Add a scroll option to Navigation.navigate() and <Link>

[lemonmade]

Adds a scroll option to Navigation.navigate() and <Link>, and makes the URL change — not the history operation — decide the default scroll behavior.

Default behavior change

For push and replace navigations alike:

• Changing the pathname or hash resets the scroll position to the top of the page (or scrolls to the URL's hash target when present). Previously, replace navigations never reset.
• Changing only the search params keeps the current scroll position. Previously, push navigations always reset — which yanked the page to the top for URL-encoded UI state like filters, tabs, or a selected calendar day.

Back/forward still restores each entry's saved offset, and reloads still restore the entry's offset.

This differs deliberately from React Router / Next.js / TanStack Router, which reset on search-only changes too (behind preventScrollReset / scroll: false / resetScroll: false opt-outs). Search-only navigations almost always encode UI state rather than a new location, so staying put is the default that matches intent; the scroll option covers the exceptions in both directions.

Previously, apps reached for replace to get its keep-scroll side effect. Now push/replace is purely a history-semantics choice, and scroll behavior follows the shape of the URL change.

The scroll option

// Force a search-only navigation to reset:
navigation.navigate(url, {scroll: true});

// Keep the position on a path change:
navigation.navigate(url, {replace: true, scroll: false});

<Link to={url} scroll={false}>
  Select day
</Link>

With scroll: false, the kept offset is recorded against the new history entry, so a later back/forward return to it still restores correctly. The option is a no-op when the Navigation was constructed with scrollRestoration: false.

Tests

New packages/preact-router/source/Navigation.test.ts covers: manual-restoration setup, scrollRestoration: false, push/replace top reset on path changes, search-only keep (push and replace), scroll: true forcing a reset, scroll: false keeping the position (push and replace), offset recording under scroll: false, hash-target scrolling (path change and same-path hash change), popstate restore, and sessionStorage persistence.

pnpm vitest run --config configuration/vite.unit.config.ts packages/preact-router/source/Navigation.test.ts — 14/14 pass. tsc --build packages/preact-router — clean.

Note: packages/preact-router/source/components/Link.test.tsx currently fails to transform on main with the pinned toolchain (rolldown can't parse esbuild's lowering of using declarations) — pre-existing and unrelated to this change.

🤖 Generated with Claude Code