@real-router/solid 0.13.0 → 0.14.1

package/README.md

@@ -242,7 +242,7 @@ Navigation link with automatic active state detection. Uses `classList` for acti
 <Link routeName="settings" hash="account">Account</Link>
 ```
 
-Tri-state: `undefined` preserves the current hash, `""` clears it, a value sets it. Active class is hash-aware — only the matching tab lights up. Setting `hash` forces the slow path (the fast-path `routeSelector` is hash-agnostic). 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.
+Tri-state: `undefined` preserves the current hash, `""` clears it, a value sets it. Active class is hash-aware — only the matching tab lights up. Setting `hash` forces the slow path (the fast-path `routeSelector` is hash-agnostic). 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.
 
 ### `<RouteView>`
 
@@ -526,6 +526,25 @@ 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`. Options are read once on mount — changing the prop at runtime does not reconfigure the utility (Solid `onMount` is non-reactive). 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:
+
+```tsx
+<RouterProvider
+  router={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 }`. Empty `selector` / `undefined` = off. Read once on mount (Solid `onMount` is non-reactive). 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):
@@ -542,7 +561,7 @@ No-op on unsupported browsers (Firefox as of 2026-04, SSR). Prop is read once on
 
 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)
 - Solid-specific store variants: [useRouteStore / useRouteNodeStore](https://github.com/greydragon888/real-router/wiki/Solid-Integration#store-based-granular-route-state) — `createStore` + `reconcile`, property-level reactivity
 

package/dist/cjs/index.d.ts

@@ -301,10 +301,70 @@ interface ScrollRestorationOptions {
     storageKey?: string | undefined;
 }
 
+/**
+ * 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.
+ */
+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;
+}
+
 interface RouteProviderProps {
     router: Router;
     announceNavigation?: boolean;
     scrollRestoration?: ScrollRestorationOptions;
+    scrollSpy?: ScrollSpyOptions;
     viewTransitions?: boolean;
 }
 declare function RouterProvider(props: ParentProps<RouteProviderProps>): JSX.Element;

package/dist/esm/index.d.mts

@@ -301,10 +301,70 @@ interface ScrollRestorationOptions {
     storageKey?: string | undefined;
 }
 
+/**
+ * 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.
+ */
+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;
+}
+
 interface RouteProviderProps {
     router: Router;
     announceNavigation?: boolean;
     scrollRestoration?: ScrollRestorationOptions;
+    scrollSpy?: ScrollSpyOptions;
     viewTransitions?: boolean;
 }
 declare function RouterProvider(props: ParentProps<RouteProviderProps>): JSX.Element;

package/dist/types/RouterProvider.d.ts

@@ -1,10 +1,11 @@
-import type { ScrollRestorationOptions } from "./dom-utils";
+import type { ScrollRestorationOptions, ScrollSpyOptions } from "./dom-utils";
 import type { Router } from "@real-router/core";
 import type { ParentProps, JSX } from "solid-js";
 export interface RouteProviderProps {
     router: Router;
     announceNavigation?: boolean;
     scrollRestoration?: ScrollRestorationOptions;
+    scrollSpy?: ScrollSpyOptions;
     viewTransitions?: boolean;
 }
 export declare function isRouteActive(linkRouteName: string, currentRouteName: string): boolean;

package/dist/types/RouterProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RouterProvider.d.ts","sourceRoot":"","sources":["../../src/RouterProvider.tsx"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAEjD,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,iBAAiB,CAAC,EAAE,wBAAwB,CAAC;IAC7C,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,wBAAgB,aAAa,CAC3B,aAAa,EAAE,MAAM,EACrB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAKT;AAwBD,wBAAgB,cAAc,CAC5B,KAAK,EAAE,WAAW,CAAC,kBAAkB,CAAC,GACrC,GAAG,CAAC,OAAO,CAuCb"}
+{"version":3,"file":"RouterProvider.d.ts","sourceRoot":"","sources":["../../src/RouterProvider.tsx"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,wBAAwB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAEjD,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,iBAAiB,CAAC,EAAE,wBAAwB,CAAC;IAC7C,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,wBAAgB,aAAa,CAC3B,aAAa,EAAE,MAAM,EACrB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAKT;AAwBD,wBAAgB,cAAc,CAC5B,KAAK,EAAE,WAAW,CAAC,kBAAkB,CAAC,GACrC,GAAG,CAAC,OAAO,CAoDb"}

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

@@ -1,10 +1,12 @@
 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";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/dom-utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAE5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,OAAO,EACL,cAAc,EACd,SAAS,EACT,oBAAoB,EACpB,gBAAgB,EAChB,YAAY,EACZ,aAAa,GACd,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAElE,YAAY,EACV,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAE7B,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,YAAY,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/dom-utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAE5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElD,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,OAAO,EACL,cAAc,EACd,SAAS,EACT,oBAAoB,EACpB,gBAAgB,EAChB,YAAY,EACZ,aAAa,GACd,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAElE,YAAY,EACV,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAE7B,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnE,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,YAAY,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/types/dom-utils/scroll-restore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scroll-restore.d.ts","sourceRoot":"","sources":["../../../src/dom-utils/scroll-restore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAUvD,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,KAAK,GAAG,QAAQ,CAAC;AAEjE,MAAM,WAAW,wBAAwB;IACvC,IAAI,CAAC,EAAE,qBAAqB,GAAG,SAAS,CAAC;IACzC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,eAAe,CAAC,EAAE,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,SAAS,CAAC;IACzD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IACtC;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAOD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,wBAAwB,GACjC;IAAE,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAgQzB;AA2BD,wBAAgB,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAY1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD"}
+{"version":3,"file":"scroll-restore.d.ts","sourceRoot":"","sources":["../../../src/dom-utils/scroll-restore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAkBvD,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,KAAK,GAAG,QAAQ,CAAC;AAEjE,MAAM,WAAW,wBAAwB;IACvC,IAAI,CAAC,EAAE,qBAAqB,GAAG,SAAS,CAAC;IACzC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,eAAe,CAAC,EAAE,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,SAAS,CAAC;IACzD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IACtC;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAOD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,wBAAwB,GACjC;IAAE,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CA+UzB;AA2BD,wBAAgB,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAY1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD"}

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

@@ -0,0 +1,65 @@
+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;
+//# sourceMappingURL=scroll-spy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-spy.d.ts","sourceRoot":"","sources":["../../../src/dom-utils/scroll-spy.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAqB,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAEhC;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,SAAS,CAAC;CAC1D;AAED,MAAM,WAAW,SAAS;IACxB,kDAAkD;IAClD,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAuaD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,gBAAgB,GACxB,SAAS,CAiMX"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/solid",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "type": "commonjs",
   "description": "Solid.js integration for Real-Router",
   "main": "./dist/cjs/index.js",
@@ -67,27 +67,27 @@
   "license": "MIT",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.54.1",
+    "@real-router/core": "^0.55.0",
     "@real-router/route-utils": "^0.2.2",
-    "@real-router/sources": "^0.8.3"
+    "@real-router/sources": "^0.8.4"
   },
   "devDependencies": {
-    "@babel/core": "7.29.0",
-    "@babel/preset-typescript": "7.28.5",
-    "@rollup/plugin-babel": "7.0.0",
+    "@babel/core": "7.29.7",
+    "@babel/preset-typescript": "7.29.7",
+    "@rollup/plugin-babel": "7.1.0",
     "@rollup/plugin-node-resolve": "16.0.3",
     "@solidjs/testing-library": "0.8.10",
     "@testing-library/dom": "10.4.1",
     "@testing-library/jest-dom": "6.9.1",
     "@testing-library/user-event": "14.6.1",
-    "babel-preset-solid": "1.9.3",
+    "babel-preset-solid": "1.9.12",
     "rimraf": "6.1.3",
-    "rollup": "4.60.2",
+    "rollup": "4.61.0",
     "rollup-plugin-dts": "6.4.1",
     "solid-js": "1.9.12",
     "vite-plugin-solid": "2.11.11",
-    "vitest": "4.1.6",
-    "@real-router/browser-plugin": "^0.17.4"
+    "vitest": "4.1.8",
+    "@real-router/browser-plugin": "^0.17.5"
   },
   "peerDependencies": {
     "solid-js": ">=1.7.0"

package/src/RouterProvider.tsx

@@ -7,10 +7,11 @@ import { createSignalFromSource } from "./createSignalFromSource";
 import {
   createRouteAnnouncer,
   createScrollRestoration,
+  createScrollSpy,
   createViewTransitions,
 } from "./dom-utils";
 
-import type { ScrollRestorationOptions } from "./dom-utils";
+import type { ScrollRestorationOptions, ScrollSpyOptions } from "./dom-utils";
 import type { Router } from "@real-router/core";
 import type { ParentProps, JSX } from "solid-js";
 
@@ -18,6 +19,7 @@ export interface RouteProviderProps {
   router: Router;
   announceNavigation?: boolean;
   scrollRestoration?: ScrollRestorationOptions;
+  scrollSpy?: ScrollSpyOptions;
   viewTransitions?: boolean;
 }
 
@@ -81,6 +83,19 @@ export function RouterProvider(
   mountFeature(props.scrollRestoration, () =>
     createScrollRestoration(props.router, props.scrollRestoration),
   );
+  onMount(() => {
+    const spyOpts = props.scrollSpy;
+
+    if (spyOpts === undefined || spyOpts.selector === "") {
+      return;
+    }
+
+    const spy = createScrollSpy(props.router, spyOpts);
+
+    onCleanup(() => {
+      spy.destroy();
+    });
+  });
   mountFeature(props.viewTransitions, () =>
     createViewTransitions(props.router),
   );