npm - @real-router/angular - Versions diffs - 0.8.0 → 0.9.0 - Mend

@real-router/angular 0.8.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (43) hide show

package/README.md +183 -4
package/dist/README.md +183 -4
package/dist/fesm2022/real-router-angular-ssr.mjs +323 -0
package/dist/fesm2022/real-router-angular-ssr.mjs.map +1 -0
package/dist/fesm2022/real-router-angular.mjs +759 -173
package/dist/fesm2022/real-router-angular.mjs.map +1 -1
package/dist/types/real-router-angular-ssr.d.ts +227 -0
package/dist/types/real-router-angular-ssr.d.ts.map +1 -0
package/dist/types/real-router-angular.d.ts +119 -20
package/dist/types/real-router-angular.d.ts.map +1 -1
package/package.json +18 -11
package/src/components/RouteView.ts +81 -56
package/src/components/RouterErrorBoundary.ts +7 -5
package/src/directives/RealLink.ts +57 -37
package/src/directives/RealLinkActive.ts +34 -25
package/src/dom-utils/link-utils.ts +119 -7
package/src/dom-utils/route-announcer.ts +58 -2
package/src/dom-utils/scroll-restore.ts +160 -12
package/src/functions/injectIsActiveRoute.ts +9 -8
package/src/functions/injectNavigator.ts +4 -0
package/src/functions/injectOrThrow.ts +5 -1
package/src/functions/injectRoute.ts +17 -8
package/src/functions/injectRouteEnter.ts +5 -10
package/src/functions/injectRouteNode.ts +3 -0
package/src/functions/injectRouteUtils.ts +3 -0
package/src/functions/injectRouter.ts +4 -0
package/src/functions/injectRouterTransition.ts +3 -0
package/src/index.ts +14 -3
package/src/internal/buildActiveRouteOptions.ts +20 -0
package/src/internal/install.ts +77 -0
package/src/internal/subscribeSourceToSignal.ts +48 -0
package/src/providers.ts +11 -38
package/src/providersFactory.ts +298 -0
package/src/sourceToSignal.ts +10 -2
package/src/types.ts +6 -1
package/ssr/components/ClientOnly.ts +27 -0
package/ssr/components/HttpStatusCode.ts +106 -0
package/ssr/components/ServerOnly.ts +27 -0
package/ssr/functions/injectDeferred.ts +92 -0
package/ssr/functions/provideHttpStatusSink.ts +43 -0
package/ssr/ng-package.json +6 -0
package/ssr/public_api.ts +35 -0
package/ssr/utils/createHttpStatusSink.ts +61 -0

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

@@ -1,12 +1,13 @@
 import * as i0 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 { inject, DestroyRef, ApplicationRef, signal, InjectionToken, provideEnvironmentInitializer, makeEnvironmentProviders, makeStateKey, REQUEST, provideAppInitializer, TransferState, 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 { cloneRouter, getPluginApi } from '@real-router/core/api';
+import { hydrateRouter, serializeRouterState } from '@real-router/core/utils';
 import { getRouteUtils, startsWithSegment } from '@real-router/route-utils';
 import { NgTemplateOutlet } from '@angular/common';
-const NOOP_INSTANCE$2 = Object.freeze({
+const NOOP_INSTANCE$3 = Object.freeze({
     destroy: () => {
         /* no-op */
     },
@@ -34,7 +35,7 @@ const NOOP_INSTANCE$2 = Object.freeze({
  */
 function createDirectionTracker(router) {
     if (typeof document === "undefined") {
-        return NOOP_INSTANCE$2;
+        return NOOP_INSTANCE$3;
     }
     let popstateFlag = false;
     document.documentElement.dataset.navDirection = "forward";
@@ -69,7 +70,24 @@ const SAFARI_READY_DELAY = 100;
 const ANNOUNCER_ATTR = "data-real-router-announcer";
 const INTERNAL_ROUTE_PREFIX = "@@";
 const VISUALLY_HIDDEN = "position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);clip-path:inset(50%);white-space:nowrap;border:0";
+const NOOP_INSTANCE$2 = Object.freeze({
+    destroy: () => {
+        /* no-op */
+    },
+});
 function createRouteAnnouncer(router, options) {
+    // Defensive SSR / non-browser guard: in SSR (Node.js) or non-DOM
+    // environments, `document` is undefined and the announcer cannot
+    // attach its aria-live region. Return a frozen NOOP_INSTANCE — same
+    // pattern as `createDirectionTracker`, `createScrollRestoration`, and
+    // `createViewTransitions`. Without this guard, `NavigationAnnouncer`
+    // component construction would throw `ReferenceError: document is not
+    // defined` under `@angular/ssr` rendering, tearing down the whole SSR
+    // bootstrap. Closes review-2026-05-10 §5.10 ⛔ "NavigationAnnouncer
+    // SSR mode" MED.
+    if (typeof document === "undefined") {
+        return NOOP_INSTANCE$2;
+    }
     const prefix = options?.prefix ?? "Navigated to ";
     const getCustomText = options?.getAnnouncementText;
     let isInitialNavigation = true;
@@ -150,7 +168,19 @@ function getOrCreateAnnouncer() {
     element.setAttribute("aria-live", "assertive");
     element.setAttribute("aria-atomic", "true");
     element.setAttribute(ANNOUNCER_ATTR, "");
-    document.body.prepend(element);
+    // Defensive SSR / pre-`<body>` guard: in some environments (early
+    // injection, deferred-body documents, certain SSR rehydration paths)
+    // `document.body` can be null when the announcer is constructed.
+    // `document.body.prepend(...)` would throw `TypeError: Cannot read
+    // properties of null`, tearing down the consumer's RouterProvider /
+    // NavigationAnnouncer mount. Fallback to `documentElement` keeps the
+    // announcer working for SR users; visual-hidden styling means there is
+    // no visible artifact regardless of mount point.
+    //
+    // TS dom lib types `document.body` as `HTMLElement` (non-null), but
+    // runtime can return null per spec. The `as` cast narrows the type to
+    // include null so the `??` short-circuit is type-safe.
+    (document.body ?? document.documentElement).prepend(element);
     return element;
 }
 function removeAnnouncer() {
@@ -158,7 +188,27 @@ function removeAnnouncer() {
 }
 function resolveText(route, prefix, getCustomText, h1) {
     if (getCustomText) {
-        return getCustomText(route);
+        try {
+            const customText = getCustomText(route);
+            // Mini-sprint E.4 (audit-5 §4.2 #4) — empty-string fallback.
+            // A consumer pattern like
+            //   getAnnouncementText: (route) => myMap[route.name] ?? ""
+            // returns `""` for routes outside the map. The subscribe loop
+            // then sees an empty text and silently no-announces — screen
+            // readers stay quiet without any signal to the developer. Treat
+            // a falsy custom result (`""` / `null` / `undefined`) as
+            // "consumer doesn't have a name for this route" and fall through
+            // to the default resolution chain (h1 → title → route name).
+            if (customText) {
+                return customText;
+            }
+        }
+        catch (error) {
+            // A throwing consumer callback inside the router's subscribe loop
+            // would tear down sibling listeners — log and fall through to the
+            // built-in resolution chain so the announcer keeps working.
+            console.error("[real-router] getAnnouncementText threw; falling back to default resolution.", error);
+        }
     }
     const h1Text = (h1?.textContent ?? "").trim();
     const routeName = route.name.startsWith(INTERNAL_ROUTE_PREFIX)
@@ -201,20 +251,36 @@ function createScrollRestoration(router, options) {
     const getContainer = options?.scrollContainer;
     const behavior = options?.behavior ?? "auto";
     const storageKey = options?.storageKey ?? DEFAULT_STORAGE_KEY;
+    // Write-through in-memory cache: parse sessionStorage once per provider
+    // mount, then mutate in-memory. Avoids a JSON.parse + JSON.stringify pair
+    // on every subscribeLeave / pagehide event.
+    let store;
     const loadStore = () => {
+        if (store !== undefined) {
+            return store;
+        }
         try {
             const raw = sessionStorage.getItem(storageKey);
-            return raw ? JSON.parse(raw) : {};
+            store = raw ? JSON.parse(raw) : {};
         }
         catch {
-            return {};
+            store = {};
         }
+        return store;
     };
     const putPos = (key, pos) => {
         try {
-            const store = loadStore();
-            store[key] = pos;
-            sessionStorage.setItem(storageKey, JSON.stringify(store));
+            const cached = loadStore();
+            // Skip-same-value: when a route is left at the same scroll position it
+            // already holds in the cache (e.g. tab-switching without scrolling),
+            // both the in-memory write and the JSON.stringify + setItem pair are
+            // no-ops. Eliminates redundant serialization on the navigation hot
+            // path for the common "click tabs without scrolling" case.
+            if (cached[key] === pos) {
+                return;
+            }
+            cached[key] = pos;
+            sessionStorage.setItem(storageKey, JSON.stringify(cached));
         }
         catch {
             // Ignore quota / security errors.
@@ -285,6 +351,27 @@ function createScrollRestoration(router, options) {
         writePos(0);
     };
     let destroyed = false;
+    let unserializableWarned = false;
+    // `keyOf` defers to `canonicalJson` which calls `JSON.stringify`. Two
+    // realistic inputs blow up the serializer and would otherwise crash the
+    // subscribe callback (taking scroll-restore offline for the whole session):
+    //   - `BigInt` params → `TypeError: Do not know how to serialize a BigInt`
+    //   - cyclic params (reactive proxies, DOM-ref back-pointers) → stack
+    //     overflow.
+    // The defensive wrapper drops capture/restore for that specific navigation
+    // and warns once per provider — the rest of the cache stays usable.
+    const safeKeyOf = (state) => {
+        try {
+            return keyOf(state);
+        }
+        catch {
+            if (!unserializableWarned) {
+                unserializableWarned = true;
+                console.error(`[real-router] scroll-restore: route "${state.name}" has params that cannot be canonicalized (e.g. BigInt or cyclic structure). Scroll position will not be captured or restored for this route.`);
+            }
+            return null;
+        }
+    };
     const unsubscribe = router.subscribe(({ route, previousRoute }) => {
         const nav = route.context
             .navigation;
@@ -292,7 +379,10 @@ function createScrollRestoration(router, options) {
         // previousRoute is undefined and capture is naturally skipped. The
         // pre-refresh position was already persisted via pagehide.
         if (previousRoute) {
-            putPos(keyOf(previousRoute), readPos());
+            const prevKey = safeKeyOf(previousRoute);
+            if (prevKey !== null) {
+                putPos(prevKey, readPos());
+            }
         }
         // Single rAF so DOM is committed before we read anchors / write scroll.
         // Guard against destroy() racing with the callback.
@@ -310,7 +400,8 @@ function createScrollRestoration(router, options) {
             if (nav.direction === "back" ||
                 nav.navigationType === "traverse" ||
                 nav.navigationType === "reload") {
-                writePos(loadStore()[keyOf(route)] ?? 0);
+                const key = safeKeyOf(route);
+                writePos(key === null ? 0 : (loadStore()[key] ?? 0));
                 return;
             }
             scrollToHashOrTop(route);
@@ -319,7 +410,10 @@ function createScrollRestoration(router, options) {
     const onPageHide = () => {
         const current = router.getState();
         if (current) {
-            putPos(keyOf(current), readPos());
+            const key = safeKeyOf(current);
+            if (key !== null) {
+                putPos(key, readPos());
+            }
         }
     };
     globalThis.addEventListener("pagehide", onPageHide);
@@ -340,15 +434,103 @@ function createScrollRestoration(router, options) {
         },
     };
 }
+/**
+ * Internal cache-key builder for scroll-position storage.
+ *
+ * **Exported for testing only — not part of the public API** (intentionally
+ * excluded from `index.ts` barrel). Adapter property tests import it via
+ * the direct path to lock the `(name, canonicalJson(params))` key shape
+ * as a regression guard (§8b H20 / audit-2026-05-16 #S3). A change to
+ * key format would silently lose scroll positions across an upgrade —
+ * the test set is the contract.
+ *
+ * ## Identity-based memoization (audit-2026-05-17 §8b #2)
+ *
+ * `State` objects emitted by core are frozen per-navigation: their
+ * `name` / `params` are immutable for the lifetime of the snapshot, and
+ * any change produces a new `State` reference. A `WeakMap<State, string>`
+ * therefore safely caches the canonicalised key by identity — repeat
+ * `keyOf(state)` calls on the same snapshot (typical on
+ * back/forward/traverse where the same prior `State` is re-emitted)
+ * skip the recursive `canonicalJson` pass entirely.
+ *
+ * The cache key is the `State` reference, so entries auto-release when
+ * the snapshot is GC'd — no eviction needed.
+ */
+const KEY_CACHE = new WeakMap();
 function keyOf(state) {
-    return `${state.name}:${canonicalJson(state.params)}`;
+    const cached = KEY_CACHE.get(state);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const key = `${state.name}:${canonicalJson(state.params)}`;
+    KEY_CACHE.set(state, key);
+    return key;
 }
+/**
+ * Stable JSON serializer with sorted object keys.
+ *
+ * **Exported for testing only — not part of the public API** (intentionally
+ * excluded from `index.ts` barrel). Adapter property tests import it via
+ * the direct path to lock the key-order-insensitive property
+ * (`canonicalJson({a:1,b:2}) === canonicalJson({b:2,a:1})`).
+ *
+ * ## Divergence from `@real-router/sources/canonicalJson` — by design
+ *
+ * Two independent implementations live in the monorepo:
+ *
+ * - **`shared/dom-utils/scroll-restore.canonicalJson`** (this file) — scroll
+ *   cache key builder. Uses `localeCompare` and a plain-object accumulator;
+ *   tolerates `__proto__`-keyed inputs only insofar as `JSON.stringify`'s
+ *   replacer happens to sort them; relies on `JSON.stringify`'s native cycle
+ *   detector. Designed to be cheap on the navigation hot path. The
+ *   surrounding [[safeKeyOf]] wrapper catches the two crash inputs (`BigInt`,
+ *   cyclic) and skips the offending capture/restore.
+ *
+ * - **`@real-router/sources/canonicalJson`** — sources cache key builder.
+ *   Uses byte-order compare (`< / >`) for locale-independence, a
+ *   `Object.create(null)` accumulator to prevent prototype pollution, and a
+ *   bespoke path-based cycle detector (the native one cannot see the cloned
+ *   graph). Throws eagerly on `Map`/`Set`/`RegExp`/cycles — the caller falls
+ *   back to a non-cached source.
+ *
+ * **They are intentionally NOT interchangeable.** Aligning them would either
+ * regress scroll-restore performance (byte-order + recursive clone is heavier
+ * per call) or weaken the sources cache (locale dependence breaks
+ * deterministic cache keys across machines). No cross-package equivalence
+ * test exists or should be added; the relationship is "different invariants,
+ * different costs, different consumers." Audit-2 / audit-2026-05-17 §2
+ * documents the choice.
+ */
 function canonicalJson(value) {
     return JSON.stringify(value, canonicalReplacer);
 }
 function canonicalReplacer(_key, val) {
+    // audit-2026-05-17 §5 MEDIUM (Sprint A.3) — function/Symbol marker.
+    // `JSON.stringify` silently drops function and symbol values from
+    // object output. Two routes that differ ONLY in a function/Symbol
+    // value would canonicalize to the same string → silent scroll-cache
+    // key collision (positions clobber each other). Replacing the value
+    // with a sentinel string breaks the collision while keeping the
+    // canonical form deterministic. The sentinels are intentionally
+    // ASCII-only and lexically distinct from valid JSON-stringified
+    // values; consumers will see `"<fn>"` / `"<sym>"` if they ever
+    // round-trip the cache key, signalling the substitution clearly.
+    if (typeof val === "function") {
+        return "<fn>";
+    }
+    if (typeof val === "symbol") {
+        return "<sym>";
+    }
     if (val !== null && typeof val === "object" && !Array.isArray(val)) {
-        const sorted = {};
+        // Null-prototype accumulator: a plain `{}` would interpret
+        // `sorted["__proto__"] = x` as a prototype assignment (silently dropped
+        // from JSON.stringify output AND a prototype-pollution vector). Mirrors
+        // the same guard in `@real-router/sources/canonicalJson`. The two
+        // implementations are still intentionally divergent (see the doc-block
+        // on [[canonicalJson]] above), but prototype-safety is non-negotiable
+        // on both. Lock-test: scrollRestoreKey.properties.ts Invariant 11.
+        const sorted = Object.create(null);
         // eslint-disable-next-line unicorn/no-array-sort -- ng-packagr uses pre-ES2023 lib; toSorted unavailable
         const keys = Object.keys(val).sort((left, right) => left.localeCompare(right));
         for (const key of keys) {
@@ -485,14 +667,39 @@ function shouldNavigate(evt) {
         !evt.ctrlKey &&
         !evt.shiftKey);
 }
+// Matches a single percent-escape triple (`%` + two hex digits). Used as
+// the "already-encoded" probe in `encodeFragmentInline` below — see the
+// idempotency rationale there.
+const PERCENT_ESCAPE_PROBE = /%[\dA-Fa-f]{2}/;
 /**
  * RFC 3986 fragment encoding: preserve sub-delims (`&`, `=`, `?`, `:`),
  * encode space, `%`, control chars, non-ASCII via encodeURI; defensively
  * escape `#` (encodeURI does not). Mirrors `encodeHashFragment` in
  * `shared/browser-env/url-context.ts` — duplicated here because the
  * shared/dom-utils symlink graph does not reach shared/browser-env.
+ *
+ * **Idempotency for pre-encoded input (audit-2026-05-17 §5 MEDIUM E.1).**
+ * The doc-comment on `<Link hash>` says the value is a "decoded fragment
+ * without leading #". But realistic consumers copy hashes out of
+ * `location.hash` (which is percent-encoded) and pass them back, so the
+ * naive `encodeURI("%20")` would double-encode into `"%2520"` and break
+ * anchor lookup. We detect a percent-escape triple in the input and, if
+ * present, decode + re-encode for idempotency. Malformed `%XX` (e.g.
+ * `"%2"` or `"%ZZ"`) makes `decodeURIComponent` throw — in that case we
+ * fall through to plain `encodeURI`, which never throws.
  */
 function encodeFragmentInline(decoded) {
+    if (PERCENT_ESCAPE_PROBE.test(decoded)) {
+        try {
+            const roundtrip = decodeURIComponent(decoded);
+            return encodeURI(roundtrip).replaceAll("#", "%23");
+        }
+        catch {
+            // Malformed `%XX` — fall through to the plain encoding path.
+            // encodeURI does not throw on malformed escapes; it treats the
+            // `%` as a literal and percent-encodes it (`%2` → `%252`).
+        }
+    }
     return encodeURI(decoded).replaceAll("#", "%23");
 }
 /**
@@ -518,11 +725,28 @@ function buildHref(router, routeName, routeParams, options) {
         const buildUrl = router.buildUrl;
         if (buildUrl) {
             const url = buildUrl(routeName, routeParams, normHash === undefined ? undefined : { hash: normHash });
-            if (url !== undefined) {
+            // Accept only non-empty strings. The BuildUrlFn type contract is
+            // `string | undefined`, but defensive against:
+            //   - `""` (empty string) → would render `<a href="">`, which resolves
+            //     to the current page URL → silent self-navigation on click.
+            //   - `null` (type-contract violation) → would render `<a href={null}>`,
+            //     stringified to `"null"` in some renderers.
+            // Either case falls through to the `router.buildPath` fallback below.
+            if (typeof url === "string" && url.length > 0) {
                 return url;
             }
         }
         const path = router.buildPath(routeName, routeParams);
+        // Symmetric to the buildUrl guard above (#S1 audit, Invariant 12).
+        // `router.buildPath` is typed `string`, but defends against:
+        //   - `""` (empty string) — would render `<a href="">`, which resolves
+        //     to the current page URL → silent self-navigation on click.
+        //   - non-string type-contract violations from custom path-matchers.
+        // Both yield `undefined` (renderer drops the attribute) with a warning.
+        if (typeof path !== "string" || path.length === 0) {
+            console.error(`[real-router] Route "${routeName}" yielded an empty path. The element will render without an href attribute.`);
+            return undefined;
+        }
         return normHash ? `${path}#${encodeFragmentInline(normHash)}` : path;
     }
     catch {
@@ -548,8 +772,25 @@ function navigateWithHash(router, routeName, routeParams, hash, extraOptions) {
     }
     return router.navigate(routeName, routeParams, opts);
 }
+// Match-any-whitespace regex shared across calls. RegExp literals at
+// call-site recompile in some engines; lifting it avoids that microcost
+// for the slow-path branch.
+const WHITESPACE_PROBE = /\s/;
+const WHITESPACE_SPLIT = /\S+/g;
 function parseTokens(value) {
-    return value ? (value.match(/\S+/g) ?? []) : [];
+    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
+    // regex match and Array result allocation: a literal `[value]` works
+    // because the slow-path `match(/\S+/g)` would return exactly `[value]`
+    // for the same input. PBT lock: linkUtils.properties.ts Invariant 13.
+    if (!WHITESPACE_PROBE.test(value)) {
+        return [value];
+    }
+    return value.match(WHITESPACE_SPLIT) ?? [];
 }
 function buildActiveClassName(isActive, activeClassName, baseClassName) {
     if (isActive && activeClassName) {
@@ -572,6 +813,29 @@ function buildActiveClassName(isActive, activeClassName, baseClassName) {
     }
     return baseClassName ?? undefined;
 }
+/**
+ * One-level structural equality using `Object.is` per key.
+ *
+ * **String-keyed properties only (Mini-sprint E.3 — audit-5 §4.2 #3).**
+ * Implementation walks `Object.keys()` which by spec returns only
+ * enumerable own STRING keys. Symbol-keyed properties — created via
+ * `obj[Symbol("brand")] = value` or `{ [Symbol(...)]: value }` — are
+ * NOT compared. Two records that differ only in a Symbol-keyed value
+ * will compare as equal.
+ *
+ * This is intentional: route params and Link options are documented as
+ * string-keyed primitives (string | number | boolean) — Symbol-keyed
+ * metadata (e.g. brand markers, private state) doesn't belong in a
+ * cache-key comparison. Switching to `Reflect.ownKeys()` would extend
+ * the contract to symbols at the cost of one extra allocation per call
+ * (Reflect.ownKeys composes string-keys + symbol-keys arrays). If a
+ * consumer relies on symbol-keyed metadata for navigation
+ * disambiguation, they should encode it into a string key instead.
+ *
+ * Mirrors React's `shallowEqual` (packages/shared/shallowEqual.js) in
+ * both the string-keys-only semantics and the `hasOwnProperty` guard
+ * below.
+ */
 function shallowEqual(prev, next) {
     if (Object.is(prev, next)) {
         return true;
@@ -586,7 +850,11 @@ function shallowEqual(prev, next) {
     const prevRecord = prev;
     const nextRecord = next;
     for (const key of prevKeys) {
-        if (!Object.is(prevRecord[key], nextRecord[key])) {
+        // hasOwnProperty guard: without it, a key missing in `next` reads as
+        // `undefined` and falsely matches `prev[key] === undefined`. Same shape
+        // as React's shallowEqual (packages/shared/shallowEqual.js).
+        if (!Object.prototype.hasOwnProperty.call(next, key) ||
+            !Object.is(prevRecord[key], nextRecord[key])) {
             return false;
         }
     }
@@ -596,8 +864,23 @@ function applyLinkA11y(element) {
     if (!element) {
         return;
     }
-    if (element instanceof HTMLAnchorElement ||
-        element instanceof HTMLButtonElement) {
+    // Cross-realm safety (audit-2026-05-17 §5 HIGH #4):
+    // `instanceof HTMLAnchorElement` compares against the constructor from
+    // the CURRENT realm. An element created in a different window (iframe
+    // contentDocument, micro-frontend, embedded widget) fails the check
+    // even when it IS a real anchor — the helper would then inject
+    // role="link" + tabindex="0" on top of native anchor semantics,
+    // breaking screen reader output ("link link") and focus order.
+    //
+    // tagName is realm-agnostic and is uppercase for HTML-namespaced
+    // elements in any document. SVG `<a>` has lowercase tagName plus a
+    // different prototype (SVGAElement) — skipping it here is wrong by
+    // accident: SVG anchors don't have keyboard activation semantics the
+    // helper would add. But they also don't reach this helper in
+    // practice (router Link components emit HTML anchors). Lock the
+    // uppercase compare to keep the contract narrow.
+    const tag = element.tagName;
+    if (tag === "A" || tag === "BUTTON") {
         return;
     }
     if (!element.hasAttribute("role")) {
@@ -608,6 +891,65 @@ function applyLinkA11y(element) {
     }
 }
+/**
+ * Shared installation helpers for `provideRealRouter` and
+ * `provideRealRouterFactory`. Must be called inside the body of a
+ * `provideEnvironmentInitializer(() => { ... })` callback so the active
+ * injection context resolves `ROUTER`, `ApplicationRef`, and `DestroyRef`.
+ *
+ * Closes review-2026-05-10 §8.1 MED — eliminates duplicate wiring between
+ * `providers.ts` and `providersFactory.ts` (high drift risk noted in the
+ * audit: the comment blocks were identical down to the punctuation).
+ */
+function installScrollRestoration(options) {
+    const router = inject(ROUTER);
+    const sr = createScrollRestoration(router, options);
+    inject(DestroyRef).onDestroy(() => {
+        sr.destroy();
+    });
+}
+function installViewTransitions() {
+    const router = inject(ROUTER);
+    // Feature-detect `document.startViewTransition` once at install time. The
+    // `appRef.tick()` listener exists ONLY to feed Angular's zoneless CD into
+    // the VT utility's `setTimeout(0)`-driven snapshot capture (see comment
+    // below). When `startViewTransition` is unavailable (Firefox as of 2026-04,
+    // SSR, older browsers), `createViewTransitions` short-circuits to its
+    // frozen NOOP_INSTANCE — no leave subscriber registered, no
+    // `setTimeout(0)` invariant to satisfy. Installing the per-navigation
+    // tick listener anyway would force a synchronous CD pass on every
+    // navigation with zero benefit, doubling CD work in zoneless apps.
+    // Closes review-2026-05-10 §8.2 MED (view-transitions hot path).
+    const vtAvailable = typeof document !== "undefined" &&
+        typeof document.startViewTransition === "function";
+    let offTick;
+    if (vtAvailable) {
+        // 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 app was the canary).
+        //
+        // Subscribers fire in registration order; this one runs BEFORE
+        // `createViewTransitions` registers its own subscriber, guaranteeing CD
+        // completes first.
+        const appRef = inject(ApplicationRef);
+        offTick = router.subscribe(() => {
+            appRef.tick();
+        });
+    }
+    const vt = createViewTransitions(router);
+    inject(DestroyRef).onDestroy(() => {
+        offTick?.();
+        vt.destroy();
+    });
+}
 /** Must be called within an injection context (constructor, field initializer, runInInjectionContext). */
 function sourceToSignal(source) {
     const sig = signal(source.getSnapshot(), ...(ngDevMode ? [{ debugName: "sig" }] : /* istanbul ignore next */ []));
@@ -616,8 +958,17 @@ function sourceToSignal(source) {
         sig.set(source.getSnapshot());
     });
     destroyRef.onDestroy(() => {
-        unsubscribe();
-        source.destroy();
+        // `try/finally` guarantees `source.destroy()` runs even if `unsubscribe`
+        // throws. Cached sources from `@real-router/sources` keep `destroy()` as
+        // a no-op (so they survive multi-consumer teardown), but non-cached
+        // sources rely on this call to release their router subscription —
+        // skipping it on an unsubscribe throw would leak the listener.
+        try {
+            unsubscribe();
+        }
+        finally {
+            source.destroy();
+        }
     });
     return sig.asReadonly();
 }
@@ -627,6 +978,11 @@ const NAVIGATOR = new InjectionToken("NAVIGATOR");
 const ROUTE = new InjectionToken("ROUTE");
 function provideRealRouter(router, options) {
     const navigator = getNavigator(router);
+    // `Parameters<typeof makeEnvironmentProviders>[0]` is the actual union
+    // `(Provider | EnvironmentProviders | EnvironmentProviders[])[]` —
+    // `provideEnvironmentInitializer()` returns `EnvironmentProviders`, so the
+    // narrower `Provider[]` would force a cast at every push (review §8a — the
+    // proposed Provider[] swap was retracted after discovering this).
     const providers = [
         { provide: ROUTER, useValue: router },
         { provide: NAVIGATOR, useValue: navigator },
@@ -641,66 +997,213 @@ function provideRealRouter(router, options) {
     if (options?.scrollRestoration) {
         const scrollOpts = options.scrollRestoration;
         providers.push(provideEnvironmentInitializer(() => {
-            const sr = createScrollRestoration(router, scrollOpts);
-            inject(DestroyRef).onDestroy(() => {
-                sr.destroy();
-            });
+            installScrollRestoration(scrollOpts);
         }));
     }
     if (options?.viewTransitions === true) {
+        providers.push(provideEnvironmentInitializer(installViewTransitions));
+    }
+    return makeEnvironmentProviders(providers);
+}
+/**
+ * `TransferState` key carrying the SSR-resolved router state from server to
+ * client as an XSS-safe JSON string (produced by `serializeRouterState`).
+ * Populated server-side by the `provideAppInitializer` callback after
+ * `router.start()` resolves; consumed client-side after hydration. Mirrors the
+ * `<script>window.__SSR_STATE__ = …</script>` pattern used by every other
+ * adapter — Angular's idiomatic transport is `TransferState` (#599).
+ *
+ * Stored as `string`: `serializeRouterState(state)` already produces JSON;
+ * `hydrateRouter(router, json)` accepts a JSON string and parses it once
+ * internally. Storing the parsed object would force a double round-trip
+ * (TransferState wraps every value in JSON for transport).
+ *
+ * Internal implementation detail. Not re-exported.
+ */
+const ROUTER_STATE_KEY = makeStateKey("@real-router/angular:ssrState");
+/**
+ * `provideRealRouterFactory` — environment providers for SSR / SSG scenarios.
+ *
+ * Unlike `provideRealRouter(router)` (single instance via `useValue`), this
+ * factory uses `useFactory` to produce a per-request router clone:
+ *
+ * 1. Reads Angular's `REQUEST` token (`{ optional: true }`).
+ * 2. Calls `cloneRouter(baseRouter, deps?.(request))` to create a request-scoped clone.
+ * 3. Applies plugins (`plugins` array or `plugins(request)` factory).
+ * 4. Registers `provideAppInitializer` that calls `await router.start(url)`.
+ * 5. Schedules `router.dispose()` via `DestroyRef.onDestroy` — the request
+ *    Injector is destroyed after the response is sent, releasing all
+ *    subscriptions and plugins.
+ *
+ * Use cases:
+ * - Angular SSR with `@angular/ssr` (`outputMode: "server"`).
+ * - SSG build-time render via `renderApplication` + `platformProviders` `REQUEST` mock.
+ * - Multi-tenant request-scoped routing.
+ *
+ * Existing single-instance scenarios (SPA, SSG client after hydration) continue
+ * to use `provideRealRouter(router)` — both APIs ship in parallel.
+ *
+ * @param options - Factory configuration — see `RealRouterFactoryOptions`.
+ * @returns `EnvironmentProviders` to spread into `ApplicationConfig.providers`.
+ */
+function provideRealRouterFactory(options) {
+    const { baseRouter, plugins, deps, scrollRestoration, viewTransitions } = options;
+    const providers = [
+        {
+            provide: ROUTER,
+            useFactory: () => {
+                const request = inject(REQUEST, { optional: true });
+                const requestDeps = deps?.(request);
+                const router = cloneRouter(baseRouter, requestDeps);
+                const pluginList = typeof plugins === "function" ? plugins(request) : plugins;
+                if (pluginList && pluginList.length > 0) {
+                    // Variadic — `usePlugin` accepts `(PluginFactory<D> | false | null | undefined)[]`.
+                    router.usePlugin(...pluginList);
+                }
+                // Per-request cleanup. The application Injector is destroyed:
+                // - On server: after `writeResponseToNodeResponse` finishes the response
+                //   (request scope ends).
+                // - On client: at `ApplicationRef.destroy` (rare in SPA, common in TestBed).
+                // - In SSG build: after each `renderApplication` resolves.
+                inject(DestroyRef).onDestroy(() => {
+                    router.dispose();
+                });
+                return router;
+            },
+        },
+        {
+            provide: NAVIGATOR,
+            useFactory: () => getNavigator(inject(ROUTER)),
+        },
+        {
+            provide: ROUTE,
+            useFactory: () => {
+                const router = inject(ROUTER);
+                return {
+                    routeState: sourceToSignal(createRouteSource(router)),
+                    navigator: inject(NAVIGATOR),
+                };
+            },
+        },
+        // Async bootstrap — runs before the first component renders. Three
+        // branches based on TransferState population:
+        //
+        //   1. **Client after hydration** — server populated TransferState with
+        //      the SSR-resolved router state. Consume it via `hydrateRouter`,
+        //      which deposits the parsed state into the one-shot
+        //      `RouterInternals.hydrationState` scratchpad before invoking
+        //      `router.start(state.path)`. SSR loader plugins
+        //      (`@real-router/ssr-data-plugin`, `@real-router/rsc-server-plugin`)
+        //      read the scratchpad and skip the loader on first paint — parity
+        //      with the other 5 adapters that consume `<script>__SSR_STATE__</script>` (#596, #599).
+        //
+        //   2. **Server / SSG** — TransferState empty; run the regular
+        //      `router.start(path)`. After it resolves, write the serialized
+        //      state back into TransferState so the matching client run lands
+        //      in branch 1. Angular's `TransferState` infrastructure
+        //      (provided by `provideClientHydration()`) carries this blob to
+        //      the client as a `<script id="ng-state">` payload.
+        //
+        //   3. **Pure CSR** — TransferState empty (never populated by a server
+        //      pass), and `inject(REQUEST, { optional: true })` returns null.
+        //      Falls into the same `router.start(path)` branch as server-side
+        //      but skips the TransferState write (no client to hand off to).
+        //
+        // Errors propagate (Option A from RFC §10): the bootstrap fails and the
+        // server returns 500. Custom error pages should be wired via
+        // `RouterErrorBoundary` on subsequent renders.
+        provideAppInitializer(async () => {
+            const router = inject(ROUTER);
+            const request = inject(REQUEST, { optional: true });
+            const transferState = inject(TransferState);
+            const ssrJson = transferState.get(ROUTER_STATE_KEY, null);
+            if (ssrJson !== null) {
+                // Branch 1: client after hydration — reuse server-resolved state.
+                await hydrateRouter(router, ssrJson);
+                // One-shot semantic, parity with `delete window.__SSR_STATE__`.
+                transferState.remove(ROUTER_STATE_KEY);
+                return;
+            }
+            // Branches 2 & 3: regular start.
+            // Browser-plugin's `start` interceptor (when registered) wraps this call
+            // with location-derived path. We always pass an explicit string — the
+            // interceptor uses the explicit value because `next(path ?? location)`
+            // short-circuits when `path` is non-nullish.
+            const path = deriveStartPath(request);
+            const state = await router.start(path);
+            if (request !== null) {
+                // Branch 2: running inside `@angular/ssr`'s request handler — write
+                // serialized state to TransferState so the matching client run can
+                // skip the loader on first paint.
+                transferState.set(ROUTER_STATE_KEY, serializeRouterState(state));
+            }
+        }),
+    ];
+    if (scrollRestoration) {
         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();
-            });
+            installScrollRestoration(scrollRestoration);
         }));
     }
+    if (viewTransitions === true) {
+        providers.push(provideEnvironmentInitializer(installViewTransitions));
+    }
     return makeEnvironmentProviders(providers);
 }
+/**
+ * Derive the path passed to `router.start(path)`:
+ * - Server / SSG: `request.url` → pathname + search.
+ * - Client: `window.location` if available.
+ * - Fallback: `"/"` (only reachable in synthetic non-browser non-SSR setups).
+ */
+function deriveStartPath(request) {
+    if (request) {
+        const url = new URL(request.url);
+        return url.pathname + url.search;
+    }
+    if (typeof globalThis.window !== "undefined") {
+        return globalThis.location.pathname + globalThis.location.search;
+    }
+    return "/";
+}
 function injectOrThrow(token, fnName) {
     const value = inject(token, { optional: true });
-    if (!value) {
+    // Explicit null / undefined check — falsy guard would misfire on
+    // legitimately falsy values (`0`, `""`, `false`) if the token were ever
+    // typed for primitives. Today all our tokens hold object instances, but
+    // pinning the check keeps the function safe for future typing changes.
+    if (value === null || value === undefined) {
         throw new Error(`${fnName} must be used within a provideRealRouter context`);
     }
     return value;
 }
 function injectRouter() {
+    assertInInjectionContext(injectRouter);
     return injectOrThrow(ROUTER, "injectRouter");
 }
 function injectNavigator() {
+    assertInInjectionContext(injectNavigator);
     return injectOrThrow(NAVIGATOR, "injectNavigator");
 }
 function injectRoute() {
+    assertInInjectionContext(injectRoute);
     const signals = injectOrThrow(ROUTE, "injectRoute");
-    if (!signals.routeState().route) {
+    // Read the snapshot once: the signal is reactive, but the throw-guard
+    // and any future use of the snapshot within this call should observe the
+    // SAME value to avoid races.
+    const snapshot = signals.routeState();
+    if (!snapshot.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) {
+    assertInInjectionContext(injectRouteNode);
     const router = injectRouter();
     const navigator = getNavigator(router);
     const source = createRouteNodeSource(router, nodeName);
@@ -709,26 +1212,37 @@ function injectRouteNode(nodeName) {
 }
 function injectRouteUtils() {
+    assertInInjectionContext(injectRouteUtils);
     const router = injectRouter();
     return getRouteUtils(getPluginApi(router).getTree());
 }
 function injectRouterTransition() {
+    assertInInjectionContext(injectRouterTransition);
     const router = injectRouter();
     const source = getTransitionSource(router);
     return sourceToSignal(source);
 }
+/**
+ * Build the `options` literal for `createActiveRouteSource` while honoring
+ * `exactOptionalPropertyTypes` — the type forbids passing `{ hash: undefined }`
+ * literally (#532), so callers must conditionally include the `hash` key only
+ * when a value was provided.
+ *
+ * Used by `RealLink`, `RealLinkActive`, and `injectIsActiveRoute` — extracted
+ * from three identical ternaries (review-2026-05-16 §8a LOW).
+ */
+function buildActiveRouteOptions(strict, ignoreQueryParams, hash) {
+    return hash === undefined
+        ? { strict, ignoreQueryParams }
+        : { strict, ignoreQueryParams, hash };
+}
 function injectIsActiveRoute(routeName, params, options) {
+    assertInInjectionContext(injectIsActiveRoute);
     const router = injectRouter();
-    const strict = options?.strict ?? false;
-    const ignoreQueryParams = options?.ignoreQueryParams ?? true;
-    const hash = options?.hash;
-    // exactOptionalPropertyTypes forbids `{ hash: undefined }` literally — pass
-    // the field only when a value was provided. (#532)
-    const source = createActiveRouteSource(router, routeName, params, hash === undefined
-        ? { strict, ignoreQueryParams }
-        : { strict, ignoreQueryParams, hash });
+    const source = createActiveRouteSource(router, routeName, params, buildActiveRouteOptions(options?.strict ?? false, options?.ignoreQueryParams ?? true, options?.hash));
     return sourceToSignal(source);
 }
@@ -870,7 +1384,6 @@ 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:
@@ -880,23 +1393,19 @@ function injectRouteEnter(handler, options) {
         //   - **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) {
+        // `previousRoute` is guaranteed populated whenever `route.transition.from`
+        // is set — core writes them together. The dead-code throw-guard that used
+        // to live here (review §8a LOW) is removed; the narrowing below is the
+        // type-safe equivalent and avoids the no-non-null-assertion lint.
+        if (!previousRoute) {
             return;
         }
-        /* v8 ignore stop */
-        lastHandledRoute = route;
         handler({ route, previousRoute });
     });
 }
@@ -904,60 +1413,131 @@ function injectRouteEnter(handler, options) {
 class RouteMatch {
     routeMatch = input.required(...(ngDevMode ? [{ debugName: "routeMatch" }] : /* istanbul ignore next */ []));
     templateRef = inject(TemplateRef);
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: RouteMatch, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.8", type: RouteMatch, isStandalone: true, selector: "ng-template[routeMatch]", inputs: { routeMatch: { classPropertyName: "routeMatch", publicName: "routeMatch", isSignal: true, isRequired: true, transformFunction: null } }, ngImport: i0 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: RouteMatch, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.9", type: RouteMatch, isStandalone: true, selector: "ng-template[routeMatch]", inputs: { routeMatch: { classPropertyName: "routeMatch", publicName: "routeMatch", isSignal: true, isRequired: true, transformFunction: null } }, ngImport: i0 });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: RouteMatch, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: RouteMatch, decorators: [{
             type: Directive,
             args: [{ selector: "ng-template[routeMatch]" }]
         }], propDecorators: { routeMatch: [{ type: i0.Input, args: [{ isSignal: true, alias: "routeMatch", required: true }] }] } });
 class RouteNotFound {
     templateRef = inject(TemplateRef);
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: RouteNotFound, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "21.2.8", type: RouteNotFound, isStandalone: true, selector: "ng-template[routeNotFound]", ngImport: i0 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: RouteNotFound, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "21.2.9", type: RouteNotFound, isStandalone: true, selector: "ng-template[routeNotFound]", ngImport: i0 });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: RouteNotFound, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: RouteNotFound, decorators: [{
             type: Directive,
             args: [{ selector: "ng-template[routeNotFound]" }]
         }] });
 class RouteSelf {
     templateRef = inject(TemplateRef);
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: RouteSelf, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "21.2.8", type: RouteSelf, isStandalone: true, selector: "ng-template[routeSelf]", ngImport: i0 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: RouteSelf, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "21.2.9", type: RouteSelf, isStandalone: true, selector: "ng-template[routeSelf]", ngImport: i0 });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: RouteSelf, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: RouteSelf, decorators: [{
             type: Directive,
             args: [{ selector: "ng-template[routeSelf]" }]
         }] });
-const EMPTY_SNAPSHOT = Object.freeze({
+/**
+ * Subscribe a `RouterSource<T>` to a write-callback and return a cleanup
+ * function. The shape is the per-effect-run pattern that `RealLink`,
+ * `RealLinkActive`, and `RouteView` all share inside their constructor
+ * `effect(...)` (review-2026-05-16 §8a MEDIUM — identical 8-line block
+ * repeated in 3 directives):
+ *
+ *   1. Read initial snapshot and apply it via `onSnapshot(snap)`.
+ *   2. Subscribe — every subsequent emission calls `onSnapshot(snap)` again.
+ *   3. Return a cleanup that unsubscribes and destroys the source. For
+ *      cached factories from `@real-router/sources` (`createActiveRouteSource`,
+ *      `createRouteNodeSource`, `getTransitionSource`, `getErrorSource`,
+ *      `createDismissableError`) `destroy()` is a no-op on the shared
+ *      wrapper, so this helper is safe to invoke from rapid effect re-runs
+ *      under signal-input changes.
+ *
+ * Callers pass the result to `onCleanup(...)` from Angular's `effect()`.
+ *
+ * @example
+ * ```ts
+ * effect((onCleanup) => {
+ *   const source = createActiveRouteSource(router, routeName(), params());
+ *   onCleanup(
+ *     subscribeSourceToSignal(source, (snap) => {
+ *       this.isActive.set(snap);
+ *       this.updateDom();
+ *     }),
+ *   );
+ * });
+ * ```
+ */
+function subscribeSourceToSignal(source, onSnapshot) {
+    onSnapshot(source.getSnapshot());
+    const unsub = source.subscribe(() => {
+        onSnapshot(source.getSnapshot());
+    });
+    return () => {
+        unsub();
+        source.destroy();
+    };
+}
+const EMPTY_SNAPSHOT = {
     route: undefined,
     previousRoute: undefined,
-});
+};
 class RouteView {
     nodeName = input("", { ...(ngDevMode ? { debugName: "nodeName" } : /* istanbul ignore next */ {}), alias: "routeNode" });
     matches = contentChildren(RouteMatch, { ...(ngDevMode ? { debugName: "matches" } : /* istanbul ignore next */ {}), descendants: true });
     selfs = contentChildren(RouteSelf, { ...(ngDevMode ? { debugName: "selfs" } : /* istanbul ignore next */ {}), descendants: true });
     notFounds = contentChildren(RouteNotFound, { ...(ngDevMode ? { debugName: "notFounds" } : /* istanbul ignore next */ {}), descendants: true });
-    activeTemplate = computed(() => {
-        const snapshot = this.routeState();
-        const route = snapshot.route;
+    activeTemplate = computed(() => this.matchedTemplate() ?? this.fallbackTemplate(), ...(ngDevMode ? [{ debugName: "activeTemplate" }] : /* istanbul ignore next */ []));
+    router = injectRouter();
+    routeState = signal(EMPTY_SNAPSHOT, ...(ngDevMode ? [{ debugName: "routeState" }] : /* istanbul ignore next */ []));
+    matchEntries = computed(() => {
+        const nodeName = this.nodeName();
+        return this.matches().map((match) => {
+            const segment = match.routeMatch();
+            return {
+                match,
+                fullSegmentName: nodeName ? `${nodeName}.${segment}` : segment,
+            };
+        });
+    }, ...(ngDevMode ? [{ debugName: "matchEntries" }] : /* istanbul ignore next */ []));
+    // The matched template (Match priority) is independent of the Self /
+    // NotFound fallback chain. Splitting the two paths into separate computeds
+    // localises re-runs: a change to `selfs()` / `notFounds()` no longer
+    // re-evaluates the Match loop (review §8a LOW — RouteView activeTemplate
+    // split).
+    matchedTemplate = computed(() => {
+        const route = this.routeState().route;
         if (!route) {
             return null;
         }
         const routeName = route.name;
-        const entries = this.matchEntries();
-        for (const { match, fullSegmentName } of entries) {
+        for (const { match, fullSegmentName } of this.matchEntries()) {
             if (startsWithSegment(routeName, fullSegmentName)) {
                 return match.templateRef;
             }
         }
-        // Self has priority over NotFound. First-wins to mirror NotFound's
-        // last-wins inversion would be inconsistent with React/Preact/Solid/Vue
-        // adapters where Self is "first wins"; Angular's contentChildren returns
-        // declaration order, so picking [0] gives first-wins.
+        return null;
+    }, ...(ngDevMode ? [{ debugName: "matchedTemplate" }] : /* istanbul ignore next */ []));
+    // Fallback chain — only consulted when `matchedTemplate()` returned `null`.
+    // Template priority: Self → NotFound. Selection rules differ on purpose:
+    //   - **Self uses first-wins** (`.at(0)`) for parity with React / Preact /
+    //     Solid / Vue, where the first matching `<Self>` token in declaration
+    //     order wins.
+    //   - **NotFound uses last-wins** (`.at(-1)`) intentionally — the fallback
+    //     should be the most-recently-declared template so that consumers can
+    //     override an inherited `<ng-template routeNotFound>` simply by
+    //     re-declaring it lower in the projected content.
+    fallbackTemplate = computed(() => {
+        const route = this.routeState().route;
+        if (!route) {
+            return null;
+        }
+        const routeName = route.name;
         if (routeName === this.nodeName()) {
             const first = this.selfs().at(0);
             if (first) {
@@ -971,39 +1551,25 @@ class RouteView {
             }
         }
         return null;
-    }, ...(ngDevMode ? [{ debugName: "activeTemplate" }] : /* istanbul ignore next */ []));
-    matchEntries = computed(() => {
-        const nodeName = this.nodeName();
-        return this.matches().map((match) => {
-            const segment = match.routeMatch();
-            return {
-                match,
-                fullSegmentName: nodeName ? `${nodeName}.${segment}` : segment,
-            };
-        });
-    }, ...(ngDevMode ? [{ debugName: "matchEntries" }] : /* istanbul ignore next */ []));
-    router = injectRouter();
-    destroyRef = inject(DestroyRef);
-    routeState = signal(EMPTY_SNAPSHOT, ...(ngDevMode ? [{ debugName: "routeState" }] : /* istanbul ignore next */ []));
-    ngOnInit() {
-        const source = createRouteNodeSource(this.router, this.nodeName());
-        this.routeState.set(source.getSnapshot());
-        const unsub = source.subscribe(() => {
-            this.routeState.set(source.getSnapshot());
-        });
-        this.destroyRef.onDestroy(() => {
-            unsub();
-            source.destroy();
+    }, ...(ngDevMode ? [{ debugName: "fallbackTemplate" }] : /* istanbul ignore next */ []));
+    constructor() {
+        // Reactive source-creation effect (#630 fix) — see
+        // `packages/angular/CLAUDE.md` → "Directives use constructor + effect()".
+        effect((onCleanup) => {
+            const source = createRouteNodeSource(this.router, this.nodeName());
+            onCleanup(subscribeSourceToSignal(source, (snap) => {
+                this.routeState.set(snap);
+            }));
         });
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: RouteView, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.8", type: RouteView, isStandalone: true, selector: "route-view", inputs: { nodeName: { classPropertyName: "nodeName", publicName: "routeNode", isSignal: true, isRequired: false, transformFunction: null } }, queries: [{ propertyName: "matches", predicate: RouteMatch, descendants: true, isSignal: true }, { propertyName: "selfs", predicate: RouteSelf, descendants: true, isSignal: true }, { propertyName: "notFounds", predicate: RouteNotFound, descendants: true, isSignal: true }], ngImport: i0, template: `
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: RouteView, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.9", type: RouteView, isStandalone: true, selector: "route-view", inputs: { nodeName: { classPropertyName: "nodeName", publicName: "routeNode", isSignal: true, isRequired: false, transformFunction: null } }, queries: [{ propertyName: "matches", predicate: RouteMatch, descendants: true, isSignal: true }, { propertyName: "selfs", predicate: RouteSelf, descendants: true, isSignal: true }, { propertyName: "notFounds", predicate: RouteNotFound, descendants: true, isSignal: true }], ngImport: i0, template: `
     @if (activeTemplate()) {
       <ng-container [ngTemplateOutlet]="activeTemplate()!" />
     }
   `, isInline: true, dependencies: [{ kind: "directive", type: NgTemplateOutlet, selector: "[ngTemplateOutlet]", inputs: ["ngTemplateOutletContext", "ngTemplateOutlet", "ngTemplateOutletInjector"] }] });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: RouteView, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: RouteView, decorators: [{
             type: Component,
             args: [{
                     selector: "route-view",
@@ -1014,7 +1580,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImpor
   `,
                     imports: [NgTemplateOutlet],
                 }]
-        }], propDecorators: { nodeName: [{ type: i0.Input, args: [{ isSignal: true, alias: "routeNode", required: false }] }], matches: [{ type: i0.ContentChildren, args: [i0.forwardRef(() => RouteMatch), { ...{ descendants: true }, isSignal: true }] }], selfs: [{ type: i0.ContentChildren, args: [i0.forwardRef(() => RouteSelf), { ...{ descendants: true }, isSignal: true }] }], notFounds: [{ type: i0.ContentChildren, args: [i0.forwardRef(() => RouteNotFound), { ...{ descendants: true }, isSignal: true }] }] } });
+        }], ctorParameters: () => [], propDecorators: { nodeName: [{ type: i0.Input, args: [{ isSignal: true, alias: "routeNode", required: false }] }], matches: [{ type: i0.ContentChildren, args: [i0.forwardRef(() => RouteMatch), { ...{ descendants: true }, isSignal: true }] }], selfs: [{ type: i0.ContentChildren, args: [i0.forwardRef(() => RouteSelf), { ...{ descendants: true }, isSignal: true }] }], notFounds: [{ type: i0.ContentChildren, args: [i0.forwardRef(() => RouteNotFound), { ...{ descendants: true }, isSignal: true }] }] } });
 class RouterErrorBoundary {
     errorTemplate = input(...(ngDevMode ? [undefined, { debugName: "errorTemplate" }] : /* istanbul ignore next */ []));
@@ -1032,6 +1598,12 @@ class RouterErrorBoundary {
     router = injectRouter();
     snapshot = sourceToSignal(createDismissableError(this.router));
     constructor() {
+        // `effect()` registers itself with the current injection context's
+        // `DestroyRef` and tears down automatically when the component is
+        // destroyed. The earlier manual `effectRef.destroy()` wired through
+        // `inject(DestroyRef).onDestroy(...)` duplicated that built-in cleanup
+        // (audit §8.1 LOW — confirmed: no behavior change without the manual
+        // path).
         effect(() => {
             const snap = this.snapshot();
             if (snap.error) {
@@ -1043,8 +1615,8 @@ class RouterErrorBoundary {
             }
         });
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: RouterErrorBoundary, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.8", type: RouterErrorBoundary, isStandalone: true, selector: "router-error-boundary", inputs: { errorTemplate: { classPropertyName: "errorTemplate", publicName: "errorTemplate", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { onError: "onError" }, ngImport: i0, template: `
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: RouterErrorBoundary, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.9", type: RouterErrorBoundary, isStandalone: true, selector: "router-error-boundary", inputs: { errorTemplate: { classPropertyName: "errorTemplate", publicName: "errorTemplate", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { onError: "onError" }, ngImport: i0, template: `
     <ng-content />
     @if (errorContext() && errorTemplate()) {
       <ng-container
@@ -1054,7 +1626,7 @@ class RouterErrorBoundary {
     }
   `, isInline: true, dependencies: [{ kind: "directive", type: NgTemplateOutlet, selector: "[ngTemplateOutlet]", inputs: ["ngTemplateOutletContext", "ngTemplateOutlet", "ngTemplateOutletInjector"] }] });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: RouterErrorBoundary, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: RouterErrorBoundary, decorators: [{
             type: Component,
             args: [{
                     selector: "router-error-boundary",
@@ -1078,10 +1650,10 @@ class NavigationAnnouncer {
             this.announcer.destroy();
         });
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: NavigationAnnouncer, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "21.2.8", type: NavigationAnnouncer, isStandalone: true, selector: "navigation-announcer", ngImport: i0, template: "", isInline: true });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: NavigationAnnouncer, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "21.2.9", type: NavigationAnnouncer, isStandalone: true, selector: "navigation-announcer", ngImport: i0, template: "", isInline: true });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: NavigationAnnouncer, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: NavigationAnnouncer, decorators: [{
             type: Component,
             args: [{
                     selector: "navigation-announcer",
@@ -1089,6 +1661,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImpor
                 }]
         }], ctorParameters: () => [] });
+const NOOP_CATCH = () => { };
 class RealLink {
     routeName = input("", ...(ngDevMode ? [{ debugName: "routeName" }] : /* istanbul ignore next */ []));
     routeParams = input({}, ...(ngDevMode ? [{ debugName: "routeParams" }] : /* istanbul ignore next */ []));
@@ -1104,38 +1677,45 @@ class RealLink {
      */
     hash = input(undefined, ...(ngDevMode ? [{ debugName: "hash" }] : /* istanbul ignore next */ []));
     router = injectRouter();
-    destroyRef = inject(DestroyRef);
     anchor = inject(ElementRef)
         .nativeElement;
     isActive = signal(false, ...(ngDevMode ? [{ debugName: "isActive" }] : /* istanbul ignore next */ []));
+    // `href` is computed from signal inputs only — Angular's default Object.is
+    // equality already collapses repeated `string` results, so no custom
+    // comparator is required (review §8b note 3 — applies after verifying that
+    // `buildHref` returns a primitive).
     href = computed(() => {
         const hashValue = this.hash();
         return buildHref(this.router, this.routeName(), this.routeParams(), hashValue === undefined ? undefined : { hash: hashValue });
     }, ...(ngDevMode ? [{ debugName: "href" }] : /* istanbul ignore next */ []));
     prevActiveClass = "";
-    ngOnInit() {
-        // Hash-aware active state (#532): pass `hash` so that tab-style links
-        // (same routeName, different `hash` input) only mark the active variant.
-        const hashValue = this.hash();
-        const source = createActiveRouteSource(this.router, this.routeName(), this.routeParams(), hashValue === undefined
-            ? {
-                strict: this.activeStrict(),
-                ignoreQueryParams: this.ignoreQueryParams(),
-            }
-            : {
-                strict: this.activeStrict(),
-                ignoreQueryParams: this.ignoreQueryParams(),
-                hash: hashValue,
-            });
-        this.isActive.set(source.getSnapshot());
-        this.updateDom();
-        const unsub = source.subscribe(() => {
-            this.isActive.set(source.getSnapshot());
-            this.updateDom();
-        });
-        this.destroyRef.onDestroy(() => {
-            unsub();
-            source.destroy();
+    prevHref = undefined;
+    // Skip-same-value: only re-touch the DOM `class` list when the active state
+    // actually flipped. Without this, every navigation that re-fires the active
+    // source still issues a `classList.toggle` no-op (review §8b MEDIUM).
+    prevActive = undefined;
+    constructor() {
+        // Reactive source-creation effect (#630 fix) — see
+        // `packages/angular/CLAUDE.md` → "Directives use constructor + effect()".
+        // Reading signal inputs inside `effect()` re-creates the active-route
+        // source whenever any input changes; `onCleanup` tears the previous
+        // subscription down.
+        effect((onCleanup) => {
+            const source = createActiveRouteSource(this.router, this.routeName(), this.routeParams(), buildActiveRouteOptions(this.activeStrict(), this.ignoreQueryParams(), this.hash()));
+            onCleanup(subscribeSourceToSignal(source, (snap) => {
+                // Pure-href refresh: when the active flag did not change, only the
+                // href may have moved (e.g. param-only update on a parent route).
+                // Skip the classList work in that branch (review §8b MEDIUM).
+                if (snap === this.prevActive) {
+                    this.isActive.set(snap);
+                    this.updateHref();
+                    return;
+                }
+                this.prevActive = snap;
+                this.isActive.set(snap);
+                this.updateHref();
+                this.updateActiveClass();
+            }));
         });
     }
     onClick(event) {
@@ -1143,13 +1723,16 @@ class RealLink {
             return;
         }
         event.preventDefault();
-        navigateWithHash(this.router, this.routeName(), this.routeParams(), this.hash(), this.routeOptions()).catch(() => { });
+        navigateWithHash(this.router, this.routeName(), this.routeParams(), this.hash(), this.routeOptions()).catch(NOOP_CATCH);
     }
-    updateDom() {
+    updateHref() {
         const href = this.href();
-        if (href !== undefined) {
+        if (href !== undefined && href !== this.prevHref) {
             this.anchor.setAttribute("href", href);
         }
+        this.prevHref = href;
+    }
+    updateActiveClass() {
         const activeClass = this.activeClassName();
         if (this.prevActiveClass && this.prevActiveClass !== activeClass) {
             this.anchor.classList.remove(this.prevActiveClass);
@@ -1159,10 +1742,10 @@ class RealLink {
         }
         this.prevActiveClass = activeClass;
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: RealLink, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.8", type: RealLink, isStandalone: true, selector: "a[realLink]", inputs: { routeName: { classPropertyName: "routeName", publicName: "routeName", isSignal: true, isRequired: false, transformFunction: null }, routeParams: { classPropertyName: "routeParams", publicName: "routeParams", isSignal: true, isRequired: false, transformFunction: null }, routeOptions: { classPropertyName: "routeOptions", publicName: "routeOptions", isSignal: true, isRequired: false, transformFunction: null }, activeClassName: { classPropertyName: "activeClassName", publicName: "activeClassName", isSignal: true, isRequired: false, transformFunction: null }, activeStrict: { classPropertyName: "activeStrict", publicName: "activeStrict", isSignal: true, isRequired: false, transformFunction: null }, ignoreQueryParams: { classPropertyName: "ignoreQueryParams", publicName: "ignoreQueryParams", isSignal: true, isRequired: false, transformFunction: null }, hash: { classPropertyName: "hash", publicName: "hash", isSignal: true, isRequired: false, transformFunction: null } }, host: { listeners: { "click": "onClick($event)" } }, ngImport: i0 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: RealLink, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.9", type: RealLink, isStandalone: true, selector: "a[realLink]", inputs: { routeName: { classPropertyName: "routeName", publicName: "routeName", isSignal: true, isRequired: false, transformFunction: null }, routeParams: { classPropertyName: "routeParams", publicName: "routeParams", isSignal: true, isRequired: false, transformFunction: null }, routeOptions: { classPropertyName: "routeOptions", publicName: "routeOptions", isSignal: true, isRequired: false, transformFunction: null }, activeClassName: { classPropertyName: "activeClassName", publicName: "activeClassName", isSignal: true, isRequired: false, transformFunction: null }, activeStrict: { classPropertyName: "activeStrict", publicName: "activeStrict", isSignal: true, isRequired: false, transformFunction: null }, ignoreQueryParams: { classPropertyName: "ignoreQueryParams", publicName: "ignoreQueryParams", isSignal: true, isRequired: false, transformFunction: null }, hash: { classPropertyName: "hash", publicName: "hash", isSignal: true, isRequired: false, transformFunction: null } }, host: { listeners: { "click": "onClick($event)" } }, ngImport: i0 });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: RealLink, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: RealLink, decorators: [{
             type: Directive,
             args: [{
                     selector: "a[realLink]",
@@ -1170,7 +1753,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImpor
                         "(click)": "onClick($event)",
                     },
                 }]
-        }], propDecorators: { routeName: [{ type: i0.Input, args: [{ isSignal: true, alias: "routeName", required: false }] }], routeParams: [{ type: i0.Input, args: [{ isSignal: true, alias: "routeParams", required: false }] }], routeOptions: [{ type: i0.Input, args: [{ isSignal: true, alias: "routeOptions", required: false }] }], activeClassName: [{ type: i0.Input, args: [{ isSignal: true, alias: "activeClassName", required: false }] }], activeStrict: [{ type: i0.Input, args: [{ isSignal: true, alias: "activeStrict", required: false }] }], ignoreQueryParams: [{ type: i0.Input, args: [{ isSignal: true, alias: "ignoreQueryParams", required: false }] }], hash: [{ type: i0.Input, args: [{ isSignal: true, alias: "hash", required: false }] }] } });
+        }], ctorParameters: () => [], propDecorators: { routeName: [{ type: i0.Input, args: [{ isSignal: true, alias: "routeName", required: false }] }], routeParams: [{ type: i0.Input, args: [{ isSignal: true, alias: "routeParams", required: false }] }], routeOptions: [{ type: i0.Input, args: [{ isSignal: true, alias: "routeOptions", required: false }] }], activeClassName: [{ type: i0.Input, args: [{ isSignal: true, alias: "activeClassName", required: false }] }], activeStrict: [{ type: i0.Input, args: [{ isSignal: true, alias: "activeStrict", required: false }] }], ignoreQueryParams: [{ type: i0.Input, args: [{ isSignal: true, alias: "ignoreQueryParams", required: false }] }], hash: [{ type: i0.Input, args: [{ isSignal: true, alias: "hash", required: false }] }] } });
 class RealLinkActive {
     realLinkActive = input("", ...(ngDevMode ? [{ debugName: "realLinkActive" }] : /* istanbul ignore next */ []));
@@ -1179,26 +1762,29 @@ class RealLinkActive {
     activeStrict = input(false, ...(ngDevMode ? [{ debugName: "activeStrict" }] : /* istanbul ignore next */ []));
     ignoreQueryParams = input(true, ...(ngDevMode ? [{ debugName: "ignoreQueryParams" }] : /* istanbul ignore next */ []));
     router = injectRouter();
-    destroyRef = inject(DestroyRef);
     element = inject(ElementRef).nativeElement;
     isActive = signal(false, ...(ngDevMode ? [{ debugName: "isActive" }] : /* istanbul ignore next */ []));
+    // Skip-same-value: only touch `classList.toggle` when the active flag
+    // actually flipped. Saves one DOM write per RealLinkActive per unrelated
+    // navigation (review §8b MEDIUM).
+    prevActive = undefined;
     constructor() {
+        // One-time a11y setup — doesn't depend on signal inputs, stays in
+        // constructor body. `applyLinkA11y` is idempotent so re-running would
+        // be safe, but we only need it once per element.
         applyLinkA11y(this.element);
-    }
-    ngOnInit() {
-        const source = createActiveRouteSource(this.router, this.routeName(), this.routeParams(), {
-            strict: this.activeStrict(),
-            ignoreQueryParams: this.ignoreQueryParams(),
-        });
-        this.isActive.set(source.getSnapshot());
-        this.updateClass();
-        const unsub = source.subscribe(() => {
-            this.isActive.set(source.getSnapshot());
-            this.updateClass();
-        });
-        this.destroyRef.onDestroy(() => {
-            unsub();
-            source.destroy();
+        // Reactive source-creation effect (#630 fix) — see
+        // `packages/angular/CLAUDE.md` → "Directives use constructor + effect()".
+        effect((onCleanup) => {
+            const source = createActiveRouteSource(this.router, this.routeName(), this.routeParams(), buildActiveRouteOptions(this.activeStrict(), this.ignoreQueryParams(), undefined));
+            onCleanup(subscribeSourceToSignal(source, (snap) => {
+                if (snap === this.prevActive) {
+                    return;
+                }
+                this.prevActive = snap;
+                this.isActive.set(snap);
+                this.updateClass();
+            }));
         });
     }
     updateClass() {
@@ -1208,10 +1794,10 @@ class RealLinkActive {
         }
         this.element.classList.toggle(className, this.isActive());
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: RealLinkActive, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.8", type: RealLinkActive, isStandalone: true, selector: "[realLinkActive]", inputs: { realLinkActive: { classPropertyName: "realLinkActive", publicName: "realLinkActive", isSignal: true, isRequired: false, transformFunction: null }, routeName: { classPropertyName: "routeName", publicName: "routeName", isSignal: true, isRequired: false, transformFunction: null }, routeParams: { classPropertyName: "routeParams", publicName: "routeParams", isSignal: true, isRequired: false, transformFunction: null }, activeStrict: { classPropertyName: "activeStrict", publicName: "activeStrict", isSignal: true, isRequired: false, transformFunction: null }, ignoreQueryParams: { classPropertyName: "ignoreQueryParams", publicName: "ignoreQueryParams", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: RealLinkActive, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.9", type: RealLinkActive, isStandalone: true, selector: "[realLinkActive]", inputs: { realLinkActive: { classPropertyName: "realLinkActive", publicName: "realLinkActive", isSignal: true, isRequired: false, transformFunction: null }, routeName: { classPropertyName: "routeName", publicName: "routeName", isSignal: true, isRequired: false, transformFunction: null }, routeParams: { classPropertyName: "routeParams", publicName: "routeParams", isSignal: true, isRequired: false, transformFunction: null }, activeStrict: { classPropertyName: "activeStrict", publicName: "activeStrict", isSignal: true, isRequired: false, transformFunction: null }, ignoreQueryParams: { classPropertyName: "ignoreQueryParams", publicName: "ignoreQueryParams", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0 });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.8", ngImport: i0, type: RealLinkActive, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: RealLinkActive, decorators: [{
             type: Directive,
             args: [{ selector: "[realLinkActive]" }]
         }], ctorParameters: () => [], propDecorators: { realLinkActive: [{ type: i0.Input, args: [{ isSignal: true, alias: "realLinkActive", required: false }] }], routeName: [{ type: i0.Input, args: [{ isSignal: true, alias: "routeName", required: false }] }], routeParams: [{ type: i0.Input, args: [{ isSignal: true, alias: "routeParams", required: false }] }], activeStrict: [{ type: i0.Input, args: [{ isSignal: true, alias: "activeStrict", required: false }] }], ignoreQueryParams: [{ type: i0.Input, args: [{ isSignal: true, alias: "ignoreQueryParams", required: false }] }] } });
@@ -1220,5 +1806,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, injectRouteEnter, injectRouteExit, 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, provideRealRouterFactory, sourceToSignal };
 //# sourceMappingURL=real-router-angular.mjs.map