@valentinkolb/ssr 0.9.0 → 0.10.1

package/README.md

@@ -42,12 +42,16 @@ What is intentionally not included:
 - no build tool wrapper around Bun
 
 Use the libraries you already prefer. This package only handles SSR and islands hydration.
+The optional `@valentinkolb/ssr/nav` subpath provides progressive anchor
+enhancement for islands, but it still does not add route matching, loaders, or
+SPA routing.
 
 ## Features
 
 - Small SSR core with Bun-native build/plugin flow
 - Adapters for Bun, Hono, and Elysia
 - Type-safe Hono page helper via `createSSRHandler`
+- Optional progressive navigation helpers via `@valentinkolb/ssr/nav`
 - Monorepo support via `rootDir`
 - Public path mounting via `basePath` for microfrontends
 - Stable file-path-based island IDs (collision-safe across workspace packages)
@@ -61,7 +65,7 @@ bun add @valentinkolb/ssr solid-js
 # choose adapter deps you need
 bun add hono
 # or
-bun add elysia @elysiajs/static
+bun add elysia
 ```
 
 ## Required TypeScript settings
@@ -174,6 +178,48 @@ NODE_ENV=development bun --watch --preload=./scripts/preload.ts src/server.ts
 - Hono: `@valentinkolb/ssr/hono`
 - Elysia: `@valentinkolb/ssr/elysia`
 
+## Optional Navigation Helpers
+
+`@valentinkolb/ssr/nav` is an opt-in browser helper for islands that want to
+update URL history after they have already updated client state.
+
+```tsx
+import { createSignal } from "solid-js";
+import { Link, type LinkNavigateEvent } from "@valentinkolb/ssr/nav";
+
+export default function Tabs() {
+  const [tab, setTab] = createSignal("alpha");
+
+  const openTab = (nav: LinkNavigateEvent) => {
+    const next = nav.url.searchParams.get("tab") ?? "alpha";
+    setTab(next);
+    nav.replaceWith(`/demo?tab=${next}`, { scroll: "preserve" });
+  };
+
+  return (
+    <Link href="/demo?tab=beta" scroll="preserve" onNavigate={openTab}>
+      Open beta
+    </Link>
+  );
+}
+```
+
+`Link` renders a real `<a href>` during SSR. Enhanced clicks only run in the
+browser for same-origin, left-click navigation without modifier keys. Without
+`onNavigate`, `Link` calls `navigate()` directly and only updates browser
+history. With `onNavigate`, the island owns data loading and state updates, then
+calls `nav.push()`, `nav.replaceWith()`, or `nav.fallback()`.
+
+Available exports:
+
+- `Link`
+- `navigate()`, `navigateTo()`, `documentNavigate()`, `refreshCurrentPath()`
+- `captureScroll()`, `restoreScroll()`, `startViewTransition()`
+- `LinkNavigateEvent`, `LinkProps`, `EnhancedNavigateOptions`, `NavigationScrollMode`, `ScrollSnapshot`
+
+Use `data-scroll-preserve="stable-key"` on scroll containers that should keep
+their scroll position across enhanced navigation.
+
 ## Rendering API
 
 `html()` and Hono `ssr()` handlers expect a synchronous render function:
@@ -222,6 +268,7 @@ createConfig({
   rootDir?: string;      // default: process.cwd()
   basePath?: string;     // default: "", example: "/docs"
   external?: string[];   // passed to Bun.build for island bundle
+  devSourcemap?: "none" | "linked" | "inline"; // default: "linked"
   template?: ({ body, scripts, ...custom }) => string | Promise<string>;
 })
 ```
@@ -230,7 +277,9 @@ createConfig({
 
 - `rootDir` is important in monorepos where server entrypoint and island files live in different packages.
 - `basePath` moves SSR assets and dev endpoints under that prefix, e.g. `/docs/_ssr`.
+- Development builds emit linked source maps by default. Use `"inline"` only when a tool requires embedded maps, or `"none"` to disable them.
 - In production, hydration imports include a build timestamp query (`?v=...`) for cache busting.
+- All adapters stream island assets from `Bun.file`. Production assets and content-hashed development chunks are immutable; stable development entries and source maps use validators for inexpensive freshness checks.
 
 ## Microfrontend mount example
 
@@ -288,7 +337,7 @@ It can:
 ## Limitations
 
 - islands must use default export
-- props must be serializable (via `seroval`)
+- props must be serializable via `seroval`; do not pass functions, callbacks, event handlers, Solid signals/stores, DOM nodes, or class instances as island/client props
 - nested island/client imports are not supported
 
 ## Local monorepo example

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentinkolb/ssr",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "Minimal SSR framework for SolidJS and Bun",
   "type": "module",
   "main": "src/index.ts",
@@ -9,7 +9,8 @@
     ".": "./src/index.ts",
     "./bun": "./src/adapter/bun.ts",
     "./elysia": "./src/adapter/elysia.ts",
-    "./hono": "./src/adapter/hono.ts"
+    "./hono": "./src/adapter/hono.ts",
+    "./nav": "./src/nav.ts"
   },
   "scripts": {
     "test": "bun test"
@@ -17,34 +18,30 @@
   "peerDependencies": {
     "solid-js": "^1.9.0",
     "elysia": "^1.0.0",
-    "@elysiajs/static": "^1.0.0",
     "hono": "^4.0.0"
   },
   "peerDependenciesMeta": {
     "elysia": {
       "optional": true
     },
-    "@elysiajs/static": {
-      "optional": true
-    },
     "hono": {
       "optional": true
     }
   },
   "dependencies": {
-    "@babel/core": "^7.24.0",
-    "@babel/preset-typescript": "^7.24.0",
-    "babel-preset-solid": "^1.8.0",
-    "seroval": "^1.0.0"
+    "@babel/core": "^7.29.7",
+    "@babel/preset-typescript": "^7.29.7",
+    "@types/babel__core": "^7.20.5",
+    "babel-preset-solid": "^1.9.12",
+    "seroval": "^1.5.5"
   },
   "devDependencies": {
-    "@elysiajs/static": "^1.2.0",
-    "@types/babel__core": "^7.20.5",
-    "@types/bun": "latest",
-    "elysia": "^1.2.0",
-    "hono": "^4.6.14",
-    "solid-js": "^1.9.0",
-    "typescript": "^5.0.0"
+    "@types/bun": "^1.3.14",
+    "elysia": "^1.4.29",
+    "file-type": "^21.3.1",
+    "hono": "^4.12.30",
+    "solid-js": "^1.9.14",
+    "typescript": "^5.9.3"
   },
   "license": "MIT",
   "author": "Valentin Kolb",

package/src/adapter/bun.ts

@@ -4,11 +4,9 @@
  */
 import type { SsrConfig } from "../index";
 import {
+  createAssetResponse,
   getSsrDir,
-  getCacheHeaders,
   createReloadResponse,
-  notFound,
-  safePath,
 } from "./utils";
 
 type RouteHandler = (req: Request) => Response | Promise<Response>;
@@ -39,21 +37,14 @@ export const routes = (config: SsrConfig): Routes => {
       }
     : {};
 
+  const serveAsset: RouteHandler = (req) => {
+    const filename = new URL(req.url).pathname.split("/").pop()!;
+    return createAssetResponse(req, ssrDir, filename, dev);
+  };
+
   return {
     ...devRoutes,
-
-    [`${ssrPath}/*.js`]: async (req) => {
-      const filename = new URL(req.url).pathname.split("/").pop()!;
-      const path = safePath(ssrDir, filename);
-      if (!path) return notFound();
-      const file = Bun.file(path);
-      if (!(await file.exists())) return notFound();
-      return new Response(file, {
-        headers: {
-          "Content-Type": file.type,
-          "Cache-Control": getCacheHeaders(dev),
-        },
-      });
-    },
+    [`${ssrPath}/*.js`]: serveAsset,
+    [`${ssrPath}/*.js.map`]: serveAsset,
   };
 };

package/src/adapter/elysia.ts

@@ -1,13 +1,12 @@
 /**
  * Elysia adapter - provides Elysia plugin with SSR routes.
- * Uses staticPlugin for serving island chunks.
+ * Uses the shared BunFile-backed asset response path.
  */
 import { Elysia } from "elysia";
-import { staticPlugin } from "@elysiajs/static";
 import type { SsrConfig } from "../index";
 import {
+  createAssetResponse,
   getSsrDir,
-  getCacheHeaders,
   createReloadResponse,
   notFound,
 } from "./utils";
@@ -29,13 +28,9 @@ export const routes = (config: SsrConfig) => {
   const ssrDir = getSsrDir(config);
 
   return new Elysia({ name: "ssr" })
-    .use(
-      staticPlugin({
-        assets: ssrDir,
-        prefix: ssrPath,
-        headers: { "Cache-Control": getCacheHeaders(dev) },
-      }),
-    )
     .get(`${ssrPath}/_reload`, () => (dev ? createReloadResponse() : notFound()))
-    .get(`${ssrPath}/_ping`, () => (dev ? new Response("ok") : notFound()));
+    .get(`${ssrPath}/_ping`, () => (dev ? new Response("ok") : 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 { getSsrDir, getCacheHeaders, createReloadResponse, safePath } from "./utils";
+import { createAssetResponse, getSsrDir, createReloadResponse } from "./utils";
 
 // ============================================================================
 // Types
@@ -176,19 +176,10 @@ export const routes = (config: SsrConfig) => {
     app.get("/_ping", (c) => c.text("ok"));
   }
 
-  // Serve island chunks
-  app.get("/:filename{.+\\.js$}", async (c) => {
-    const path = safePath(ssrDir, c.req.param("filename"));
-    if (!path) return c.notFound();
-    const file = Bun.file(path);
-    if (!(await file.exists())) return c.notFound();
-    return c.body(await file.arrayBuffer(), {
-      headers: {
-        "Content-Type": "application/javascript",
-        "Cache-Control": getCacheHeaders(dev),
-      },
-    });
-  });
+  const serveAsset = (c: Context) => createAssetResponse(c.req.raw, ssrDir, c.req.param("filename"), dev);
+
+  app.get("/:filename{.+\\.js$}", serveAsset);
+  app.get("/:filename{.+\\.js\\.map$}", serveAsset);
 
   return app;
 };

package/src/adapter/utils.ts

@@ -1,6 +1,6 @@
 /**
- * Shared utilities for SSR adapters - path helpers, cache headers,
- * SSE stream for hot reload, and security utilities.
+ * Shared utilities for SSR adapters - path helpers, asset responses,
+ * SSE live reload, and security utilities.
  */
 import { dirname, join, resolve } from "path";
 import type { SsrConfig } from "../index";
@@ -34,11 +34,78 @@ export const toSsrPath = (basePath: string): string =>
 export const getSsrDir = (config: SsrConfig): string =>
   join(config.dev ? config.rootDir ?? process.cwd() : dirname(Bun.main), "_ssr");
 
+const HASHED_CHUNK = /^chunk-[a-z0-9]+\.js$/i;
+const ASSET_FILE = /^[a-z0-9._-]+\.js(?:\.map)?$/i;
+
+/**
+ * Stable entry names can change during development. Content-hashed chunks
+ * cannot, so the browser may retain them across page navigations.
+ */
+export const getCacheHeaders = (dev: boolean, filename = "") =>
+  !dev || HASHED_CHUNK.test(filename) ? "public, max-age=31536000, immutable" : "no-cache";
+
+const matchesEtag = (header: string, etag: string): boolean => {
+  const normalized = etag.replace(/^W\//, "");
+  return header.split(",").some((candidate) => {
+    const value = candidate.trim();
+    return value === "*" || value.replace(/^W\//, "") === normalized;
+  });
+};
+
+const isNotModified = (request: Request, etag: string, lastModified: number): boolean => {
+  const ifNoneMatch = request.headers.get("If-None-Match");
+  if (ifNoneMatch) return matchesEtag(ifNoneMatch, etag);
+
+  const ifModifiedSince = request.headers.get("If-Modified-Since");
+  if (!ifModifiedSince) return false;
+  const since = Date.parse(ifModifiedSince);
+  return Number.isFinite(since) && Math.floor(lastModified / 1000) <= Math.floor(since / 1000);
+};
+
 /**
- * Cache headers for static assets
+ * Serves generated island assets without eagerly buffering their contents.
+ * Dev validators make stable entries cheap to revalidate while preserving
+ * immediate rebuild visibility.
  */
-export const getCacheHeaders = (dev: boolean) =>
-  dev ? "no-cache" : "public, max-age=31536000, immutable";
+export const createAssetResponse = async (
+  request: Request,
+  directory: string,
+  filename: string,
+  dev: boolean,
+): Promise<Response> => {
+  if (!ASSET_FILE.test(filename)) return notFound();
+  const path = safePath(directory, filename);
+  if (!path) return notFound();
+
+  const contentType = filename.endsWith(".map")
+    ? "application/json; charset=utf-8"
+    : "application/javascript";
+  const file = Bun.file(path, { type: contentType });
+  if (!(await file.exists())) return notFound();
+
+  const cacheControl = getCacheHeaders(dev, filename);
+  if (!dev) {
+    return new Response(file, {
+      headers: { "Content-Type": contentType, "Cache-Control": cacheControl },
+    });
+  }
+
+  const lastModified = file.lastModified;
+  const etag = `W/"${file.size.toString(16)}-${Math.trunc(lastModified).toString(16)}"`;
+  const validatorHeaders = {
+    "Cache-Control": cacheControl,
+    ETag: etag,
+    "Last-Modified": new Date(lastModified).toUTCString(),
+  };
+
+  if (isNotModified(request, etag, lastModified)) {
+    return new Response(null, { status: 304, headers: validatorHeaders });
+  }
+
+  return new Response(file, {
+    headers: { "Content-Type": contentType, ...validatorHeaders },
+  });
+};
 
 /**
  * SSE headers for live reload

package/src/build.ts

@@ -4,17 +4,35 @@
  */
 import { relative, resolve } from "path";
 import { Glob } from "bun";
+import { unlink } from "fs/promises";
 import { transform } from "./transform";
 import { ISLAND_ID_LENGTH, islandIdFromFile, toStableKey } from "./island-id";
 
 type ComponentType = "island" | "client";
 
+export type DevSourcemap = "none" | "linked" | "inline";
+
 const getComponentType = (path: string): ComponentType => (path.includes(".client.") ? "client" : "island");
 
 const getSelector = (type: ComponentType, id: string) =>
   type === "island" ? `solid-island[data-id="${id}"]` : `solid-client[data-id="${id}"]`;
 
 const fmt = (ms: number) => (ms >= 1000 ? `${(ms / 1000).toFixed(2)}s` : `${Math.round(ms)}ms`);
+const GENERATED_ASSET = /^(?:[a-f0-9]{12}|chunk-[a-z0-9]+)\.js(?:\.map)?$/i;
+
+const removeStaleBuildAssets = async (outdir: string, outputs: readonly Bun.BuildArtifact[]): Promise<number> => {
+  const current = new Set(outputs.map((output) => resolve(output.path)));
+  let removed = 0;
+
+  for await (const file of new Glob("*.js*").scan({ cwd: outdir, absolute: true })) {
+    const filename = file.slice(file.lastIndexOf("/") + 1);
+    if (!GENERATED_ASSET.test(filename) || current.has(resolve(file))) continue;
+    await unlink(file);
+    removed += 1;
+  }
+
+  return removed;
+};
 
 /**
  * Workaround for Bun bundler bug: duplicate export statements in shared chunks
@@ -73,9 +91,10 @@ export const buildIslands = async (options: {
   cwd: string;
   verbose: boolean;
   dev?: boolean;
+  devSourcemap?: DevSourcemap;
   external?: string[];
 }): Promise<void> => {
-  const { pattern, outdir, cwd, verbose, dev = false, external } = options;
+  const { pattern, outdir, cwd, verbose, dev = false, devSourcemap = "linked", external } = options;
   const resolvedCwd = resolve(cwd);
 
   const totalStart = performance.now();
@@ -137,7 +156,7 @@ export const buildIslands = async (options: {
     external,
     minify: !dev,
     splitting: true,
-    sourcemap: dev ? "inline" : "none",
+    sourcemap: dev ? devSourcemap : "none",
     plugins: [
       {
         name: "solid-islands",
@@ -181,10 +200,15 @@ export const buildIslands = async (options: {
     ],
   });
 
-  if (result.success && !dev) {
-    await dedupeSharedChunkExports(outdir, verbose);
-  } else if (result.success && dev && verbose) {
-    console.log("Skipped shared-chunk export rewrite in dev mode.");
+  if (result.success) {
+    const removed = await removeStaleBuildAssets(outdir, result.outputs);
+    if (verbose && removed > 0) console.log(`Removed ${removed} stale build asset(s).`);
+
+    if (!dev) {
+      await dedupeSharedChunkExports(outdir, verbose);
+    } else if (verbose) {
+      console.log("Skipped shared-chunk export rewrite in dev mode.");
+    }
   }
 
   if (verbose) {

package/src/index.ts

@@ -9,7 +9,7 @@ import type { JSX } from "solid-js";
 import type { BunPlugin } from "bun";
 import { statSync } from "fs";
 import { transform } from "./transform";
-import { buildIslands } from "./build";
+import { buildIslands, type DevSourcemap } from "./build";
 import { join, dirname, resolve } from "path";
 import { resolveIslandImport } from "./island-resolve";
 import { normalizeBasePath, toSsrPath } from "./adapter/utils";
@@ -51,6 +51,8 @@ export type SsrOptions<T extends object = object> = {
   basePath?: string;
   /** Modules to exclude from the island bundle (passed to Bun.build) */
   external?: string[];
+  /** Development island sourcemaps (default: "linked") */
+  devSourcemap?: DevSourcemap;
   /** HTML template function (optional, has default) */
   template?: (
     ctx: {
@@ -112,7 +114,15 @@ export type SsrResult<T extends object> = {
  * ```
  */
 export const createConfig = <T extends object = object>(options: SsrOptions<T> = {}): SsrResult<T> => {
-  const { dev = false, verbose, external, template, rootDir: rootDirOption, basePath: basePathOption } = options;
+  const {
+    dev = false,
+    verbose,
+    external,
+    devSourcemap = "linked",
+    template,
+    rootDir: rootDirOption,
+    basePath: basePathOption,
+  } = options;
   const rootDir = resolve(rootDirOption ?? process.cwd());
   const basePath = normalizeBasePath(basePathOption);
   const ssrPath = toSsrPath(basePath);
@@ -200,6 +210,7 @@ export const createConfig = <T extends object = object>(options: SsrOptions<T> =
             cwd: rootDir,
             verbose: verbose ?? !dev,
             dev,
+            devSourcemap,
             external,
           });
         };

package/src/nav.ts

@@ -0,0 +1,229 @@
+/**
+ * Opt-in browser navigation helpers for SSR islands.
+ *
+ * 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 { createDynamic } from "solid-js/web";
+
+type AnchorProps = JSX.AnchorHTMLAttributes<HTMLAnchorElement>;
+
+export type NavigationScrollMode = "top" | "preserve" | "manual";
+
+export type ScrollSnapshot = {
+  window: { x: number; y: number };
+  regions: Array<{
+    key: string;
+    x: number;
+    y: number;
+  }>;
+};
+
+export type EnhancedNavigateOptions = {
+  replace?: boolean;
+  scroll?: NavigationScrollMode;
+  scrollSnapshot?: ScrollSnapshot;
+  viewTransition?: boolean;
+};
+
+export type LinkNavigateEvent = {
+  event: MouseEvent;
+  href: string;
+  url: URL;
+  replace: boolean;
+  scroll: NavigationScrollMode;
+  push: (href?: string, options?: EnhancedNavigateOptions) => void;
+  replaceWith: (href?: string, options?: Omit<EnhancedNavigateOptions, "replace">) => void;
+  fallback: (href?: string) => void;
+  scrollSnapshot: ScrollSnapshot;
+  captureScroll: (selector?: string) => ScrollSnapshot;
+  restoreScroll: typeof restoreScroll;
+};
+
+export type LinkProps = Omit<AnchorProps, "href" | "onClick"> & {
+  href: string;
+  replace?: boolean;
+  scroll?: NavigationScrollMode;
+  onClick?: JSX.EventHandlerUnion<HTMLAnchorElement, MouseEvent>;
+  onNavigate?: (event: LinkNavigateEvent) => void | Promise<void>;
+};
+
+const SCROLL_PRESERVE_SELECTOR = "[data-scroll-preserve]";
+
+type ViewTransitionDocument = Document & {
+  startViewTransition?: (callback: () => void | Promise<void>) => unknown;
+};
+
+/**
+ * Returns the current URL path + query, without the hash.
+ */
+export const currentPathWithQuery = (): string => {
+  const url = new URL(window.location.href);
+  return `${url.pathname}${url.search}`;
+};
+
+/**
+ * Navigates to the current path + query with a full document navigation.
+ */
+export const refreshCurrentPath = (): void => {
+  window.location.assign(currentPathWithQuery());
+};
+
+/**
+ * Navigates with a full document navigation.
+ */
+export const navigateTo = (href: string): void => {
+  window.location.assign(href);
+};
+
+export const startViewTransition = (callback: () => void | Promise<void>): void => {
+  const doc = document as ViewTransitionDocument;
+  if (!doc.startViewTransition) {
+    void callback();
+    return;
+  }
+  doc.startViewTransition(callback);
+};
+
+const restoreRegionScroll = (snapshot: ScrollSnapshot): void => {
+  for (const region of snapshot.regions) {
+    const selector = `[data-scroll-preserve="${CSS.escape(region.key)}"]`;
+    const el = document.querySelector<HTMLElement>(selector);
+    if (!el) continue;
+    el.scrollLeft = region.x;
+    el.scrollTop = region.y;
+  }
+};
+
+/**
+ * Captures window scroll and keyed `[data-scroll-preserve]` regions.
+ */
+export const captureScroll = (selector = SCROLL_PRESERVE_SELECTOR): ScrollSnapshot => ({
+  window: { x: window.scrollX, y: window.scrollY },
+  regions: Array.from(document.querySelectorAll<HTMLElement>(selector))
+    .map((el) => ({
+      key: el.dataset.scrollPreserve ?? "",
+      x: el.scrollLeft,
+      y: el.scrollTop,
+    }))
+    .filter((region) => region.key.length > 0),
+});
+
+/**
+ * Restores a captured scroll snapshot.
+ */
+export const restoreScroll = (snapshot: ScrollSnapshot, options: { window?: boolean } = {}): void => {
+  restoreRegionScroll(snapshot);
+  if (options.window === false) return;
+  window.scrollTo(snapshot.window.x, snapshot.window.y);
+};
+
+/**
+ * Updates browser history without a document reload.
+ *
+ * Use this after the current island has already updated its UI or when it is
+ * intentionally preserving the current DOM. It does not match routes, load
+ * data, or re-render server pages.
+ */
+export const navigate = (href: string, options: EnhancedNavigateOptions = {}): void => {
+  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);
+
+    if (!snapshot) return;
+    restoreRegionScroll(snapshot);
+    if (scroll === "preserve") {
+      window.scrollTo(snapshot.window.x, snapshot.window.y);
+      return;
+    }
+    window.scrollTo(0, 0);
+  };
+
+  if (options.viewTransition === false) {
+    commit();
+    return;
+  }
+  startViewTransition(commit);
+};
+
+export const documentNavigate = (href: string, options: { replace?: boolean } = {}): void => {
+  if (options.replace) window.location.replace(href);
+  else window.location.assign(href);
+};
+
+const shouldEnhanceClick = (event: MouseEvent, anchor: HTMLAnchorElement): boolean => {
+  if (event.defaultPrevented || event.button !== 0) return false;
+  if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return false;
+  if (anchor.target && anchor.target !== "_self") return false;
+  if (anchor.hasAttribute("download")) return false;
+
+  const url = new URL(anchor.href, window.location.href);
+  return url.origin === window.location.origin;
+};
+
+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 });
+    return;
+  }
+  (handler as unknown as EventListenerObject).handleEvent(event);
+};
+
+/**
+ * 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 handleClick: JSX.EventHandler<HTMLAnchorElement, MouseEvent> = (event) => {
+    callUserClick(props.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 scrollSnapshot = captureScroll();
+
+    event.preventDefault();
+
+    if (!props.onNavigate) {
+      navigate(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,
+      }),
+    );
+  };
+
+  return createDynamic(() => "a", {
+    ...anchorProps(),
+    href: props.href,
+    onClick: handleClick,
+  });
+}