@real-router/svelte 0.12.0 → 0.13.0

package/README.md

@@ -200,7 +200,7 @@ All other props are spread onto the `<a>` element.
 <Link routeName="settings" hash="account">Account</Link>
 ```
 
-Active class is hash-aware — only the matching tab lights up. Live demo: [`examples/web/react/link-hash/`](../../examples/web/react/link-hash/) — behavior is identical across adapters, only template syntax differs. See the [Hash Fragment Support](https://github.com/greydragon888/real-router/wiki/Hash) wiki page for the full surface.
+Active class is hash-aware — only the matching tab lights up. Live demo: [`examples/web/react/hash-examples/link-hash/`](../../examples/web/react/hash-examples/link-hash/) — behavior is identical across adapters, only template syntax differs. See the [Hash Fragment Support](https://github.com/greydragon888/real-router/wiki/Hash) wiki page for the full surface.
 
 ### `<Lazy>`
 
@@ -475,6 +475,22 @@ Opt-in preservation of scroll position across navigations:
 
 Restores scroll on back/forward, scrolls to top (or `#hash`) on push. Three modes: `"restore"` (default), `"top"`, `"native"`. Custom containers via `scrollContainer: () => HTMLElement | null`. Lifecycle tied to the provider — created on mount, destroyed on unmount. Under `@real-router/browser-plugin`, replace transitions now preserve scroll position and programmatic reloads restore from `sessionStorage` (portable via `state.transition.replace` / `state.transition.reload`). See [Scroll Restoration guide](https://github.com/greydragon888/real-router/wiki/Scroll-Restoration) for the full behaviour matrix.
 
+## Scroll Spy
+
+Opt-in router-coordinated `IntersectionObserver` scroll spy — the URL hash tracks the topmost visible anchor as the user scrolls, syncing `state.context.url.hash` so sibling `<Link hash>` highlights stay current:
+
+```svelte
+<RouterProvider {router} scrollSpy={{ selector: "[id]:is(h2,h3)" }}>
+  <!-- Your app -->
+</RouterProvider>
+```
+
+Emits a forced same-route transition with `{ hash, replace: true, force: true, hashChange: true }` — same write API as `<Link hash>` (#532), `replace: true` so spy doesn't pollute history. Anti-flicker via `isTransitioning` + `coolingDown` gates with `selfEmitting` guard. Hardcoded internals: rAF + 150 ms debounce, MutationObserver 250 ms.
+
+Options: `{ selector: string, rootMargin?: string, scrollContainer?: () => HTMLElement | null }`. Reactive via `$effect` — primitive fields (`selector`, `rootMargin`) wrapped in `$derived`, so inline objects with the same values don't thrash; `scrollContainer` getter pulled via `untrack` (identity changes don't retrigger). Empty `selector` / `undefined` = off. SSR / browsers without `IntersectionObserver` = NOOP. Requires `browser-plugin` or `navigation-plugin` (hash-plugin / memory-plugin → warn-once + NOOP).
+
+Behaviour is identical to the React adapter — see the [React Scroll Spy demo](../../examples/web/react/hash-examples/scroll-spy/) (12 sections, TOC sidebar, 10 e2e scenarios) and the [Scroll Spy guide](https://github.com/greydragon888/real-router/wiki/Scroll-Spy).
+
 ## View Transitions
 
 Opt-in animated route transitions via the browser's [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API):
@@ -491,7 +507,7 @@ Reactive via `$effect` — toggling the prop creates/destroys the utility. No-op
 
 Full documentation: [Wiki](https://github.com/greydragon888/real-router/wiki)
 
-- [RouterProvider](https://github.com/greydragon888/real-router/wiki/RouterProvider) · [RouteView](https://github.com/greydragon888/real-router/wiki/RouteView) · [RouterErrorBoundary](https://github.com/greydragon888/real-router/wiki/RouterErrorBoundary) · [Link](https://github.com/greydragon888/real-router/wiki/Link) · [Scroll Restoration](https://github.com/greydragon888/real-router/wiki/Scroll-Restoration) · [View Transitions](https://github.com/greydragon888/real-router/wiki/View-Transitions)
+- [RouterProvider](https://github.com/greydragon888/real-router/wiki/RouterProvider) · [RouteView](https://github.com/greydragon888/real-router/wiki/RouteView) · [RouterErrorBoundary](https://github.com/greydragon888/real-router/wiki/RouterErrorBoundary) · [Link](https://github.com/greydragon888/real-router/wiki/Link) · [Scroll Restoration](https://github.com/greydragon888/real-router/wiki/Scroll-Restoration) · [Scroll Spy](https://github.com/greydragon888/real-router/wiki/Scroll-Spy) · [View Transitions](https://github.com/greydragon888/real-router/wiki/View-Transitions)
 - [useRouter](https://github.com/greydragon888/real-router/wiki/useRouter) · [useRoute](https://github.com/greydragon888/real-router/wiki/useRoute) · [useRouteNode](https://github.com/greydragon888/real-router/wiki/useRouteNode) · [useNavigator](https://github.com/greydragon888/real-router/wiki/useNavigator) · [useRouteUtils](https://github.com/greydragon888/real-router/wiki/useRouteUtils) · [useRouterTransition](https://github.com/greydragon888/real-router/wiki/useRouterTransition) · [useRouteExit](https://github.com/greydragon888/real-router/wiki/useRouteExit) · [useRouteEnter](https://github.com/greydragon888/real-router/wiki/useRouteEnter)
 
 ## Examples

package/dist/RouterProvider.svelte

@@ -4,6 +4,7 @@
   import {
     createRouteAnnouncer,
     createScrollRestoration,
+    createScrollSpy,
     createViewTransitions,
   } from "./dom-utils";
   import { setContext, untrack } from "svelte";
@@ -12,7 +13,7 @@
   import { createRouteContext } from "./createRouteContext.svelte";
   import { NAVIGATOR_KEY, ROUTE_KEY, ROUTER_KEY } from "./context";
 
-  import type { ScrollRestorationOptions } from "./dom-utils";
+  import type { ScrollRestorationOptions, ScrollSpyOptions } from "./dom-utils";
   import type { Router } from "@real-router/core";
   import type { Snippet } from "svelte";
 
@@ -21,13 +22,15 @@
     children,
     announceNavigation,
     scrollRestoration,
+    scrollSpy,
     viewTransitions,
   }: {
     router: Router;
     children: Snippet;
-    announceNavigation?: boolean;
-    scrollRestoration?: ScrollRestorationOptions;
-    viewTransitions?: boolean;
+    announceNavigation?: boolean | undefined;
+    scrollRestoration?: ScrollRestorationOptions | undefined;
+    scrollSpy?: ScrollSpyOptions | undefined;
+    viewTransitions?: boolean | undefined;
   } = $props();
 
   $effect(() => {
@@ -73,6 +76,23 @@
     return () => sr.destroy();
   });
 
+  const spyEnabled = $derived(
+    scrollSpy !== undefined && scrollSpy.selector !== "",
+  );
+  const spySelector = $derived(scrollSpy?.selector);
+  const spyRootMargin = $derived(scrollSpy?.rootMargin);
+
+  $effect(() => {
+    if (!spyEnabled || !spySelector) return;
+    void spyRootMargin;
+    const spy = createScrollSpy(router, {
+      selector: spySelector,
+      rootMargin: spyRootMargin,
+      scrollContainer: untrack(() => scrollSpy?.scrollContainer),
+    });
+    return () => spy.destroy();
+  });
+
   $effect(() => {
     if (!viewTransitions) return;
     const vt = createViewTransitions(router);

package/dist/RouterProvider.svelte.d.ts

@@ -1,12 +1,13 @@
-import type { ScrollRestorationOptions } from "./dom-utils";
+import type { ScrollRestorationOptions, ScrollSpyOptions } from "./dom-utils";
 import type { Router } from "@real-router/core";
 import type { Snippet } from "svelte";
 type $$ComponentProps = {
     router: Router;
     children: Snippet;
-    announceNavigation?: boolean;
-    scrollRestoration?: ScrollRestorationOptions;
-    viewTransitions?: boolean;
+    announceNavigation?: boolean | undefined;
+    scrollRestoration?: ScrollRestorationOptions | undefined;
+    scrollSpy?: ScrollSpyOptions | undefined;
+    viewTransitions?: boolean | undefined;
 };
 declare const RouterProvider: import("svelte").Component<$$ComponentProps, {}, "">;
 type RouterProvider = ReturnType<typeof RouterProvider>;

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

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

package/dist/dom-utils/index.js

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

package/dist/dom-utils/scroll-restore.js

@@ -1,4 +1,11 @@
 const DEFAULT_STORAGE_KEY = "real-router:scroll";
+// 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 = Object.freeze({
     destroy: () => {
         /* no-op */
@@ -80,6 +87,65 @@ export 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
@@ -163,23 +229,34 @@ export 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);

package/dist/dom-utils/scroll-spy.d.ts

@@ -0,0 +1,64 @@
+import type { Router } from "@real-router/core";
+/**
+ * Router-coordinated scroll spy (#575).
+ *
+ * On `IntersectionObserver` notifications the utility picks the topmost
+ * visible anchor inside the configured scroll container and emits a forced
+ * same-route transition with `{ hash, replace: true, force: true, hashChange:
+ * true }` through `router.navigate(...)`. The URL plugin
+ * (`@real-router/browser-plugin` or `@real-router/navigation-plugin`) updates
+ * `state.context.url.hash` so sibling hash-aware `<Link hash>` re-highlights
+ * via the standard `createActiveRouteSource` pipeline.
+ *
+ * **Anti-flicker gates** (RFC §5.2):
+ * 1. `getTransitionSource(router).getSnapshot().isTransitioning` — skip emits
+ *    while a transition is in-flight (re-entrant lock).
+ * 2. `coolingDown` — set on a user-driven hash transition (e.g. `<Link hash>`
+ *    click + smooth `scrollIntoView`). Cleared on `scrollend` or after a
+ *    500ms safety timeout. Spy's own emits are excluded via the synchronous
+ *    `selfEmitting` flag — required so the spy doesn't rate-limit itself.
+ *
+ * **Self-healing** (RFC §7.3): if the initial URL contains a hash without a
+ * matching `id` (e.g. `/page#nonexistent`), the first IO event emitted right
+ * after observe()-ing picks the topmost real anchor and corrects the URL.
+ *
+ * **Hash-only transition pipeline cost** (RFC §5.3): for same-route same-
+ * params hash-only navigations, `getTransitionPath` returns empty
+ * `toDeactivate` / `toActivate` arrays, so `runGuards` is a no-op. The only
+ * work is the URL plugin's `onTransitionSuccess` write and the
+ * `getTransitionSource` flip — cheap.
+ *
+ * **Architecture**: decomposed into 4 private subsystem closure factories
+ * (`createUrlPluginDetector`, `createCooldown`, `createDebouncer`,
+ * `createObserverPair`). The main `createScrollSpy` wires them together
+ * around the shared `silenced` / `destroyed` / `selfEmitting` flags and the
+ * `flush()` emit logic. Each subsystem owns its state + cleanup; `destroy()`
+ * delegates to each. See section banners below.
+ *
+ * @returns A `ScrollSpy` handle whose `destroy()` is idempotent.
+ */
+export interface ScrollSpyOptions {
+    /**
+     * CSS selector for anchor candidates. Empty string `""` or `undefined`
+     * disables the spy (returns a NOOP handle). Common values:
+     * `"[id]"`, `"[id]:is(h1,h2,h3)"`, `"section[id]"`.
+     */
+    selector: string;
+    /**
+     * `IntersectionObserver` `rootMargin`. Default
+     * `"-20% 0px -60% 0px"` — an anchor is considered "active" once it crosses
+     * into the top 20 % of the viewport (or scroll container).
+     */
+    rootMargin?: string | undefined;
+    /**
+     * Lazy getter for the scrollable container. Resolved on every event.
+     * `null` (or missing getter) falls back to the window viewport
+     * (`root: null` on the `IntersectionObserver`).
+     */
+    scrollContainer?: (() => HTMLElement | null) | undefined;
+}
+export interface ScrollSpy {
+    /** Tear down observer + listeners. Idempotent. */
+    destroy: () => void;
+}
+export declare function createScrollSpy(router: Router, options: ScrollSpyOptions): ScrollSpy;

package/dist/dom-utils/scroll-spy.js

@@ -0,0 +1,418 @@
+import { getTransitionSource } from "@real-router/sources";
+const NOOP_INSTANCE = 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
+// =============================================================================
+export function createScrollSpy(router, options) {
+    // SSR guard (RFC §7.5) — return early without warnings.
+    if (typeof document === "undefined") {
+        return NOOP_INSTANCE;
+    }
+    // Feature-detect IntersectionObserver — no polyfill ships (RFC §4).
+    if (typeof IntersectionObserver === "undefined") {
+        return NOOP_INSTANCE;
+    }
+    const { selector } = options;
+    // Empty selector → disabled. Documented opt-out for conditional enabling
+    // (RFC §5.4 `scrollSpy={{ selector: enable ? "[id]" : "" }}`).
+    if (!selector) {
+        return NOOP_INSTANCE;
+    }
+    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();
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/svelte",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "type": "module",
   "description": "Svelte 5 integration for Real-Router",
   "svelte": "./dist/index.js",
@@ -49,7 +49,7 @@
   "license": "MIT",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.54.1",
+    "@real-router/core": "^0.54.6",
     "@real-router/route-utils": "^0.2.2",
     "@real-router/sources": "^0.8.3"
   },

package/src/RouterProvider.svelte

@@ -4,6 +4,7 @@
   import {
     createRouteAnnouncer,
     createScrollRestoration,
+    createScrollSpy,
     createViewTransitions,
   } from "./dom-utils";
   import { setContext, untrack } from "svelte";
@@ -12,7 +13,7 @@
   import { createRouteContext } from "./createRouteContext.svelte";
   import { NAVIGATOR_KEY, ROUTE_KEY, ROUTER_KEY } from "./context";
 
-  import type { ScrollRestorationOptions } from "./dom-utils";
+  import type { ScrollRestorationOptions, ScrollSpyOptions } from "./dom-utils";
   import type { Router } from "@real-router/core";
   import type { Snippet } from "svelte";
 
@@ -21,13 +22,15 @@
     children,
     announceNavigation,
     scrollRestoration,
+    scrollSpy,
     viewTransitions,
   }: {
     router: Router;
     children: Snippet;
-    announceNavigation?: boolean;
-    scrollRestoration?: ScrollRestorationOptions;
-    viewTransitions?: boolean;
+    announceNavigation?: boolean | undefined;
+    scrollRestoration?: ScrollRestorationOptions | undefined;
+    scrollSpy?: ScrollSpyOptions | undefined;
+    viewTransitions?: boolean | undefined;
   } = $props();
 
   $effect(() => {
@@ -73,6 +76,23 @@
     return () => sr.destroy();
   });
 
+  const spyEnabled = $derived(
+    scrollSpy !== undefined && scrollSpy.selector !== "",
+  );
+  const spySelector = $derived(scrollSpy?.selector);
+  const spyRootMargin = $derived(scrollSpy?.rootMargin);
+
+  $effect(() => {
+    if (!spyEnabled || !spySelector) return;
+    void spyRootMargin;
+    const spy = createScrollSpy(router, {
+      selector: spySelector,
+      rootMargin: spyRootMargin,
+      scrollContainer: untrack(() => scrollSpy?.scrollContainer),
+    });
+    return () => spy.destroy();
+  });
+
   $effect(() => {
     if (!viewTransitions) return;
     const vt = createViewTransitions(router);