@valentinkolb/ssr 0.10.1 → 0.11.1

package/README.md

@@ -21,8 +21,8 @@ Current source size in this repo (`packages/ssr-core/src`):
 | Component | Lines | Raw | Gzipped |
 | --- | ---: | ---: | ---: |
 | Core (`index`, `transform`, `build`, island ID + resolver) | ~689 | 23.8 KB | 7.2 KB |
-| Dev client (overlay + reload, dev only) | ~211 | 6.1 KB | 2.0 KB |
-| Adapters (`bun`, `hono`, `elysia`, shared utils) | ~355 | 10.4 KB | 3.3 KB |
+| Dev client (overlay + reload, dev only) | ~421 | 11.9 KB | 3.5 KB |
+| Adapters (`bun`, `hono`, `elysia`, shared utils) | ~465 | 14.4 KB | 4.8 KB |
 
 Important: these sizes describe framework source code that runs at build time and on the server.
 The browser receives only:
@@ -184,16 +184,24 @@ NODE_ENV=development bun --watch --preload=./scripts/preload.ts src/server.ts
 update URL history after they have already updated client state.
 
 ```tsx
-import { createSignal } from "solid-js";
-import { Link, type LinkNavigateEvent } from "@valentinkolb/ssr/nav";
+import { createSignal, onCleanup, onMount } from "solid-js";
+import { Link, listenPopState, type LinkNavigateEvent } from "@valentinkolb/ssr/nav";
 
 export default function Tabs() {
   const [tab, setTab] = createSignal("alpha");
 
+  onMount(() => {
+    onCleanup(
+      listenPopState(({ url }) => {
+        setTab(url.searchParams.get("tab") ?? "alpha");
+      }),
+    );
+  });
+
   const openTab = (nav: LinkNavigateEvent) => {
     const next = nav.url.searchParams.get("tab") ?? "alpha";
     setTab(next);
-    nav.replaceWith(`/demo?tab=${next}`, { scroll: "preserve" });
+    nav.push(`/demo?tab=${next}`, { scroll: "preserve", state: { tab: next } });
   };
 
   return (
@@ -210,12 +218,28 @@ browser for same-origin, left-click navigation without modifier keys. Without
 history. With `onNavigate`, the island owns data loading and state updates, then
 calls `nav.push()`, `nav.replaceWith()`, or `nav.fallback()`.
 
+Use `listenPopState()` whenever `nav.push()` represents client state. Browser
+Back/Forward changes history but cannot infer how an island maps the URL back to
+signals or stores. The helper reports the current `URL`, native `PopStateEvent`,
+and history state without adding route matching or data loading.
+
+Navigation behavior:
+
+- reactive anchor props remain reactive after `Link` renders
+- same-document hash links retain native target scrolling unless `onNavigate`
+  or `scroll` explicitly takes ownership
+- relative URLs follow `document.baseURI`
+- cross-origin `navigate()` calls use full document navigation
+- replace navigation preserves existing `history.state` unless `state` is set
+- rejected async `onNavigate` callbacks log the error and fall back to a full
+  document navigation
+
 Available exports:
 
 - `Link`
 - `navigate()`, `navigateTo()`, `documentNavigate()`, `refreshCurrentPath()`
-- `captureScroll()`, `restoreScroll()`, `startViewTransition()`
-- `LinkNavigateEvent`, `LinkProps`, `EnhancedNavigateOptions`, `NavigationScrollMode`, `ScrollSnapshot`
+- `captureScroll()`, `restoreScroll()`, `listenPopState()`, `startViewTransition()`
+- `LinkNavigateEvent`, `LinkProps`, `EnhancedNavigateOptions`, `NavigationScrollMode`, `PopStateNavigationEvent`, `ScrollSnapshot`
 
 Use `data-scroll-preserve="stable-key"` on scroll containers that should keep
 their scroll position across enhanced navigation.
@@ -334,6 +358,12 @@ It can:
 - highlight island/client boundaries
 - show source filenames for wrapped components
 
+In browsers with Web Locks support, auto-reload elects one visible tab per
+origin and SSR path to hold the SSE connection. Hidden tabs suspend reload work,
+leadership transfers automatically, and cached pages resume safely after a
+back-forward cache restore. Browsers without Web Locks retain visibility-scoped
+per-tab connections as a compatibility fallback.
+
 ## Limitations
 
 - islands must use default export

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentinkolb/ssr",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "description": "Minimal SSR framework for SolidJS and Bun",
   "type": "module",
   "main": "src/index.ts",
@@ -13,7 +13,7 @@
     "./nav": "./src/nav.ts"
   },
   "scripts": {
-    "test": "bun test"
+    "test": "bunx tsc -p test/tsconfig.json && bun test test/unit && bun test --conditions=browser --preload ./test/browser/setup.ts test/browser"
   },
   "peerDependencies": {
     "solid-js": "^1.9.0",
@@ -36,6 +36,7 @@
     "seroval": "^1.5.5"
   },
   "devDependencies": {
+    "@happy-dom/global-registrator": "^20.10.6",
     "@types/bun": "^1.3.14",
     "elysia": "^1.4.29",
     "file-type": "^21.3.1",

package/src/adapter/bun.ts

@@ -5,6 +5,7 @@
 import type { SsrConfig } from "../index";
 import {
   createAssetResponse,
+  createPingResponse,
   getSsrDir,
   createReloadResponse,
 } from "./utils";
@@ -32,8 +33,8 @@ export const routes = (config: SsrConfig): Routes => {
 
   const devRoutes: Routes = dev
     ? {
-        [`${ssrPath}/_reload`]: () => createReloadResponse(),
-        [`${ssrPath}/_ping`]: () => new Response("ok"),
+        [`${ssrPath}/_reload`]: (req) => createReloadResponse(req.signal),
+        [`${ssrPath}/_ping`]: () => createPingResponse(),
       }
     : {};
 

package/src/adapter/client.js

@@ -14,11 +14,31 @@ if (!window.__ssr_reload) {
       position: "bl",
     };
 
-    const load = () => ({
-      ...defaults,
-      ...JSON.parse(localStorage.getItem(STORAGE_KEY) || "{}"),
-    });
-    const save = (s) => localStorage.setItem(STORAGE_KEY, JSON.stringify(s));
+    const readStorage = (key) => {
+      try {
+        return localStorage.getItem(key);
+      } catch {
+        return null;
+      }
+    };
+    const writeStorage = (key, value) => {
+      try {
+        localStorage.setItem(key, value);
+      } catch {
+        // Dev tools still work when storage is unavailable.
+      }
+    };
+    const load = () => {
+      try {
+        return {
+          ...defaults,
+          ...JSON.parse(readStorage(STORAGE_KEY) || "{}"),
+        };
+      } catch {
+        return { ...defaults };
+      }
+    };
+    const save = (s) => writeStorage(STORAGE_KEY, JSON.stringify(s));
     let settings = load();
 
     // Highlight Styles
@@ -152,10 +172,23 @@ if (!window.__ssr_reload) {
     bind("_ssr_pos", "position", applyPosition);
 
     // Live Reload (SSE)
-    let es, reconnectInterval, animationInterval;
+    const reloadId = globalThis.__SSR_CONFIG?.reloadId;
+    const reloadIdKey = `${STORAGE_KEY}:reload-id`;
+    const reloadLockName = `${STORAGE_KEY}:reload-lock`;
+    let es, retryTimer, retryController, animationInterval;
+    let lockController, releaseLock;
+    let retryAttempt = 0;
+    let retryGeneration = 0;
+    let ownsLock = false;
+    let pageActive = true;
+    let reloadRequested = false;
     const spinFrames = ["[ / ]", "[ – ]", "[ \\ ]", "[ | ]"];
     let spinIndex = 0;
 
+    // A fresh document already represents this server generation. Publishing
+    // it first wakes stale tabs without making the fresh document reload.
+    if (reloadId) writeStorage(reloadIdKey, reloadId);
+
     const stopAnimation = () => {
       clearInterval(animationInterval);
       animationInterval = null;
@@ -169,45 +202,220 @@ if (!window.__ssr_reload) {
       }, 150);
     };
 
-    const stop = () => {
-      es?.close();
+    const shouldParticipate = () =>
+      pageActive &&
+      !reloadRequested &&
+      settings.autoReload &&
+      document.visibilityState === "visible";
+    const canConnect = () => shouldParticipate() && ownsLock;
+
+    const closeSource = () => {
+      const source = es;
       es = null;
-      clearInterval(reconnectInterval);
-      reconnectInterval = null;
+      source?.close();
+    };
+
+    const cancelRetry = () => {
+      retryGeneration += 1;
+      clearTimeout(retryTimer);
+      retryTimer = null;
+      const controller = retryController;
+      retryController = null;
+      controller?.abort();
+    };
+
+    const stopConnection = () => {
+      closeSource();
+      cancelRetry();
+      retryAttempt = 0;
       stopAnimation();
+      badge.innerText = "[ssr]";
+    };
+
+    const releaseLeadership = () => {
+      const pendingLock = lockController;
+      lockController = null;
+      pendingLock?.abort();
+
+      const release = releaseLock;
+      releaseLock = null;
+      ownsLock = false;
+      release?.();
+      stopConnection();
+    };
+
+    const requestReload = () => {
+      if (reloadRequested) return;
+      reloadRequested = true;
+      releaseLeadership();
+      location.reload();
+    };
+
+    const acceptReloadId = (nextReloadId) => {
+      if (!nextReloadId) return;
+      writeStorage(reloadIdKey, nextReloadId);
+      if (reloadId && nextReloadId !== reloadId) requestReload();
+    };
+
+    const retryDelay = () =>
+      Math.min(2_000, 300 * 2 ** Math.min(retryAttempt, 3));
+
+    const scheduleRetry = () => {
+      if (!canConnect() || retryTimer || retryController) return;
+
+      const generation = retryGeneration;
+      retryTimer = setTimeout(async () => {
+        retryTimer = null;
+        if (generation !== retryGeneration || !canConnect()) return;
+
+        const controller = new AbortController();
+        retryController = controller;
+        try {
+          const response = await fetch(`${ssrPath}/_ping`, {
+            cache: "no-store",
+            signal: controller.signal,
+          });
+          if (response.ok && canConnect()) {
+            acceptReloadId(response.headers.get("X-SSR-Reload-ID"));
+            if (!reloadRequested) requestReload();
+            return;
+          }
+        } catch {
+          // A stopped or unavailable dev server is expected during reload.
+        } finally {
+          if (retryController === controller) retryController = null;
+        }
+
+        if (generation !== retryGeneration || !canConnect()) return;
+        retryAttempt += 1;
+        scheduleRetry();
+      }, retryDelay());
+    };
+
+    const startRetry = () => {
+      if (!canConnect()) return;
+      startAnimation();
+      scheduleRetry();
     };
 
     const start = () => {
-      if (es) return;
+      if (!canConnect() || es || retryTimer || retryController) return;
+
+      let source;
       try {
-        es = new EventSource(`${ssrPath}/_reload`);
+        source = new EventSource(`${ssrPath}/_reload`);
+        es = source;
         stopAnimation();
         badge.innerText = "[ssr]";
       } catch {
+        startRetry();
         return;
       }
 
-      es.onerror = (e) => {
-        e.preventDefault();
-        stop();
-        startAnimation();
-        if (!settings.autoReload) return;
-        reconnectInterval = setInterval(() => {
-          fetch(`${ssrPath}/_ping`)
-            .then((r) => r.ok && location.reload())
-            .catch(() => {});
-        }, 300);
+      source.onopen = () => {
+        if (es !== source) return;
+        retryAttempt = 0;
+        stopAnimation();
+        badge.innerText = "[ssr]";
       };
+
+      source.onmessage = (event) => {
+        if (es !== source) return;
+        acceptReloadId(event.data);
+      };
+
+      source.onerror = (event) => {
+        if (es !== source) return;
+        event.preventDefault();
+        closeSource();
+        retryAttempt = 0;
+        startRetry();
+      };
+    };
+
+    const requestLeadership = () => {
+      if (!shouldParticipate()) return;
+      if (ownsLock) {
+        start();
+        return;
+      }
+      if (lockController) return;
+
+      if (!navigator.locks?.request) {
+        ownsLock = true;
+        start();
+        return;
+      }
+
+      const controller = new AbortController();
+      lockController = controller;
+      void navigator.locks
+        .request(
+          reloadLockName,
+          { mode: "exclusive", signal: controller.signal },
+          async () => {
+            if (lockController === controller) lockController = null;
+            if (controller.signal.aborted || !shouldParticipate()) return;
+
+            ownsLock = true;
+            start();
+            await new Promise((resolve) => {
+              releaseLock = resolve;
+            });
+            releaseLock = null;
+            ownsLock = false;
+            stopConnection();
+          },
+        )
+        .catch((error) => {
+          if (lockController === controller) lockController = null;
+          if (error?.name === "AbortError" || !shouldParticipate()) return;
+
+          // If Web Locks is unavailable at runtime, retain per-tab behavior.
+          ownsLock = true;
+          start();
+        });
     };
 
-    if (settings.autoReload) start();
+    const syncConnection = () => {
+      const knownReloadId = readStorage(reloadIdKey);
+      if (
+        shouldParticipate() &&
+        reloadId &&
+        knownReloadId &&
+        knownReloadId !== reloadId
+      ) {
+        requestReload();
+        return;
+      }
+
+      if (shouldParticipate()) requestLeadership();
+      else releaseLeadership();
+    };
+
+    syncConnection();
 
     panel.querySelector("#_ssr_reload").onchange = (e) => {
       settings.autoReload = e.target.checked;
       save(settings);
-      settings.autoReload ? start() : stop();
+      syncConnection();
     };
 
-    window.addEventListener("pagehide", stop);
+    document.addEventListener("visibilitychange", syncConnection);
+    window.addEventListener("storage", (event) => {
+      if (event.key !== reloadIdKey || !event.newValue) return;
+      if (reloadId && event.newValue !== reloadId && shouldParticipate()) {
+        requestReload();
+      }
+    });
+    window.addEventListener("pagehide", () => {
+      pageActive = false;
+      releaseLeadership();
+    });
+    window.addEventListener("pageshow", () => {
+      pageActive = true;
+      reloadRequested = false;
+      syncConnection();
+    });
   })();
 }

package/src/adapter/elysia.ts

@@ -6,6 +6,7 @@ import { Elysia } from "elysia";
 import type { SsrConfig } from "../index";
 import {
   createAssetResponse,
+  createPingResponse,
   getSsrDir,
   createReloadResponse,
   notFound,
@@ -28,8 +29,10 @@ export const routes = (config: SsrConfig) => {
   const ssrDir = getSsrDir(config);
 
   return new Elysia({ name: "ssr" })
-    .get(`${ssrPath}/_reload`, () => (dev ? createReloadResponse() : notFound()))
-    .get(`${ssrPath}/_ping`, () => (dev ? new Response("ok") : notFound()))
+    .get(`${ssrPath}/_reload`, ({ request }) =>
+      dev ? createReloadResponse(request.signal) : notFound(),
+    )
+    .get(`${ssrPath}/_ping`, () => (dev ? createPingResponse() : notFound()))
     .get(`${ssrPath}/*`, ({ request, params }) =>
       createAssetResponse(request, ssrDir, params["*"], dev),
     );

package/src/adapter/hono.ts

@@ -6,7 +6,7 @@ import { Hono } from "hono";
 import { createFactory } from "hono/factory";
 import type { Context, Env, Handler, MiddlewareHandler, TypedResponse } from "hono";
 import type { SsrConfig, HtmlFn, RenderFn } from "../index";
-import { createAssetResponse, getSsrDir, createReloadResponse } from "./utils";
+import { createAssetResponse, createPingResponse, getSsrDir, createReloadResponse } from "./utils";
 
 // ============================================================================
 // Types
@@ -172,8 +172,8 @@ export const routes = (config: SsrConfig) => {
 
   // Dev mode endpoints
   if (dev) {
-    app.get("/_reload", () => createReloadResponse());
-    app.get("/_ping", (c) => c.text("ok"));
+    app.get("/_reload", (c) => createReloadResponse(c.req.raw.signal));
+    app.get("/_ping", () => createPingResponse());
   }
 
   const serveAsset = (c: Context) => createAssetResponse(c.req.raw, ssrDir, c.req.param("filename"), dev);

package/src/adapter/utils.ts

@@ -116,28 +116,63 @@ export const SSE_HEADERS = {
   Connection: "keep-alive",
 } as const;
 
+const reloadId = crypto.randomUUID();
+const reloadConnected = new TextEncoder().encode(`: connected\ndata: ${reloadId}\n\n`);
+const reloadPing = new TextEncoder().encode(": ping\n\n");
+
+export const getReloadId = (): string => reloadId;
+
+export const createPingResponse = (): Response =>
+  new Response("ok", { headers: { "X-SSR-Reload-ID": reloadId } });
+
 /**
  * Creates a Server-Sent Events stream for live reload
  */
-export const createReloadStream = (): ReadableStream =>
-  new ReadableStream({
+export const createReloadStream = (signal?: AbortSignal): ReadableStream<Uint8Array> => {
+  let interval: ReturnType<typeof setInterval> | undefined;
+  let streamController: ReadableStreamDefaultController<Uint8Array> | undefined;
+  const handleAbort = () => {
+    stopHeartbeat();
+    try {
+      streamController?.close();
+    } catch {
+      // The consumer may already have canceled the stream.
+    }
+  };
+  const stopHeartbeat = () => {
+    if (interval === undefined) return;
+    clearInterval(interval);
+    interval = undefined;
+    signal?.removeEventListener("abort", handleAbort);
+  };
+
+  return new ReadableStream<Uint8Array>({
     start(controller) {
-      controller.enqueue(new TextEncoder().encode(": connected\n\n"));
-      const interval = setInterval(() => {
+      streamController = controller;
+      if (signal?.aborted) {
+        controller.close();
+        return;
+      }
+
+      signal?.addEventListener("abort", handleAbort, { once: true });
+      controller.enqueue(reloadConnected);
+      interval = setInterval(() => {
         try {
-          controller.enqueue(new TextEncoder().encode(": ping\n\n"));
+          controller.enqueue(reloadPing);
         } catch {
-          clearInterval(interval);
+          stopHeartbeat();
         }
       }, 5000);
     },
+    cancel: stopHeartbeat,
   });
+};
 
 /**
  * Creates a Response for the SSE reload endpoint
  */
-export const createReloadResponse = (): Response =>
-  new Response(createReloadStream(), { headers: SSE_HEADERS });
+export const createReloadResponse = (signal?: AbortSignal): Response =>
+  new Response(createReloadStream(signal), { headers: SSE_HEADERS });
 
 /**
  * 404 Response

package/src/index.ts

@@ -12,7 +12,7 @@ import { transform } from "./transform";
 import { buildIslands, type DevSourcemap } from "./build";
 import { join, dirname, resolve } from "path";
 import { resolveIslandImport } from "./island-resolve";
-import { normalizeBasePath, toSsrPath } from "./adapter/utils";
+import { getReloadId, normalizeBasePath, toSsrPath } from "./adapter/utils";
 // @ts-ignore - Bun text import
 import devClientCode from "./adapter/client.js" with { type: "text" };
 
@@ -160,7 +160,7 @@ export const createConfig = <T extends object = object>(options: SsrOptions<T> =
 
   // Hydration script - dynamically loads island/client bundles based on DOM
   const hydrationScript = `<script type="module">const p=${JSON.stringify(ssrPath)};const v=${JSON.stringify(buildVersion)};document.querySelectorAll('solid-island,solid-client').forEach(e=>import(p+'/'+e.dataset.id+'.js'+(v?'?v='+v:'')));</script>`;
-  const devConfigScript = `<script>globalThis.__SSR_CONFIG=${JSON.stringify({ ssrPath })}</script>`;
+  const devConfigScript = `<script>globalThis.__SSR_CONFIG=${JSON.stringify({ ssrPath, reloadId: getReloadId() })}</script>`;
 
   // HTML renderer
   const html: HtmlFn<T> = async (render, opts = {} as T) => {

package/src/nav.ts

@@ -4,7 +4,7 @@
  * This is not a router. Links remain real anchors and apps decide whether an
  * enhanced click can update client state before committing browser history.
  */
-import type { JSX } from "solid-js";
+import { mergeProps, splitProps, type JSX } from "solid-js";
 import { createDynamic } from "solid-js/web";
 
 type AnchorProps = JSX.AnchorHTMLAttributes<HTMLAnchorElement>;
@@ -24,9 +24,16 @@ export type EnhancedNavigateOptions = {
   replace?: boolean;
   scroll?: NavigationScrollMode;
   scrollSnapshot?: ScrollSnapshot;
+  state?: unknown;
   viewTransition?: boolean;
 };
 
+export type PopStateNavigationEvent = {
+  event: PopStateEvent;
+  url: URL;
+  state: unknown;
+};
+
 export type LinkNavigateEvent = {
   event: MouseEvent;
   href: string;
@@ -119,6 +126,24 @@ export const restoreScroll = (snapshot: ScrollSnapshot, options: { window?: bool
   window.scrollTo(snapshot.window.x, snapshot.window.y);
 };
 
+/**
+ * Subscribes to browser Back/Forward navigation.
+ *
+ * The application remains responsible for reconciling its island state with
+ * the URL. This helper intentionally does not perform route matching.
+ */
+export const listenPopState = (handler: (navigation: PopStateNavigationEvent) => void): (() => void) => {
+  const listener = (event: PopStateEvent) => {
+    handler({ event, url: new URL(window.location.href), state: event.state });
+  };
+
+  window.addEventListener("popstate", listener);
+  return () => window.removeEventListener("popstate", listener);
+};
+
+const resolveNavigationUrl = (href: string): URL =>
+  new URL(href, document.baseURI || window.location.href);
+
 /**
  * Updates browser history without a document reload.
  *
@@ -127,14 +152,22 @@ export const restoreScroll = (snapshot: ScrollSnapshot, options: { window?: bool
  * data, or re-render server pages.
  */
 export const navigate = (href: string, options: EnhancedNavigateOptions = {}): void => {
+  const url = resolveNavigationUrl(href);
+  if (url.origin !== window.location.origin) {
+    documentNavigate(url.href, { replace: options.replace });
+    return;
+  }
+
   const scroll = options.scroll ?? "top";
   const snapshot = scroll === "manual" ? null : (options.scrollSnapshot ?? captureScroll());
-  const url = new URL(href, window.location.href);
   const target = `${url.pathname}${url.search}${url.hash}`;
 
   const commit = () => {
-    if (options.replace) window.history.replaceState(null, "", target);
-    else window.history.pushState(null, "", target);
+    const hasExplicitState = Object.prototype.hasOwnProperty.call(options, "state");
+    const state = hasExplicitState ? options.state : options.replace ? window.history.state : null;
+
+    if (options.replace) window.history.replaceState(state, "", target);
+    else window.history.pushState(state, "", target);
 
     if (!snapshot) return;
     restoreRegionScroll(snapshot);
@@ -163,67 +196,113 @@ const shouldEnhanceClick = (event: MouseEvent, anchor: HTMLAnchorElement): boole
   if (anchor.target && anchor.target !== "_self") return false;
   if (anchor.hasAttribute("download")) return false;
 
-  const url = new URL(anchor.href, window.location.href);
+  const url = new URL(anchor.href);
   return url.origin === window.location.origin;
 };
 
+const isSameDocumentHash = (url: URL): boolean => {
+  const current = new URL(window.location.href);
+  return url.hash.length > 0 && url.pathname === current.pathname && url.search === current.search;
+};
+
 const callUserClick = (handler: LinkProps["onClick"], event: MouseEvent, anchor: HTMLAnchorElement): void => {
   if (!handler) return;
-  if (typeof handler === "function") {
-    handler(event as MouseEvent & { currentTarget: HTMLAnchorElement; target: Element });
+  const typedEvent = event as MouseEvent & { currentTarget: HTMLAnchorElement; target: Element };
+
+  if (Array.isArray(handler)) {
+    handler[0].call(anchor, handler[1], typedEvent);
     return;
   }
-  (handler as unknown as EventListenerObject).handleEvent(event);
+
+  if (typeof handler === "function") {
+    handler.call(anchor, typedEvent);
+  }
 };
 
 /**
  * SSR-safe anchor with opt-in progressive navigation.
  */
 export function Link(props: LinkProps) {
-  const anchorProps = () => {
-    const { href: _href, replace: _replace, scroll: _scroll, onNavigate: _onNavigate, onClick: _onClick, ...rest } = props;
-    return rest;
-  };
+  const [local, anchorProps] = splitProps(props, ["href", "replace", "scroll", "onNavigate", "onClick"]);
 
   const handleClick: JSX.EventHandler<HTMLAnchorElement, MouseEvent> = (event) => {
-    callUserClick(props.onClick, event, event.currentTarget);
+    callUserClick(local.onClick, event, event.currentTarget);
     if (!shouldEnhanceClick(event, event.currentTarget)) return;
 
-    const href = props.href;
-    const url = new URL(href, window.location.href);
-    const scroll = props.scroll ?? "top";
-    const replace = Boolean(props.replace);
+    const href = local.href;
+    const url = new URL(event.currentTarget.href);
+
+    // Preserve native target scrolling unless the application explicitly owns
+    // this hash navigation through onNavigate or a scroll option.
+    if (!local.onNavigate && local.scroll === undefined && isSameDocumentHash(url)) return;
+
+    const scroll = local.scroll ?? "top";
+    const replace = Boolean(local.replace);
     const scrollSnapshot = captureScroll();
 
     event.preventDefault();
 
-    if (!props.onNavigate) {
-      navigate(href, { replace, scroll, scrollSnapshot });
+    if (!local.onNavigate) {
+      navigate(url.href, { replace, scroll, scrollSnapshot });
       return;
     }
 
-    startViewTransition(() =>
-      props.onNavigate!({
-        event,
-        href,
-        url,
-        replace,
-        scroll,
-        push: (nextHref = href, options = {}) =>
-          navigate(nextHref, { replace: false, scroll, scrollSnapshot, viewTransition: false, ...options }),
-        replaceWith: (nextHref = href, options = {}) =>
-          navigate(nextHref, { replace: true, scroll, scrollSnapshot, viewTransition: false, ...options }),
-        fallback: (nextHref = href) => documentNavigate(nextHref, { replace }),
-        scrollSnapshot,
-        captureScroll,
-        restoreScroll,
-      }),
-    );
+    let navigationOutcome: "none" | "history" | "document" = "none";
+    const runNavigation = async () => {
+      try {
+        await local.onNavigate!({
+          event,
+          href,
+          url,
+          replace,
+          scroll,
+          push: (nextHref = url.href, options = {}) => {
+            navigate(nextHref, {
+              ...options,
+              replace: false,
+              scroll: options.scroll ?? scroll,
+              scrollSnapshot: options.scrollSnapshot ?? scrollSnapshot,
+              viewTransition: false,
+            });
+            navigationOutcome = "history";
+          },
+          replaceWith: (nextHref = url.href, options = {}) => {
+            navigate(nextHref, {
+              ...options,
+              replace: true,
+              scroll: options.scroll ?? scroll,
+              scrollSnapshot: options.scrollSnapshot ?? scrollSnapshot,
+              viewTransition: false,
+            });
+            navigationOutcome = "history";
+          },
+          fallback: (nextHref = url.href) => {
+            documentNavigate(resolveNavigationUrl(nextHref).href, { replace });
+            navigationOutcome = "document";
+          },
+          scrollSnapshot,
+          captureScroll,
+          restoreScroll,
+        });
+      } catch (error) {
+        console.error("[@valentinkolb/ssr/nav] onNavigate failed; falling back to document navigation.", error);
+        if (navigationOutcome === "document") return;
+        const historyCommitted = navigationOutcome === "history";
+        const fallbackHref = historyCommitted ? window.location.href : url.href;
+        documentNavigate(fallbackHref, { replace: historyCommitted || replace });
+      }
+    };
+
+    startViewTransition(runNavigation);
   };
 
-  return createDynamic(() => "a", {
-    ...anchorProps(),
-    href: props.href,
-    onClick: handleClick,
-  });
+  return createDynamic(
+    () => "a",
+    mergeProps(anchorProps, {
+      get href() {
+        return local.href;
+      },
+      onClick: handleClick,
+    }),
+  );
 }

package/src/transform.ts

@@ -122,6 +122,10 @@ const componentWrapperPlugin = (filename: string, rootDir: string, dev: boolean)
             path.skip();
           },
         });
+
+        // Client wrappers remove their original JSX usage. Refresh bindings so
+        // later presets can discard imports that became unused in this pass.
+        programPath.scope.crawl();
       },
     },
   };
@@ -138,19 +142,10 @@ export const transform = async (
   dev: boolean = false,
   rootDir: string = process.cwd(),
 ): Promise<string> => {
-  let code = source;
-
-  if (mode === "ssr") {
-    const result = await transformAsync(code, {
-      filename,
-      parserOpts: { plugins: ["jsx", "typescript"] },
-      plugins: [() => componentWrapperPlugin(filename, rootDir, dev)],
-    });
-    code = result?.code || code;
-  }
-
-  const result = await transformAsync(code, {
+  const result = await transformAsync(source, {
     filename,
+    parserOpts: mode === "ssr" ? { plugins: ["jsx", "typescript"] } : undefined,
+    plugins: mode === "ssr" ? [() => componentWrapperPlugin(filename, rootDir, dev)] : [],
     presets: [
       [tsPreset, {}],
       [solidPreset, { generate: mode, hydratable: false }],