@real-router/angular 0.10.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
@@ -392,23 +458,34 @@ function createScrollRestoration(router, options) {
                 scrollToHashOrTop(route);
                 return;
             }
-            if (route.transition.replace || nav?.navigationType === "replace") {
-                return;
-            }
-            // Both arms 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. Same belt-and-suspenders pattern is used for replace
-            // above. Browser-plugin's F5 is not covered (no priming, out of scope).
+            // 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);
-                writePos(key === null ? 0 : (loadStore()[key] ?? 0));
+                restorePos(key === null ? 0 : (loadStore()[key] ?? 0));
                 return;
             }
             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);
@@ -548,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 */
@@ -915,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
@@ -1007,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));
     }
@@ -1055,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,
@@ -1152,6 +1660,11 @@ function provideRealRouterFactory(options) {
             installScrollRestoration(scrollRestoration);
         }));
     }
+    if (scrollSpy && scrollSpy.selector !== "") {
+        providers.push(provideEnvironmentInitializer(() => {
+            installScrollSpy(scrollSpy);
+        }));
+    }
     if (viewTransitions === true) {
         providers.push(provideEnvironmentInitializer(installViewTransitions));
     }