@real-router/solid 0.9.1 → 0.11.0

package/README.md

@@ -191,6 +191,15 @@ Navigation link with automatic active state detection. Uses `classList` for acti
 </Link>
 ```
 
+#### `hash` prop — URL fragment / tab-style UIs
+
+```tsx
+<Link routeName="settings" hash="profile">Profile</Link>
+<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.
+
 ### `<RouteView>`
 
 Declarative route matching. Renders the first matching `<RouteView.Match>` child.
@@ -363,7 +372,7 @@ Opt-in preservation of scroll position across navigations:
 </RouterProvider>
 ```
 
-Restores scroll on back/forward, scrolls to top (or `#hash`) on push. Three modes: `"restore"` (default), `"top"`, `"manual"`. 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). See [Scroll Restoration guide](https://github.com/greydragon888/real-router/wiki/Scroll-Restoration) for details.
+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). See [Scroll Restoration guide](https://github.com/greydragon888/real-router/wiki/Scroll-Restoration) for details.
 
 ## View Transitions
 

package/dist/cjs/index.d.ts

@@ -61,6 +61,13 @@ interface LinkProps<P extends Params = Params> extends Omit<JSX.HTMLAttributes<H
     activeClassName?: string;
     activeStrict?: boolean;
     ignoreQueryParams?: boolean;
+    /**
+     * URL fragment (decoded form, no leading "#") (#532).
+     * - omitted/`undefined` → preserve current fragment on same-route navigation
+     * - `""` → clear fragment
+     * - non-empty → set fragment
+     */
+    hash?: string;
     target?: string;
     onClick?: (evt: MouseEvent) => void;
 }
@@ -266,11 +273,32 @@ interface UseRouteEnterOptions {
  */
 declare function useRouteEnter(handler: RouteEnterHandler, options?: UseRouteEnterOptions): void;
 
-type ScrollRestorationMode = "restore" | "top" | "manual";
+type ScrollRestorationMode = "restore" | "top" | "native";
 interface ScrollRestorationOptions {
     mode?: ScrollRestorationMode | undefined;
     anchorScrolling?: boolean | undefined;
     scrollContainer?: (() => HTMLElement | null) | undefined;
+    /**
+     * Scroll behavior passed to `scrollTo({ behavior })` and
+     * `scrollIntoView({ behavior })`.
+     *
+     * - `"auto"` (default) — browser-defined, usually instant.
+     * - `"instant"` — explicit instant jump (no animation).
+     * - `"smooth"` — animated transition. Note: smooth restore on back/traverse
+     *   can feel disorienting if the user expects to land at the saved position
+     *   immediately. Recommended for `mode: "top"` or anchor scroll only.
+     *
+     * See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/ScrollToOptions/behavior).
+     */
+    behavior?: ScrollBehavior | undefined;
+    /**
+     * sessionStorage key used to persist saved scroll positions. Default:
+     * `"real-router:scroll"`. Override only when multiple independent
+     * `RouterProvider` instances share the same document and you need to
+     * isolate their scroll stores (e.g. micro-frontends, embedded widgets,
+     * or testing). For a single app with one provider the default is fine.
+     */
+    storageKey?: string | undefined;
 }
 
 interface RouteProviderProps {

package/dist/cjs/index.js

@@ -336,7 +336,7 @@ function manageFocus(h1) {
   });
 }
 
-const STORAGE_KEY = "real-router:scroll";
+const DEFAULT_STORAGE_KEY = "real-router:scroll";
 const NOOP_INSTANCE$1 = Object.freeze({
   destroy: () => {
     /* no-op */
@@ -348,14 +348,36 @@ function createScrollRestoration(router, options) {
   }
   const mode = options?.mode ?? "restore";
 
-  // mode "manual" = utility does nothing. Don't flip history.scrollRestoration,
-  // don't subscribe, don't register pagehide — leave the browser's native
-  // auto-restore intact for the app to override if it wants to.
-  if (mode === "manual") {
+  // mode "native" = utility does nothing. Don't flip history.scrollRestoration,
+  // don't subscribe, don't register pagehide — `history.scrollRestoration`
+  // stays at the browser default ("auto") so the browser handles scroll
+  // restore natively. (Note: this is the OPPOSITE of `history.scrollRestoration
+  // === "manual"` — utility's "native" leaves the DOM property at "auto" so
+  // the browser is in charge.)
+  if (mode === "native") {
     return NOOP_INSTANCE$1;
   }
   const anchorEnabled = options?.anchorScrolling ?? true;
   const getContainer = options?.scrollContainer;
+  const behavior = options?.behavior ?? "auto";
+  const storageKey = options?.storageKey ?? DEFAULT_STORAGE_KEY;
+  const loadStore = () => {
+    try {
+      const raw = sessionStorage.getItem(storageKey);
+      return raw ? JSON.parse(raw) : {};
+    } catch {
+      return {};
+    }
+  };
+  const putPos = (key, pos) => {
+    try {
+      const store = loadStore();
+      store[key] = pos;
+      sessionStorage.setItem(storageKey, JSON.stringify(store));
+    } catch {
+      // Ignore quota / security errors.
+    }
+  };
   const prevScrollRestoration = history.scrollRestoration;
   try {
     history.scrollRestoration = "manual";
@@ -373,17 +395,46 @@ function createScrollRestoration(router, options) {
   const writePos = top => {
     const element = getContainer?.();
     if (element) {
-      element.scrollTop = top;
+      element.scrollTo({
+        top,
+        left: 0,
+        behavior
+      });
     } else {
-      globalThis.scrollTo(0, top);
+      globalThis.scrollTo({
+        top,
+        left: 0,
+        behavior
+      });
     }
   };
-  const scrollToHashOrTop = () => {
+  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
+    // installed. The value is already DECODED — feeding it through
+    // `decodeURIComponent` again would throw on a bare `%`.
+    const ctxHash = route.context?.url?.hash;
+    if (ctxHash !== undefined) {
+      if (anchorEnabled && ctxHash.length > 0) {
+        // eslint-disable-next-line unicorn/prefer-query-selector -- ids may contain CSS-unsafe chars
+        const element = document.getElementById(ctxHash);
+        if (element) {
+          element.scrollIntoView({
+            behavior
+          });
+          return;
+        }
+      }
+      writePos(0);
+      return;
+    }
+
+    // Fallback path: no URL plugin, read the DOM. `location.hash` is
+    // percent-encoded; ids in the DOM are the raw string, so decode for the
+    // match. Fall back to the raw slice if the hash contains a malformed
+    // escape sequence (decodeURIComponent throws on those).
     const hash = globalThis.location.hash;
     if (anchorEnabled && hash.length > 1) {
-      // location.hash is percent-encoded; ids in the DOM are the raw string.
-      // Decode for the match. Fall back to the raw slice if the hash contains
-      // a malformed escape sequence (decodeURIComponent throws on those).
       let id;
       try {
         id = decodeURIComponent(hash.slice(1));
@@ -394,7 +445,9 @@ function createScrollRestoration(router, options) {
       // eslint-disable-next-line unicorn/prefer-query-selector -- ids may contain CSS-unsafe chars
       const element = document.getElementById(id);
       if (element) {
-        element.scrollIntoView();
+        element.scrollIntoView({
+          behavior
+        });
         return;
       }
     }
@@ -421,7 +474,7 @@ function createScrollRestoration(router, options) {
         return;
       }
       if (mode === "top" || !nav) {
-        scrollToHashOrTop();
+        scrollToHashOrTop(route);
         return;
       }
       if (nav.navigationType === "replace") {
@@ -431,7 +484,7 @@ function createScrollRestoration(router, options) {
         writePos(loadStore()[keyOf(route)] ?? 0);
         return;
       }
-      scrollToHashOrTop();
+      scrollToHashOrTop(route);
     });
   });
   const onPageHide = () => {
@@ -460,23 +513,6 @@ function createScrollRestoration(router, options) {
 function keyOf(state) {
   return `${state.name}:${canonicalJson(state.params)}`;
 }
-function loadStore() {
-  try {
-    const raw = sessionStorage.getItem(STORAGE_KEY);
-    return raw ? JSON.parse(raw) : {};
-  } catch {
-    return {};
-  }
-}
-function putPos(key, pos) {
-  try {
-    const store = loadStore();
-    store[key] = pos;
-    sessionStorage.setItem(STORAGE_KEY, JSON.stringify(store));
-  } catch {
-    // Ignore quota / security errors.
-  }
-}
 function canonicalJson(value) {
   return JSON.stringify(value, canonicalReplacer);
 }
@@ -618,21 +654,94 @@ function createViewTransitions(router) {
 function shouldNavigate(evt) {
   return evt.button === 0 && !evt.metaKey && !evt.altKey && !evt.ctrlKey && !evt.shiftKey;
 }
-function buildHref(router, routeName, routeParams) {
+
+/**
+ * RFC 3986 fragment encoding: preserve sub-delims (`&`, `=`, `?`, `:`),
+ * encode space, `%`, control chars, non-ASCII via encodeURI; defensively
+ * escape `#` (encodeURI does not). Mirrors `encodeHashFragment` in
+ * `shared/browser-env/url-context.ts` — duplicated here because the
+ * shared/dom-utils symlink graph does not reach shared/browser-env.
+ */
+function encodeFragmentInline(decoded) {
+  return encodeURI(decoded).replaceAll("#", "%23");
+}
+/**
+ * Builds an href for a `<Link>` element.
+ *
+ * - Prefers the URL plugin's `buildUrl` (browser-plugin, navigation-plugin,
+ *   hash-plugin) when present.
+ * - Falls back to `router.buildPath` for runtimes without a URL plugin
+ *   (memory-plugin, console UIs, NativeScript). In that fallback the hash
+ *   is appended manually so the rendered href is still correct.
+ * - The optional 4th argument is an options object so the contract stays
+ *   extensible. The `hash` option is a decoded fragment without leading "#";
+ *   `<Link hash="#section">` is accepted defensively (leading "#" stripped).
+ *   Frozen API: previous 3-arg call sites continue to work unchanged.
+ */
+function buildHref(router, routeName, routeParams, options) {
   try {
+    const rawHash = options?.hash;
+    let normHash;
+    if (rawHash !== undefined) {
+      normHash = rawHash.startsWith("#") ? rawHash.slice(1) : rawHash;
+    }
     const buildUrl = router.buildUrl;
     if (buildUrl) {
-      const url = buildUrl(routeName, routeParams);
+      const url = buildUrl(routeName, routeParams, normHash === undefined ? undefined : {
+        hash: normHash
+      });
       if (url !== undefined) {
         return url;
       }
     }
-    return router.buildPath(routeName, routeParams);
+    const path = router.buildPath(routeName, routeParams);
+    return normHash ? `${path}#${encodeFragmentInline(normHash)}` : path;
   } catch {
     console.error(`[real-router] Route "${routeName}" is not defined. The element will render without an href attribute.`);
     return undefined;
   }
 }
+
+/**
+ * `<Link>` click-handler navigation helper (#532).
+ *
+ * Wraps `router.navigate(name, params, opts)` with same-route different-hash
+ * detection: when the consumer clicks a hash-bearing Link that targets the
+ * current route with the same params but a different fragment, core's
+ * SAME_STATES check would otherwise reject the navigation. The helper adds
+ * `force: true` and `hashChange: true` automatically — subscribers can then
+ * disambiguate via `state.context.url.hashChanged`.
+ *
+ * For pure programmatic same-route hash-only navigation, callers are
+ * documented to pass `{ force: true }` themselves; the auto-bypass here is
+ * a UX convenience for `<Link hash>` that all 6 framework adapters share.
+ */
+/**
+ * Local extended-options type. Adapters that depend only on `@real-router/core`
+ * (without a URL plugin) do not see the `NavigationOptions` augmentation that
+ * declares `hash` / `hashChange`. Casting to this widened type inside the
+ * helper keeps shared/dom-utils self-contained — adapters do not need to
+ * augment NavigationOptions themselves to consume `<Link hash>`.
+ */
+
+function navigateWithHash(router, routeName, routeParams, hash, extraOptions) {
+  const opts = {
+    ...extraOptions
+  };
+  if (hash !== undefined) {
+    opts.hash = hash;
+  }
+  const current = router.getState();
+  if (current?.name === routeName && shallowEqual(current.params, routeParams)) {
+    const currentHash = current.context?.url?.hash ?? "";
+    const newHash = hash ?? currentHash;
+    if (currentHash !== newHash) {
+      opts.force = true;
+      opts.hashChange = true;
+    }
+  }
+  return router.navigate(routeName, routeParams, opts);
+}
 function parseTokens(value) {
   return value ? value.match(/\S+/g) ?? [] : [];
 }
@@ -657,6 +766,26 @@ function buildActiveClassName(isActive, activeClassName, baseClassName) {
   }
   return baseClassName ?? undefined;
 }
+function shallowEqual(prev, next) {
+  if (Object.is(prev, next)) {
+    return true;
+  }
+  if (!prev || !next) {
+    return false;
+  }
+  const prevKeys = Object.keys(prev);
+  if (prevKeys.length !== Object.keys(next).length) {
+    return false;
+  }
+  const prevRecord = prev;
+  const nextRecord = next;
+  for (const key of prevKeys) {
+    if (!Object.is(prevRecord[key], nextRecord[key])) {
+      return false;
+    }
+  }
+  return true;
+}
 function applyLinkA11y(element) {
   if (!element) {
     return;
@@ -681,18 +810,35 @@ function Link(props) {
     activeStrict: false,
     ignoreQueryParams: true
   }, props);
-  const [local, rest] = solidJs.splitProps(merged, ["routeName", "routeParams", "routeOptions", "activeClassName", "activeStrict", "ignoreQueryParams", "onClick", "target", "class", "children"]);
+  const [local, rest] = solidJs.splitProps(merged, ["routeName", "routeParams", "routeOptions", "activeClassName", "activeStrict", "ignoreQueryParams", "hash", "onClick", "target", "class", "children"]);
   const ctx = solidJs.useContext(RouterContext);
   if (!ctx) {
     throw new Error("Link must be used within a RouterProvider");
   }
   const router = ctx.router;
-  const useFastPath = !local.activeStrict && local.ignoreQueryParams && local.routeParams === EMPTY_PARAMS;
-  const isActive = useFastPath ? () => ctx.routeSelector(local.routeName) : createSignalFromSource(sources.createActiveRouteSource(router, local.routeName, local.routeParams, {
-    strict: local.activeStrict,
-    ignoreQueryParams: local.ignoreQueryParams
+
+  // Hash-aware active state (#532). `routeSelector` (the O(1) shared selector)
+  // doesn't know about hash — when `hash` prop is set, fall back to the slow
+  // path so the source's hash comparison kicks in. Tab-style UI is opt-in via
+  // the prop, so the fast path stays open for the typical Link case.
+  const useFastPath = local.hash === undefined && !local.activeStrict && local.ignoreQueryParams && local.routeParams === EMPTY_PARAMS;
+  const buildActiveOptions = () => {
+    const base = {
+      strict: local.activeStrict,
+      ignoreQueryParams: local.ignoreQueryParams
+    };
+    if (local.hash === undefined) {
+      return base;
+    }
+    return {
+      ...base,
+      hash: local.hash
+    };
+  };
+  const isActive = useFastPath ? () => ctx.routeSelector(local.routeName) : createSignalFromSource(sources.createActiveRouteSource(router, local.routeName, local.routeParams, buildActiveOptions()));
+  const href = solidJs.createMemo(() => buildHref(router, local.routeName, local.routeParams, local.hash === undefined ? undefined : {
+    hash: local.hash
   }));
-  const href = solidJs.createMemo(() => buildHref(router, local.routeName, local.routeParams));
   const handleClick = evt => {
     if (local.onClick) {
       local.onClick(evt);
@@ -704,7 +850,7 @@ function Link(props) {
       return;
     }
     evt.preventDefault();
-    router.navigate(local.routeName, local.routeParams, local.routeOptions).catch(() => {});
+    navigateWithHash(router, local.routeName, local.routeParams, local.hash, local.routeOptions).catch(() => {});
   };
   const finalClassName = solidJs.createMemo(() => buildActiveClassName(isActive(), local.activeClassName, local.class));
   return (() => {

package/dist/esm/index.d.mts

@@ -61,6 +61,13 @@ interface LinkProps<P extends Params = Params> extends Omit<JSX.HTMLAttributes<H
     activeClassName?: string;
     activeStrict?: boolean;
     ignoreQueryParams?: boolean;
+    /**
+     * URL fragment (decoded form, no leading "#") (#532).
+     * - omitted/`undefined` → preserve current fragment on same-route navigation
+     * - `""` → clear fragment
+     * - non-empty → set fragment
+     */
+    hash?: string;
     target?: string;
     onClick?: (evt: MouseEvent) => void;
 }
@@ -266,11 +273,32 @@ interface UseRouteEnterOptions {
  */
 declare function useRouteEnter(handler: RouteEnterHandler, options?: UseRouteEnterOptions): void;
 
-type ScrollRestorationMode = "restore" | "top" | "manual";
+type ScrollRestorationMode = "restore" | "top" | "native";
 interface ScrollRestorationOptions {
     mode?: ScrollRestorationMode | undefined;
     anchorScrolling?: boolean | undefined;
     scrollContainer?: (() => HTMLElement | null) | undefined;
+    /**
+     * Scroll behavior passed to `scrollTo({ behavior })` and
+     * `scrollIntoView({ behavior })`.
+     *
+     * - `"auto"` (default) — browser-defined, usually instant.
+     * - `"instant"` — explicit instant jump (no animation).
+     * - `"smooth"` — animated transition. Note: smooth restore on back/traverse
+     *   can feel disorienting if the user expects to land at the saved position
+     *   immediately. Recommended for `mode: "top"` or anchor scroll only.
+     *
+     * See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/ScrollToOptions/behavior).
+     */
+    behavior?: ScrollBehavior | undefined;
+    /**
+     * sessionStorage key used to persist saved scroll positions. Default:
+     * `"real-router:scroll"`. Override only when multiple independent
+     * `RouterProvider` instances share the same document and you need to
+     * isolate their scroll stores (e.g. micro-frontends, embedded widgets,
+     * or testing). For a single app with one provider the default is fine.
+     */
+    storageKey?: string | undefined;
 }
 
 interface RouteProviderProps {

package/dist/esm/index.mjs

@@ -334,7 +334,7 @@ function manageFocus(h1) {
   });
 }
 
-const STORAGE_KEY = "real-router:scroll";
+const DEFAULT_STORAGE_KEY = "real-router:scroll";
 const NOOP_INSTANCE$1 = Object.freeze({
   destroy: () => {
     /* no-op */
@@ -346,14 +346,36 @@ function createScrollRestoration(router, options) {
   }
   const mode = options?.mode ?? "restore";
 
-  // mode "manual" = utility does nothing. Don't flip history.scrollRestoration,
-  // don't subscribe, don't register pagehide — leave the browser's native
-  // auto-restore intact for the app to override if it wants to.
-  if (mode === "manual") {
+  // mode "native" = utility does nothing. Don't flip history.scrollRestoration,
+  // don't subscribe, don't register pagehide — `history.scrollRestoration`
+  // stays at the browser default ("auto") so the browser handles scroll
+  // restore natively. (Note: this is the OPPOSITE of `history.scrollRestoration
+  // === "manual"` — utility's "native" leaves the DOM property at "auto" so
+  // the browser is in charge.)
+  if (mode === "native") {
     return NOOP_INSTANCE$1;
   }
   const anchorEnabled = options?.anchorScrolling ?? true;
   const getContainer = options?.scrollContainer;
+  const behavior = options?.behavior ?? "auto";
+  const storageKey = options?.storageKey ?? DEFAULT_STORAGE_KEY;
+  const loadStore = () => {
+    try {
+      const raw = sessionStorage.getItem(storageKey);
+      return raw ? JSON.parse(raw) : {};
+    } catch {
+      return {};
+    }
+  };
+  const putPos = (key, pos) => {
+    try {
+      const store = loadStore();
+      store[key] = pos;
+      sessionStorage.setItem(storageKey, JSON.stringify(store));
+    } catch {
+      // Ignore quota / security errors.
+    }
+  };
   const prevScrollRestoration = history.scrollRestoration;
   try {
     history.scrollRestoration = "manual";
@@ -371,17 +393,46 @@ function createScrollRestoration(router, options) {
   const writePos = top => {
     const element = getContainer?.();
     if (element) {
-      element.scrollTop = top;
+      element.scrollTo({
+        top,
+        left: 0,
+        behavior
+      });
     } else {
-      globalThis.scrollTo(0, top);
+      globalThis.scrollTo({
+        top,
+        left: 0,
+        behavior
+      });
     }
   };
-  const scrollToHashOrTop = () => {
+  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
+    // installed. The value is already DECODED — feeding it through
+    // `decodeURIComponent` again would throw on a bare `%`.
+    const ctxHash = route.context?.url?.hash;
+    if (ctxHash !== undefined) {
+      if (anchorEnabled && ctxHash.length > 0) {
+        // eslint-disable-next-line unicorn/prefer-query-selector -- ids may contain CSS-unsafe chars
+        const element = document.getElementById(ctxHash);
+        if (element) {
+          element.scrollIntoView({
+            behavior
+          });
+          return;
+        }
+      }
+      writePos(0);
+      return;
+    }
+
+    // Fallback path: no URL plugin, read the DOM. `location.hash` is
+    // percent-encoded; ids in the DOM are the raw string, so decode for the
+    // match. Fall back to the raw slice if the hash contains a malformed
+    // escape sequence (decodeURIComponent throws on those).
     const hash = globalThis.location.hash;
     if (anchorEnabled && hash.length > 1) {
-      // location.hash is percent-encoded; ids in the DOM are the raw string.
-      // Decode for the match. Fall back to the raw slice if the hash contains
-      // a malformed escape sequence (decodeURIComponent throws on those).
       let id;
       try {
         id = decodeURIComponent(hash.slice(1));
@@ -392,7 +443,9 @@ function createScrollRestoration(router, options) {
       // eslint-disable-next-line unicorn/prefer-query-selector -- ids may contain CSS-unsafe chars
       const element = document.getElementById(id);
       if (element) {
-        element.scrollIntoView();
+        element.scrollIntoView({
+          behavior
+        });
         return;
       }
     }
@@ -419,7 +472,7 @@ function createScrollRestoration(router, options) {
         return;
       }
       if (mode === "top" || !nav) {
-        scrollToHashOrTop();
+        scrollToHashOrTop(route);
         return;
       }
       if (nav.navigationType === "replace") {
@@ -429,7 +482,7 @@ function createScrollRestoration(router, options) {
         writePos(loadStore()[keyOf(route)] ?? 0);
         return;
       }
-      scrollToHashOrTop();
+      scrollToHashOrTop(route);
     });
   });
   const onPageHide = () => {
@@ -458,23 +511,6 @@ function createScrollRestoration(router, options) {
 function keyOf(state) {
   return `${state.name}:${canonicalJson(state.params)}`;
 }
-function loadStore() {
-  try {
-    const raw = sessionStorage.getItem(STORAGE_KEY);
-    return raw ? JSON.parse(raw) : {};
-  } catch {
-    return {};
-  }
-}
-function putPos(key, pos) {
-  try {
-    const store = loadStore();
-    store[key] = pos;
-    sessionStorage.setItem(STORAGE_KEY, JSON.stringify(store));
-  } catch {
-    // Ignore quota / security errors.
-  }
-}
 function canonicalJson(value) {
   return JSON.stringify(value, canonicalReplacer);
 }
@@ -616,21 +652,94 @@ function createViewTransitions(router) {
 function shouldNavigate(evt) {
   return evt.button === 0 && !evt.metaKey && !evt.altKey && !evt.ctrlKey && !evt.shiftKey;
 }
-function buildHref(router, routeName, routeParams) {
+
+/**
+ * RFC 3986 fragment encoding: preserve sub-delims (`&`, `=`, `?`, `:`),
+ * encode space, `%`, control chars, non-ASCII via encodeURI; defensively
+ * escape `#` (encodeURI does not). Mirrors `encodeHashFragment` in
+ * `shared/browser-env/url-context.ts` — duplicated here because the
+ * shared/dom-utils symlink graph does not reach shared/browser-env.
+ */
+function encodeFragmentInline(decoded) {
+  return encodeURI(decoded).replaceAll("#", "%23");
+}
+/**
+ * Builds an href for a `<Link>` element.
+ *
+ * - Prefers the URL plugin's `buildUrl` (browser-plugin, navigation-plugin,
+ *   hash-plugin) when present.
+ * - Falls back to `router.buildPath` for runtimes without a URL plugin
+ *   (memory-plugin, console UIs, NativeScript). In that fallback the hash
+ *   is appended manually so the rendered href is still correct.
+ * - The optional 4th argument is an options object so the contract stays
+ *   extensible. The `hash` option is a decoded fragment without leading "#";
+ *   `<Link hash="#section">` is accepted defensively (leading "#" stripped).
+ *   Frozen API: previous 3-arg call sites continue to work unchanged.
+ */
+function buildHref(router, routeName, routeParams, options) {
   try {
+    const rawHash = options?.hash;
+    let normHash;
+    if (rawHash !== undefined) {
+      normHash = rawHash.startsWith("#") ? rawHash.slice(1) : rawHash;
+    }
     const buildUrl = router.buildUrl;
     if (buildUrl) {
-      const url = buildUrl(routeName, routeParams);
+      const url = buildUrl(routeName, routeParams, normHash === undefined ? undefined : {
+        hash: normHash
+      });
       if (url !== undefined) {
         return url;
       }
     }
-    return router.buildPath(routeName, routeParams);
+    const path = router.buildPath(routeName, routeParams);
+    return normHash ? `${path}#${encodeFragmentInline(normHash)}` : path;
   } catch {
     console.error(`[real-router] Route "${routeName}" is not defined. The element will render without an href attribute.`);
     return undefined;
   }
 }
+
+/**
+ * `<Link>` click-handler navigation helper (#532).
+ *
+ * Wraps `router.navigate(name, params, opts)` with same-route different-hash
+ * detection: when the consumer clicks a hash-bearing Link that targets the
+ * current route with the same params but a different fragment, core's
+ * SAME_STATES check would otherwise reject the navigation. The helper adds
+ * `force: true` and `hashChange: true` automatically — subscribers can then
+ * disambiguate via `state.context.url.hashChanged`.
+ *
+ * For pure programmatic same-route hash-only navigation, callers are
+ * documented to pass `{ force: true }` themselves; the auto-bypass here is
+ * a UX convenience for `<Link hash>` that all 6 framework adapters share.
+ */
+/**
+ * Local extended-options type. Adapters that depend only on `@real-router/core`
+ * (without a URL plugin) do not see the `NavigationOptions` augmentation that
+ * declares `hash` / `hashChange`. Casting to this widened type inside the
+ * helper keeps shared/dom-utils self-contained — adapters do not need to
+ * augment NavigationOptions themselves to consume `<Link hash>`.
+ */
+
+function navigateWithHash(router, routeName, routeParams, hash, extraOptions) {
+  const opts = {
+    ...extraOptions
+  };
+  if (hash !== undefined) {
+    opts.hash = hash;
+  }
+  const current = router.getState();
+  if (current?.name === routeName && shallowEqual(current.params, routeParams)) {
+    const currentHash = current.context?.url?.hash ?? "";
+    const newHash = hash ?? currentHash;
+    if (currentHash !== newHash) {
+      opts.force = true;
+      opts.hashChange = true;
+    }
+  }
+  return router.navigate(routeName, routeParams, opts);
+}
 function parseTokens(value) {
   return value ? value.match(/\S+/g) ?? [] : [];
 }
@@ -655,6 +764,26 @@ function buildActiveClassName(isActive, activeClassName, baseClassName) {
   }
   return baseClassName ?? undefined;
 }
+function shallowEqual(prev, next) {
+  if (Object.is(prev, next)) {
+    return true;
+  }
+  if (!prev || !next) {
+    return false;
+  }
+  const prevKeys = Object.keys(prev);
+  if (prevKeys.length !== Object.keys(next).length) {
+    return false;
+  }
+  const prevRecord = prev;
+  const nextRecord = next;
+  for (const key of prevKeys) {
+    if (!Object.is(prevRecord[key], nextRecord[key])) {
+      return false;
+    }
+  }
+  return true;
+}
 function applyLinkA11y(element) {
   if (!element) {
     return;
@@ -679,18 +808,35 @@ function Link(props) {
     activeStrict: false,
     ignoreQueryParams: true
   }, props);
-  const [local, rest] = splitProps(merged, ["routeName", "routeParams", "routeOptions", "activeClassName", "activeStrict", "ignoreQueryParams", "onClick", "target", "class", "children"]);
+  const [local, rest] = splitProps(merged, ["routeName", "routeParams", "routeOptions", "activeClassName", "activeStrict", "ignoreQueryParams", "hash", "onClick", "target", "class", "children"]);
   const ctx = useContext(RouterContext);
   if (!ctx) {
     throw new Error("Link must be used within a RouterProvider");
   }
   const router = ctx.router;
-  const useFastPath = !local.activeStrict && local.ignoreQueryParams && local.routeParams === EMPTY_PARAMS;
-  const isActive = useFastPath ? () => ctx.routeSelector(local.routeName) : createSignalFromSource(createActiveRouteSource(router, local.routeName, local.routeParams, {
-    strict: local.activeStrict,
-    ignoreQueryParams: local.ignoreQueryParams
+
+  // Hash-aware active state (#532). `routeSelector` (the O(1) shared selector)
+  // doesn't know about hash — when `hash` prop is set, fall back to the slow
+  // path so the source's hash comparison kicks in. Tab-style UI is opt-in via
+  // the prop, so the fast path stays open for the typical Link case.
+  const useFastPath = local.hash === undefined && !local.activeStrict && local.ignoreQueryParams && local.routeParams === EMPTY_PARAMS;
+  const buildActiveOptions = () => {
+    const base = {
+      strict: local.activeStrict,
+      ignoreQueryParams: local.ignoreQueryParams
+    };
+    if (local.hash === undefined) {
+      return base;
+    }
+    return {
+      ...base,
+      hash: local.hash
+    };
+  };
+  const isActive = useFastPath ? () => ctx.routeSelector(local.routeName) : createSignalFromSource(createActiveRouteSource(router, local.routeName, local.routeParams, buildActiveOptions()));
+  const href = createMemo(() => buildHref(router, local.routeName, local.routeParams, local.hash === undefined ? undefined : {
+    hash: local.hash
   }));
-  const href = createMemo(() => buildHref(router, local.routeName, local.routeParams));
   const handleClick = evt => {
     if (local.onClick) {
       local.onClick(evt);
@@ -702,7 +848,7 @@ function Link(props) {
       return;
     }
     evt.preventDefault();
-    router.navigate(local.routeName, local.routeParams, local.routeOptions).catch(() => {});
+    navigateWithHash(router, local.routeName, local.routeParams, local.hash, local.routeOptions).catch(() => {});
   };
   const finalClassName = createMemo(() => buildActiveClassName(isActive(), local.activeClassName, local.class));
   return (() => {

package/dist/types/components/Link.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Link.d.ts","sourceRoot":"","sources":["../../../src/components/Link.tsx"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAEpC,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAC5C,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAC5B,GAAG,CAAC,OAAO,CAoFb"}
+{"version":3,"file":"Link.d.ts","sourceRoot":"","sources":["../../../src/components/Link.tsx"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAEpC,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAC5C,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAC5B,GAAG,CAAC,OAAO,CAkHb"}

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

@@ -2,7 +2,7 @@ export { createDirectionTracker } from "./direction-tracker.js";
 export { createRouteAnnouncer } from "./route-announcer.js";
 export { createScrollRestoration } from "./scroll-restore.js";
 export { createViewTransitions } from "./view-transitions.js";
-export { shouldNavigate, buildHref, buildActiveClassName, shallowEqual, applyLinkA11y, } from "./link-utils.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 { DirectionTracker } from "./direction-tracker.js";

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,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,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"}

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

@@ -1,6 +1,22 @@
-import type { Router, Params } from "@real-router/core";
+import type { NavigationOptions, Params, Router, State } from "@real-router/core";
 export declare function shouldNavigate(evt: MouseEvent): boolean;
-export declare function buildHref(router: Router, routeName: string, routeParams: Params): string | undefined;
+/**
+ * Builds an href for a `<Link>` element.
+ *
+ * - Prefers the URL plugin's `buildUrl` (browser-plugin, navigation-plugin,
+ *   hash-plugin) when present.
+ * - Falls back to `router.buildPath` for runtimes without a URL plugin
+ *   (memory-plugin, console UIs, NativeScript). In that fallback the hash
+ *   is appended manually so the rendered href is still correct.
+ * - The optional 4th argument is an options object so the contract stays
+ *   extensible. The `hash` option is a decoded fragment without leading "#";
+ *   `<Link hash="#section">` is accepted defensively (leading "#" stripped).
+ *   Frozen API: previous 3-arg call sites continue to work unchanged.
+ */
+export declare function buildHref(router: Router, routeName: string, routeParams: Params, options?: {
+    hash?: string;
+}): string | undefined;
+export declare function navigateWithHash(router: Router, routeName: string, routeParams: Params, hash: string | undefined, extraOptions?: NavigationOptions): Promise<State>;
 export declare function buildActiveClassName(isActive: boolean, activeClassName: string | undefined, baseClassName: string | undefined): string | undefined;
 export declare function shallowEqual(prev: object | undefined, next: object | undefined): boolean;
 export declare function applyLinkA11y(element: HTMLElement | null | undefined): void;

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

@@ -1 +1 @@
-{"version":3,"file":"link-utils.d.ts","sourceRoot":"","sources":["../../../src/dom-utils/link-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAExD,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAQvD;AAID,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,SAAS,CAoBpB;AAMD,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,OAAO,EACjB,eAAe,EAAE,MAAM,GAAG,SAAS,EACnC,aAAa,EAAE,MAAM,GAAG,SAAS,GAChC,MAAM,GAAG,SAAS,CAyBpB;AAED,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB,OAAO,CAwBT;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAgB3E"}
+{"version":3,"file":"link-utils.d.ts","sourceRoot":"","sources":["../../../src/dom-utils/link-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,MAAM,EACN,MAAM,EACN,KAAK,EACN,MAAM,mBAAmB,CAAC;AAE3B,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAQvD;AAmBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1B,MAAM,GAAG,SAAS,CAiCpB;AA4BD,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,YAAY,CAAC,EAAE,iBAAiB,GAC/B,OAAO,CAAC,KAAK,CAAC,CAyBhB;AAMD,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,OAAO,EACjB,eAAe,EAAE,MAAM,GAAG,SAAS,EACnC,aAAa,EAAE,MAAM,GAAG,SAAS,GAChC,MAAM,GAAG,SAAS,CAyBpB;AAED,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB,OAAO,CAwBT;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAgB3E"}

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

@@ -1,9 +1,30 @@
 import type { Router } from "@real-router/core";
-export type ScrollRestorationMode = "restore" | "top" | "manual";
+export type ScrollRestorationMode = "restore" | "top" | "native";
 export interface ScrollRestorationOptions {
     mode?: ScrollRestorationMode | undefined;
     anchorScrolling?: boolean | undefined;
     scrollContainer?: (() => HTMLElement | null) | undefined;
+    /**
+     * Scroll behavior passed to `scrollTo({ behavior })` and
+     * `scrollIntoView({ behavior })`.
+     *
+     * - `"auto"` (default) — browser-defined, usually instant.
+     * - `"instant"` — explicit instant jump (no animation).
+     * - `"smooth"` — animated transition. Note: smooth restore on back/traverse
+     *   can feel disorienting if the user expects to land at the saved position
+     *   immediately. Recommended for `mode: "top"` or anchor scroll only.
+     *
+     * See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/ScrollToOptions/behavior).
+     */
+    behavior?: ScrollBehavior | undefined;
+    /**
+     * sessionStorage key used to persist saved scroll positions. Default:
+     * `"real-router:scroll"`. Override only when multiple independent
+     * `RouterProvider` instances share the same document and you need to
+     * isolate their scroll stores (e.g. micro-frontends, embedded widgets,
+     * or testing). For a single app with one provider the default is fine.
+     */
+    storageKey?: string | undefined;
 }
 export declare function createScrollRestoration(router: Router, options?: ScrollRestorationOptions): {
     destroy: () => void;

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,EAAS,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;CAC1D;AAOD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,wBAAwB,GACjC;IAAE,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CA+IzB"}
+{"version":3,"file":"scroll-restore.d.ts","sourceRoot":"","sources":["../../../src/dom-utils/scroll-restore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAS,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,CAkMzB"}

package/dist/types/types.d.ts

@@ -11,6 +11,13 @@ export interface LinkProps<P extends Params = Params> extends Omit<JSX.HTMLAttri
     activeClassName?: string;
     activeStrict?: boolean;
     ignoreQueryParams?: boolean;
+    /**
+     * URL fragment (decoded form, no leading "#") (#532).
+     * - omitted/`undefined` → preserve current fragment on same-route navigation
+     * - `""` → clear fragment
+     * - non-empty → set fragment
+     */
+    hash?: string;
     target?: string;
     onClick?: (evt: MouseEvent) => void;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAEpC,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACnD,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAC5B,aAAa,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;CACnC;AAED,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,IAAI,CAChE,GAAG,CAAC,cAAc,CAAC,iBAAiB,CAAC,EACrC,SAAS,CACV;IACC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,CAAC,CAAC;IAChB,YAAY,CAAC,EAAE,iBAAiB,CAAC;IACjC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,IAAI,CAAC;CACrC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAEpC,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACnD,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAC5B,aAAa,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;CACnC;AAED,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,IAAI,CAChE,GAAG,CAAC,cAAc,CAAC,iBAAiB,CAAC,EACrC,SAAS,CACV;IACC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,CAAC,CAAC;IAChB,YAAY,CAAC,EAAE,iBAAiB,CAAC;IACjC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,IAAI,CAAC;CACrC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/solid",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "type": "commonjs",
   "description": "Solid.js integration for Real-Router",
   "main": "./dist/cjs/index.js",
@@ -53,7 +53,7 @@
   "dependencies": {
     "@real-router/core": "^0.51.0",
     "@real-router/route-utils": "^0.2.2",
-    "@real-router/sources": "^0.7.3"
+    "@real-router/sources": "^0.8.0"
   },
   "devDependencies": {
     "@babel/core": "7.29.0",
@@ -71,7 +71,7 @@
     "solid-js": "1.9.12",
     "vite-plugin-solid": "2.11.11",
     "vitest": "4.1.0",
-    "@real-router/browser-plugin": "^0.16.1"
+    "@real-router/browser-plugin": "^0.17.0"
   },
   "peerDependencies": {
     "solid-js": ">=1.7.0"

package/src/components/Link.tsx

@@ -4,7 +4,12 @@ import { createMemo, mergeProps, splitProps, useContext } from "solid-js";
 import { EMPTY_PARAMS, EMPTY_OPTIONS } from "../constants";
 import { RouterContext } from "../context";
 import { createSignalFromSource } from "../createSignalFromSource";
-import { shouldNavigate, buildHref, buildActiveClassName } from "../dom-utils";
+import {
+  shouldNavigate,
+  buildHref,
+  buildActiveClassName,
+  navigateWithHash,
+} from "../dom-utils";
 
 import type { LinkProps } from "../types";
 import type { Params } from "@real-router/core";
@@ -31,6 +36,7 @@ export function Link<P extends Params = Params>(
     "activeClassName",
     "activeStrict",
     "ignoreQueryParams",
+    "hash",
     "onClick",
     "target",
     "class",
@@ -45,22 +51,47 @@ export function Link<P extends Params = Params>(
 
   const router = ctx.router;
 
+  // Hash-aware active state (#532). `routeSelector` (the O(1) shared selector)
+  // doesn't know about hash — when `hash` prop is set, fall back to the slow
+  // path so the source's hash comparison kicks in. Tab-style UI is opt-in via
+  // the prop, so the fast path stays open for the typical Link case.
   const useFastPath =
+    local.hash === undefined &&
     !local.activeStrict &&
     local.ignoreQueryParams &&
     local.routeParams === EMPTY_PARAMS;
 
+  const buildActiveOptions = () => {
+    const base = {
+      strict: local.activeStrict,
+      ignoreQueryParams: local.ignoreQueryParams,
+    };
+
+    if (local.hash === undefined) {
+      return base;
+    }
+
+    return { ...base, hash: local.hash };
+  };
+
   const isActive = useFastPath
     ? () => ctx.routeSelector(local.routeName)
     : createSignalFromSource(
-        createActiveRouteSource(router, local.routeName, local.routeParams, {
-          strict: local.activeStrict,
-          ignoreQueryParams: local.ignoreQueryParams,
-        }),
+        createActiveRouteSource(
+          router,
+          local.routeName,
+          local.routeParams,
+          buildActiveOptions(),
+        ),
       );
 
   const href = createMemo(() =>
-    buildHref(router, local.routeName, local.routeParams),
+    buildHref(
+      router,
+      local.routeName,
+      local.routeParams,
+      local.hash === undefined ? undefined : { hash: local.hash },
+    ),
   );
 
   const handleClick = (evt: MouseEvent) => {
@@ -77,9 +108,13 @@ export function Link<P extends Params = Params>(
     }
 
     evt.preventDefault();
-    router
-      .navigate(local.routeName, local.routeParams, local.routeOptions)
-      .catch(() => {});
+    navigateWithHash(
+      router,
+      local.routeName,
+      local.routeParams,
+      local.hash,
+      local.routeOptions,
+    ).catch(() => {});
   };
 
   const finalClassName = createMemo(() =>

package/src/types.ts

@@ -16,6 +16,13 @@ export interface LinkProps<P extends Params = Params> extends Omit<
   activeClassName?: string;
   activeStrict?: boolean;
   ignoreQueryParams?: boolean;
+  /**
+   * URL fragment (decoded form, no leading "#") (#532).
+   * - omitted/`undefined` → preserve current fragment on same-route navigation
+   * - `""` → clear fragment
+   * - non-empty → set fragment
+   */
+  hash?: string;
   target?: string;
   onClick?: (evt: MouseEvent) => void;
 }