@real-router/angular 0.9.0 → 0.11.0

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

@@ -1,13 +1,13 @@
 import * as i0 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 { getTransitionSource, createRouteSource, createRouteNodeSource, createActiveRouteSource, createDismissableError } from '@real-router/sources';
 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$3 = Object.freeze({
+const NOOP_INSTANCE$4 = Object.freeze({
     destroy: () => {
         /* no-op */
     },
@@ -35,7 +35,7 @@ const NOOP_INSTANCE$3 = Object.freeze({
  */
 function createDirectionTracker(router) {
     if (typeof document === "undefined") {
-        return NOOP_INSTANCE$3;
+        return NOOP_INSTANCE$4;
     }
     let popstateFlag = false;
     document.documentElement.dataset.navDirection = "forward";
@@ -70,7 +70,7 @@ 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({
+const NOOP_INSTANCE$3 = Object.freeze({
     destroy: () => {
         /* no-op */
     },
@@ -86,7 +86,7 @@ function createRouteAnnouncer(router, options) {
     // bootstrap. Closes review-2026-05-10 §5.10 ⛔ "NavigationAnnouncer
     // SSR mode" MED.
     if (typeof document === "undefined") {
-        return NOOP_INSTANCE$2;
+        return NOOP_INSTANCE$3;
     }
     const prefix = options?.prefix ?? "Navigated to ";
     const getCustomText = options?.getAnnouncementText;
@@ -228,14 +228,21 @@ function manageFocus(h1) {
 }
 
 const DEFAULT_STORAGE_KEY = "real-router:scroll";
-const NOOP_INSTANCE$1 = Object.freeze({
+// Bounded retry budget for resolving a late-mounting scroll container on the
+// restore path. A per-route container (e.g. an `overflow:auto` div rendered
+// only on one route) can be committed to the DOM a few frames after the
+// navigation settles — heavier routes paint later than the subscribe's rAF.
+// ~10 frames (≈160ms at 60fps) comfortably covers a React commit of a large
+// route without being perceptible. See the doc-block on `restorePos`.
+const RESTORE_RETRY_FRAMES = 10;
+const NOOP_INSTANCE$2 = Object.freeze({
     destroy: () => {
         /* no-op */
     },
 });
 function createScrollRestoration(router, options) {
     if (typeof globalThis.window === "undefined") {
-        return NOOP_INSTANCE$1;
+        return NOOP_INSTANCE$2;
     }
     const mode = options?.mode ?? "restore";
     // mode "native" = utility does nothing. Don't flip history.scrollRestoration,
@@ -245,7 +252,7 @@ function createScrollRestoration(router, options) {
     // === "manual"` — utility's "native" leaves the DOM property at "auto" so
     // the browser is in charge.)
     if (mode === "native") {
-        return NOOP_INSTANCE$1;
+        return NOOP_INSTANCE$2;
     }
     const anchorEnabled = options?.anchorScrolling ?? true;
     const getContainer = options?.scrollContainer;
@@ -309,6 +316,65 @@ function createScrollRestoration(router, options) {
             globalThis.scrollTo({ top, left: 0, behavior });
         }
     };
+    // Restore path (back / traverse / reload). Unlike `writePos`, this tolerates a
+    // scroll container that both MOUNTS and LAYS OUT a few frames AFTER the
+    // navigation settles.
+    //
+    // The capture-side `readPos` always runs against an already-mounted DOM (the
+    // route being left). On restore the target route — and its container — is
+    // still being committed by the view layer. The subscribe callback schedules a
+    // single rAF; for a heavy route (e.g. a long virtual list) the framework's
+    // commit can land AFTER that frame. Two distinct failures follow, each losing
+    // the saved position (Scenario 6 e2e, reproduced under CI's slower runner):
+    //
+    //   1. Container not mounted yet → `getContainer()` is `null`, the scroll
+    //      silently falls back to `window`, which on a container-only route has
+    //      nothing to scroll.
+    //   2. Container mounted but its content not laid out yet → `scrollHeight`
+    //      is still small, so a single `scrollTo({ top })` clamps short of the
+    //      saved position and never re-applies once layout grows.
+    //
+    // With no `scrollContainer` getter the target is always `window`, present
+    // from the first frame — restore in a single shot (unchanged behaviour). When
+    // a getter is configured we cannot tell "this route legitimately uses window"
+    // from "the container is still mounting", so re-apply the scroll on every
+    // frame for a bounded budget: window as a fallback while the container is
+    // absent (harmless clamp on container routes), the container itself once it
+    // appears. For instant restores we stop early the moment the position sticks;
+    // smooth restores animate asynchronously, so they run the full budget. The
+    // frame budget is the hard backstop against an unreachable target (saved
+    // position taller than the restored content).
+    const restorePos = (top) => {
+        if (!getContainer) {
+            globalThis.scrollTo({ top, left: 0, behavior });
+            return;
+        }
+        let frames = 0;
+        const attempt = () => {
+            if (destroyed) {
+                return;
+            }
+            const element = getContainer();
+            if (element) {
+                element.scrollTo({ top, left: 0, behavior });
+                // Instant restore landed within rounding tolerance → done; no point
+                // re-applying. Smooth restore never matches synchronously, so let it
+                // ride the budget.
+                if (behavior !== "smooth" && Math.abs(element.scrollTop - top) <= 1) {
+                    return;
+                }
+            }
+            else {
+                globalThis.scrollTo({ top, left: 0, behavior });
+            }
+            if (frames >= RESTORE_RETRY_FRAMES) {
+                return;
+            }
+            frames += 1;
+            requestAnimationFrame(attempt);
+        };
+        attempt();
+    };
     const scrollToHashOrTop = (route) => {
         // URL plugin path (#532): `state.context.url.hash` is the source of truth
         // when one of the URL plugins (browser-plugin / navigation-plugin) is
@@ -384,24 +450,42 @@ function createScrollRestoration(router, options) {
                 putPos(prevKey, readPos());
             }
         }
-        // Single rAF so DOM is committed before we read anchors / write scroll.
-        // Guard against destroy() racing with the callback.
         requestAnimationFrame(() => {
             if (destroyed) {
                 return;
             }
-            if (mode === "top" || !nav) {
+            if (mode === "top") {
                 scrollToHashOrTop(route);
                 return;
             }
-            if (nav.navigationType === "replace") {
+            // Restore branches (reload, back/traverse) MUST be evaluated before the
+            // replace-skip below. Since #657 lifted `replace` into TransitionMeta, a
+            // history TRAVERSAL (back/forward) under navigation-plugin carries
+            // `transition.replace === true` — a traversal reuses an existing history
+            // entry, which is replace-shaped at the history level. If the replace-skip
+            // ran first it would swallow every back/forward navigation and restore
+            // would never fire (the Scenario 6 e2e regression). Genuine in-place
+            // replaces (`router.navigate({ replace: true })`, navigateToNotFound) are
+            // not traversals and fall through to the skip below.
+            //
+            // Both arms of each check are required: `transition.reload` only fires for
+            // programmatic `router.navigate({reload:true})`. F5 under navigation-plugin
+            // primes `nav.navigationType === "reload"` via #531 getActivationType but
+            // leaves opts.reload undefined, so dropping the plugin arm would regress F5
+            // scroll-restore. Browser-plugin's F5 is not covered (no priming, out of
+            // scope).
+            if (route.transition.reload || nav?.navigationType === "reload") {
+                const key = safeKeyOf(route);
+                restorePos(key === null ? 0 : (loadStore()[key] ?? 0));
                 return;
             }
-            if (nav.direction === "back" ||
-                nav.navigationType === "traverse" ||
-                nav.navigationType === "reload") {
+            if (nav?.direction === "back" || nav?.navigationType === "traverse") {
                 const key = safeKeyOf(route);
-                writePos(key === null ? 0 : (loadStore()[key] ?? 0));
+                restorePos(key === null ? 0 : (loadStore()[key] ?? 0));
+                return;
+            }
+            // Genuine in-place replace (not a traversal) — leave scroll untouched.
+            if (route.transition.replace || nav?.navigationType === "replace") {
                 return;
             }
             scrollToHashOrTop(route);
@@ -541,6 +625,424 @@ function canonicalReplacer(_key, val) {
     return val;
 }
 
+const NOOP_INSTANCE$1 = Object.freeze({
+    destroy: () => {
+        /* no-op */
+    },
+});
+// Hardcoded internals (RFC §5.1 — promote only with evidence).
+const RAF_DEBOUNCE_MS = 150;
+const MUTATION_DEBOUNCE_MS = 250;
+const COOLDOWN_TIMEOUT_MS = 500;
+const DEFAULT_ROOT_MARGIN = "-20% 0px -60% 0px";
+const getUrlContext = (state) => state.context?.url;
+// =============================================================================
+// Picker — pure, no state. RFC §5.2 selection rule.
+// =============================================================================
+// Pick the anchor closest to the active zone top in viewport coordinates.
+// `entry.rootBounds.top` already reflects `rootMargin` (per W3C IO spec
+// §3.3) — for `rootMargin: "-20% 0px -60% 0px"` it returns 20% of root
+// height, for `"-50% 0px -50% 0px"` it returns the center, etc. Distance
+// = boundingClientRect.top − zoneTop in viewport pixels: positive = anchor
+// below zone top (just entered), negative = anchor above zone top (body
+// crossing zone from above). We prefer smallest non-negative; fall back to
+// least-negative when no entry has crossed yet.
+// Falls back to zoneTop = 0 when rootBounds is null (cross-origin roots,
+// unit tests). Single pass — handles `Iterable` so flushes can pass
+// `Map.values()` directly without realising the array.
+const pickTopmost = (entries) => {
+    let bestPositive = null;
+    let bestPositiveDist = Number.POSITIVE_INFINITY;
+    let bestNegative = null;
+    let bestNegativeDist = Number.NEGATIVE_INFINITY;
+    for (const entry of entries) {
+        if (!entry.isIntersecting) {
+            continue;
+        }
+        const zoneTop = entry.rootBounds?.top ?? 0;
+        const distance = entry.boundingClientRect.top - zoneTop;
+        if (distance >= 0) {
+            if (distance < bestPositiveDist) {
+                bestPositive = entry;
+                bestPositiveDist = distance;
+            }
+        }
+        else if (distance > bestNegativeDist) {
+            bestNegative = entry;
+            bestNegativeDist = distance;
+        }
+    }
+    return bestPositive ?? bestNegative;
+};
+const createUrlPluginDetector = (router, onMissing) => {
+    let detectionUnsub = null;
+    const verify = (state) => {
+        const context = state.context;
+        if (context && context.url === undefined) {
+            console.warn("[real-router] scroll-spy: state.context.url is not claimed. " +
+                "Spy requires browser-plugin or navigation-plugin. Disabling.");
+            onMissing();
+        }
+    };
+    const peekState = router.getState();
+    if (peekState) {
+        verify(peekState);
+    }
+    else {
+        // Re-entry guard: `router.subscribe` MAY invoke the callback synchronously
+        // from inside `.subscribe(...)` before the function returns. In that case
+        // `detectionUnsub` is still `null` when the callback fires. Without this
+        // boolean, a hypothetical multi-fire would double-warn.
+        let detectionConsumed = false;
+        detectionUnsub = router.subscribe(({ route }) => {
+            if (detectionConsumed) {
+                return;
+            }
+            detectionConsumed = true;
+            verify(route);
+            detectionUnsub?.();
+            detectionUnsub = null;
+        });
+    }
+    return {
+        destroy() {
+            detectionUnsub?.();
+            detectionUnsub = null;
+        },
+    };
+};
+const createCooldown = (getContainer) => {
+    let active = false;
+    let timeout = null;
+    let listenerContainer = null;
+    let listener = null;
+    const clear = () => {
+        if (timeout !== null) {
+            clearTimeout(timeout);
+            timeout = null;
+        }
+        if (listener) {
+            const target = listenerContainer ?? globalThis;
+            target.removeEventListener("scrollend", listener);
+        }
+        listener = null;
+        listenerContainer = null;
+        active = false;
+    };
+    return {
+        get active() {
+            return active;
+        },
+        start() {
+            // Reset rather than stack timers if cooldown is already active.
+            clear();
+            active = true;
+            const lift = () => {
+                clear();
+            };
+            listener = lift;
+            listenerContainer = getContainer();
+            const target = listenerContainer ?? globalThis;
+            target.addEventListener("scrollend", lift, { once: true });
+            timeout = setTimeout(lift, COOLDOWN_TIMEOUT_MS);
+        },
+        destroy() {
+            clear();
+        },
+    };
+};
+const createDebouncer = (callback, trailingMs) => {
+    let raf = null;
+    let timeout = null;
+    return {
+        schedule() {
+            if (raf !== null) {
+                return;
+            }
+            raf = requestAnimationFrame(() => {
+                raf = null;
+                if (timeout !== null) {
+                    clearTimeout(timeout);
+                }
+                timeout = setTimeout(() => {
+                    timeout = null;
+                    callback();
+                }, trailingMs);
+            });
+        },
+        destroy() {
+            if (raf !== null) {
+                cancelAnimationFrame(raf);
+                raf = null;
+            }
+            if (timeout !== null) {
+                clearTimeout(timeout);
+                timeout = null;
+            }
+        },
+    };
+};
+const createObserverPair = (selector, rootMargin, getContainer, onIntersection, onInvalidSelector, isStopped) => {
+    const observed = new Set();
+    // Latest IO entry per target — accumulated across batches. IO delivers
+    // entries only for targets whose intersection state CHANGED (W3C IO
+    // §3.2.1), so a fast scroll that lands two callbacks inside the same
+    // debounce window must merge by target, not overwrite. Entries are
+    // dropped from the map when their target leaves the DOM (see `reconcile`)
+    // and on `destroy()`.
+    const pending = new Map();
+    let duplicateIdWarned = false;
+    let mutationTimer = null;
+    const handleIntersection = (entries) => {
+        // Defensive: IO callback may fire AFTER `destroy()` if a queued event
+        // was already scheduled by the browser before `disconnect()`. Cheap
+        // belt-and-suspenders.
+        if (isStopped()) {
+            return;
+        }
+        for (const entry of entries) {
+            pending.set(entry.target, entry);
+        }
+        onIntersection();
+    };
+    const io = new IntersectionObserver(handleIntersection, {
+        root: getContainer(),
+        rootMargin,
+        threshold: 0,
+    });
+    const observeMatches = () => {
+        const scope = getContainer() ?? document;
+        let candidates;
+        try {
+            candidates = scope.querySelectorAll(selector);
+        }
+        catch {
+            onInvalidSelector();
+            return;
+        }
+        const seenIds = new Set();
+        for (const element of candidates) {
+            // Detect duplicate ids once (RFC §7.7). The DOM permits duplicate ids
+            // even though it is a markup bug; the spy keeps working but picks the
+            // first one deterministically via the topmost-visible rule.
+            const id = element.id;
+            if (id && !duplicateIdWarned) {
+                if (seenIds.has(id)) {
+                    duplicateIdWarned = true;
+                    console.warn(`[real-router] scroll-spy: duplicate id "${id}" observed. ` +
+                        "Selection picks the topmost visible match deterministically.");
+                }
+                seenIds.add(id);
+            }
+            if (observed.has(element)) {
+                continue;
+            }
+            io.observe(element);
+            observed.add(element);
+        }
+    };
+    const reconcile = () => {
+        // Drop observed elements that left the DOM. Avoids observer holding
+        // strong refs to detached nodes. Also drop their accumulated entry so
+        // stale "was intersecting" state for a removed node cannot be picked
+        // by `pickTopmost` after the node is gone.
+        for (const element of observed) {
+            if (!element.isConnected) {
+                io.unobserve(element);
+                observed.delete(element);
+                pending.delete(element);
+            }
+        }
+        observeMatches();
+    };
+    observeMatches();
+    // MutationObserver targets the scroll container (or document.body for
+    // window viewport). `childList: true, subtree: true` catches structural
+    // changes; `attributes: true, attributeFilter: ["id"]` catches anchor
+    // id renames (typical for client-rendered docs).
+    const mutationTarget = getContainer() ?? document.body;
+    const mo = new MutationObserver(() => {
+        if (mutationTimer !== null) {
+            clearTimeout(mutationTimer);
+        }
+        mutationTimer = setTimeout(() => {
+            mutationTimer = null;
+            reconcile();
+        }, MUTATION_DEBOUNCE_MS);
+    });
+    mo.observe(mutationTarget, {
+        childList: true,
+        subtree: true,
+        attributes: true,
+        attributeFilter: ["id"],
+    });
+    return {
+        pending,
+        destroy() {
+            io.disconnect();
+            mo.disconnect();
+            if (mutationTimer !== null) {
+                clearTimeout(mutationTimer);
+                mutationTimer = null;
+            }
+            observed.clear();
+            pending.clear();
+        },
+    };
+};
+// =============================================================================
+// Main: compositional wiring
+// =============================================================================
+function createScrollSpy(router, options) {
+    // SSR guard (RFC §7.5) — return early without warnings.
+    if (typeof document === "undefined") {
+        return NOOP_INSTANCE$1;
+    }
+    // Feature-detect IntersectionObserver — no polyfill ships (RFC §4).
+    if (typeof IntersectionObserver === "undefined") {
+        return NOOP_INSTANCE$1;
+    }
+    const { selector } = options;
+    // Empty selector → disabled. Documented opt-out for conditional enabling
+    // (RFC §5.4 `scrollSpy={{ selector: enable ? "[id]" : "" }}`).
+    if (!selector) {
+        return NOOP_INSTANCE$1;
+    }
+    const rootMargin = options.rootMargin ?? DEFAULT_ROOT_MARGIN;
+    const getContainer = options.scrollContainer;
+    const resolveContainer = () => getContainer?.() ?? null;
+    // Shared lifecycle flags (Oracle Q1 — `silenced` has multiple unrelated
+    // triggers; Oracle Q3 — `selfEmitting` synchronously bracketed around
+    // `router.navigate()` cannot cleanly extract). Kept in main scope.
+    let destroyed = false;
+    let silenced = false;
+    let selfEmitting = false;
+    const isStopped = () => silenced || destroyed;
+    // Symmetric late-binding (Oracle Q2): declare `flush` as nullable, wire
+    // debouncer + observers, then assign the real implementation. Reads as
+    // intentional wiring rather than accidental closure capture ordering.
+    // The `flush?.()` call below safely no-ops if a callback somehow fires
+    // before assignment (impossible in practice — IO/debounce are async).
+    let flush = null;
+    const transitionSource = getTransitionSource(router);
+    const detector = createUrlPluginDetector(router, () => {
+        silenced = true;
+    });
+    const cooldown = createCooldown(resolveContainer);
+    const debouncer = createDebouncer(() => {
+        flush?.();
+    }, RAF_DEBOUNCE_MS);
+    const observers = createObserverPair(selector, rootMargin, resolveContainer, () => {
+        debouncer.schedule();
+    }, () => {
+        if (silenced) {
+            return;
+        }
+        silenced = true;
+        console.warn(`[real-router] scroll-spy: invalid selector "${selector}". Disabling.`);
+    }, isStopped);
+    flush = () => {
+        if (destroyed || silenced) {
+            observers.pending.clear();
+            return;
+        }
+        // Gate-skipped flushes keep `pendingEntries` populated — the merged
+        // state is still the best-known snapshot, and the next non-gated flush
+        // consumes it. Clearing under a gate would re-introduce the overwrite
+        // bug for any anchor whose intersection state did not change during
+        // the gate window.
+        if (transitionSource.getSnapshot().isTransitioning) {
+            return;
+        }
+        if (cooldown.active) {
+            return;
+        }
+        if (observers.pending.size === 0) {
+            return;
+        }
+        // Successful flush consumes the merged snapshot. We clear so that the
+        // next debounce window starts fresh; an anchor that is still
+        // intersecting will only stay observable if IO emits another event for
+        // it (which it does whenever the anchor's intersection state actually
+        // changes). Skipping the clear here would leak state from one user-
+        // perceived "scroll stop" into the next.
+        const picked = pickTopmost(observers.pending.values());
+        observers.pending.clear();
+        if (!picked) {
+            // No anchor visible / above zone — preserve last hash (RFC §10 #5).
+            return;
+        }
+        const newHash = picked.target.id;
+        if (!newHash) {
+            return;
+        }
+        const state = router.getState();
+        if (!state) {
+            return;
+        }
+        const currentHash = getUrlContext(state)?.hash ?? "";
+        if (newHash === currentHash) {
+            return;
+        }
+        // Emit the same-route same-params hash-only transition. URL plugin
+        // writes `state.context.url.hash = newHash` + `hashChanged = true` in
+        // its `onTransitionSuccess` claim.
+        const opts = {
+            hash: newHash,
+            replace: true,
+            force: true,
+            hashChange: true,
+        };
+        // Self-emit guard (RFC §5.2): set synchronously around our own
+        // `router.navigate()` so the `router.subscribe` callback skips the
+        // cooldown setup for spy-emitted transitions — otherwise spy would
+        // rate-limit itself to ≤ 2 emits/s, contradicting the ≤ 10/s benchmark
+        // target. Test coupling (Q8): preserve exact `.catch(noop).finally(reset)`
+        // chain — migrating to `try/finally` over `await router.navigate(...)`
+        // changes microtask schedule and breaks "spy continues after rejection".
+        selfEmitting = true;
+        router
+            .navigate(state.name, state.params, opts)
+            .catch(() => {
+            // Fire-and-forget — suppress expected rejections (concurrent
+            // navigate, router stopped, etc.) consistent with `<Link>` adapter
+            // patterns.
+        })
+            .finally(() => {
+            selfEmitting = false;
+        });
+    };
+    // Cooldown setup on user-driven hash transitions. Spy's own emits are
+    // distinguished via the synchronous `selfEmitting` flag (see `flush`).
+    const unsubscribeRouter = router.subscribe(({ route }) => {
+        if (selfEmitting) {
+            return;
+        }
+        if (getUrlContext(route)?.hashChanged) {
+            cooldown.start();
+        }
+    });
+    return {
+        destroy() {
+            if (destroyed) {
+                return;
+            }
+            destroyed = true;
+            // Unsubscribe FIRST to prevent late-arriving router transition
+            // callback from calling `cooldown.start()` on a half-destroyed
+            // instance. Without this ordering, a transition with `hashChanged:
+            // true` firing between subsystem teardown and `unsubscribeRouter()`
+            // would re-install a 500ms timer that survives `destroy()`. Verified
+            // via Oracle review (Q5/Q7).
+            unsubscribeRouter();
+            observers.destroy();
+            debouncer.destroy();
+            cooldown.destroy();
+            detector.destroy();
+        },
+    };
+}
+
 const NOOP_INSTANCE = Object.freeze({
     destroy: () => {
         /* no-op */
@@ -908,6 +1410,13 @@ function installScrollRestoration(options) {
         sr.destroy();
     });
 }
+function installScrollSpy(options) {
+    const router = inject(ROUTER);
+    const spy = createScrollSpy(router, options);
+    inject(DestroyRef).onDestroy(() => {
+        spy.destroy();
+    });
+}
 function installViewTransitions() {
     const router = inject(ROUTER);
     // Feature-detect `document.startViewTransition` once at install time. The
@@ -1000,6 +1509,12 @@ function provideRealRouter(router, options) {
             installScrollRestoration(scrollOpts);
         }));
     }
+    if (options?.scrollSpy && options.scrollSpy.selector !== "") {
+        const spyOpts = options.scrollSpy;
+        providers.push(provideEnvironmentInitializer(() => {
+            installScrollSpy(spyOpts);
+        }));
+    }
     if (options?.viewTransitions === true) {
         providers.push(provideEnvironmentInitializer(installViewTransitions));
     }
@@ -1048,7 +1563,7 @@ const ROUTER_STATE_KEY = makeStateKey("@real-router/angular:ssrState");
  * @returns `EnvironmentProviders` to spread into `ApplicationConfig.providers`.
  */
 function provideRealRouterFactory(options) {
-    const { baseRouter, plugins, deps, scrollRestoration, viewTransitions } = options;
+    const { baseRouter, plugins, deps, scrollRestoration, scrollSpy, viewTransitions, } = options;
     const providers = [
         {
             provide: ROUTER,
@@ -1145,6 +1660,11 @@ function provideRealRouterFactory(options) {
             installScrollRestoration(scrollRestoration);
         }));
     }
+    if (scrollSpy && scrollSpy.selector !== "") {
+        providers.push(provideEnvironmentInitializer(() => {
+            installScrollSpy(scrollSpy);
+        }));
+    }
     if (viewTransitions === true) {
         providers.push(provideEnvironmentInitializer(installViewTransitions));
     }
@@ -1413,30 +1933,30 @@ 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.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 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.13", ngImport: i0, type: RouteMatch, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.13", 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.9", ngImport: i0, type: RouteMatch, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.13", 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.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 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.13", ngImport: i0, type: RouteNotFound, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "21.2.13", type: RouteNotFound, isStandalone: true, selector: "ng-template[routeNotFound]", ngImport: i0 });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: RouteNotFound, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.13", 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.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 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.13", ngImport: i0, type: RouteSelf, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "21.2.13", type: RouteSelf, isStandalone: true, selector: "ng-template[routeSelf]", ngImport: i0 });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: RouteSelf, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.13", ngImport: i0, type: RouteSelf, decorators: [{
             type: Directive,
             args: [{ selector: "ng-template[routeSelf]" }]
         }] });
@@ -1562,14 +2082,14 @@ class RouteView {
             }));
         });
     }
-    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: `
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.13", ngImport: i0, type: RouteView, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.13", 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.9", ngImport: i0, type: RouteView, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.13", ngImport: i0, type: RouteView, decorators: [{
             type: Component,
             args: [{
                     selector: "route-view",
@@ -1615,8 +2135,8 @@ class RouterErrorBoundary {
             }
         });
     }
-    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: `
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.13", ngImport: i0, type: RouterErrorBoundary, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.13", 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
@@ -1626,7 +2146,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.9", ngImport: i0, type: RouterErrorBoundary, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.13", ngImport: i0, type: RouterErrorBoundary, decorators: [{
             type: Component,
             args: [{
                     selector: "router-error-boundary",
@@ -1650,10 +2170,10 @@ class NavigationAnnouncer {
             this.announcer.destroy();
         });
     }
-    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 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.13", ngImport: i0, type: NavigationAnnouncer, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "21.2.13", type: NavigationAnnouncer, isStandalone: true, selector: "navigation-announcer", ngImport: i0, template: "", isInline: true });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.9", ngImport: i0, type: NavigationAnnouncer, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.13", ngImport: i0, type: NavigationAnnouncer, decorators: [{
             type: Component,
             args: [{
                     selector: "navigation-announcer",
@@ -1742,10 +2262,10 @@ class RealLink {
         }
         this.prevActiveClass = activeClass;
     }
-    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 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.13", ngImport: i0, type: RealLink, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.13", 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.9", ngImport: i0, type: RealLink, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.13", ngImport: i0, type: RealLink, decorators: [{
             type: Directive,
             args: [{
                     selector: "a[realLink]",
@@ -1794,10 +2314,10 @@ class RealLinkActive {
         }
         this.element.classList.toggle(className, this.isActive());
     }
-    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 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.13", ngImport: i0, type: RealLinkActive, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.13", 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.9", ngImport: i0, type: RealLinkActive, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.13", 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 }] }] } });