@weftui/core 0.26.2 → 0.26.3

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/core",
-  "version": "0.26.2",
+  "version": "0.26.3",
   "description": "Element builders and combinators for Weft — reactive UI, woven from Effect",
   "keywords": [
     "combinators",