@weftui/router 0.26.2 → 0.26.3

package/README.md

@@ -28,6 +28,8 @@ npm install @weftui/core @weftui/dom @weftui/router effect
 | `RouterLive` (client)            | History-backed `Router` layer; also provides the `AppRpcClientTag` seam.                |
 | `RouterServer` (server)          | `RouterServer.render` / `RouterServer.toWebHandler` for SSR dispatch.                   |
 
+Client-side navigation to a different path resets the window scroll to the top at commit; query-only navigations and browser back/forward preserve it (the latter via the browser's native `history.scrollRestoration`).
+
 ## Example
 
 ```typescript

package/dist/client/index.js

@@ -86,6 +86,10 @@ function RouterLive(def, options = {}) {
 		let committedScope;
 		let router;
 		const collectPreloads = (m) => m._tag !== "Matched" ? [] : [m.leaf.component, ...m.leaf.layoutChain.map((l) => l.component)].map(getPreload).filter((p) => p !== void 0);
+		const pathOf = (url) => {
+			const qIndex = url.indexOf("?");
+			return qIndex === -1 ? url : url.slice(0, qIndex);
+		};
 		const commitUrl = (normalized, replace) => Effect.sync(() => {
 			if (replace) window.history.replaceState(null, "", normalized);
 			else window.history.pushState(null, "", normalized);
@@ -137,8 +141,10 @@ function RouterLive(def, options = {}) {
 				url: normalized,
 				exit
 			});
+			const previousUrl = yield* SubscriptionRef.get(urlRef);
 			if (pushUrl) yield* commitUrl(normalized, replace);
 			yield* SubscriptionRef.set(urlRef, normalized);
+			if (pushUrl && pathOf(previousUrl) !== pathOf(normalized)) yield* Effect.sync(() => window.scrollTo(0, 0));
 			if (emitted) yield* SubscriptionRef.set(navRef, { _tag: "Idle" });
 		});
 		const navigate = (to, options) => commitTo(normalizeTo(to), true, options?.replace === true);

package/docs/how-to/add-routing.md

@@ -231,6 +231,16 @@ yield * patchQuery({ sort: "old" }); // merges into the current query
 - **`navigate(ref, args)`** builds the URL via [`href`](#type-safe-links-with-href) (so it round-trips with the matcher) and pushes — or, with `{ replace: true }`, replaces — the History entry. `args` follows the same requiredness rules as `href`.
 - **`setQuery` / `patchQuery`** keep the path, so the active leaf is never remounted — pair them with `Router.queryStream` for in-place reactive updates. They are a no-op when no route is matched.
 
+### Scroll position on navigation
+
+A client navigation whose **path** changes resets the window scroll to the top at commit — matching what a full page load would do, which a raw History `pushState`/`replaceState` otherwise doesn't. This applies uniformly to `Router.navigate`, clicking a link the [interceptor](#link-interception) handles, and the `push` / `replace` helpers.
+
+- **Query-only navigations preserve scroll.** `setQuery` / `patchQuery` (and any navigation that keeps the same path) don't reset — the leaf stays mounted, so there's nothing to scroll away from.
+- **Back/forward is untouched.** The router never resets scroll on `popstate`; the browser's native `history.scrollRestoration: "auto"` restores the offset the entry had when the user left it.
+- **Hash navigation (`#section`) is unaffected** — it's browser-native, and the link interceptor already lets same-document/hash-only clicks fall through.
+
+There's no opt-out; the behavior is hardwired.
+
 ## Server setup
 
 On the server, `RouterServer` matches a request URL, builds a fixed-match `Router`, renders `RouterApp` to hydratable HTML inside a **document shell**, and reports a status (404 when no route matches or a page raises `RouterNotFound`).

package/docs/reference/router.md

@@ -258,6 +258,10 @@ yield * push("/users/1/posts?sort=new");
 yield * patchQuery({ sort: "old" }); // keeps the current path + other query fields
 ```
 
+### Scroll reset
+
+Every client-committed navigation whose path differs from the previously committed path — `navigate`, `push`, `replace`, and the link interceptor — resets `window.scrollTo(0, 0)` synchronously at commit. Query-only navigations (`setQuery` / `patchQuery`, or any push/replace to the same path) preserve scroll. `popstate` (`back` / `forward`) never resets; the browser's own `history.scrollRestoration: "auto"` restores the prior offset for those entries. Server rendering is unaffected. Not configurable — there is no `NavigateOptions` field to opt out.
+
 ### `installLinkInterceptor`
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weftui/router",
-  "version": "0.26.2",
+  "version": "0.26.3",
   "description": "Universal nested router for Weft — one route tree, server and client, with type-safe params and href",
   "keywords": [
     "effect",
@@ -44,10 +44,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@effect/platform": "^0.96.1",
+    "@effect/platform": "^0.96.2",
     "@effect/rpc": "^0.75.1",
-    "@weftui/dom": "0.26.2",
-    "@weftui/core": "0.26.2"
+    "@weftui/core": "0.26.3",
+    "@weftui/dom": "0.26.3"
   },
   "devDependencies": {
     "@types/jsdom": "^28.0.3",