waku-navigation 0.0.3 → 0.0.4

package/README.md

@@ -4,6 +4,8 @@ A drop-in replacement for `waku/router/client` built on the [Navigation API](htt
 
 The entire public surface of `waku/router/client` — including every `unstable_*` feature — has a path to the same behavior with `waku-navigation`. This README walks through every feature and shows what the migration looks like.
 
+Because the Navigation API intercepts plain `<a>` clicks, **every `<a>` already navigates client-side — no `<Link>` required.** `<Link>` is still here, as an _enhancement_: it adds a type-safe `to`, prefetching, and per-link navigation status. Reach for `<Link>` when you want those; use a plain `<a>` when you don't.
+
 > **Browser support**: the Navigation API ships in Chromium 102+ and Safari 26 / Firefox 145 (behind/with caveats on some older versions). Check [caniuse](https://caniuse.com/mdn-api_navigation) for current coverage.
 
 ## Install
@@ -39,7 +41,7 @@ Pages and `pages/_slices/*` work exactly as in any Waku app — `waku-navigation
 ## Examples
 
 - `examples/01_minimal` — `useRouter`, `<Slice>`, 404, prefetch, scroll option, events, HMR ([StackBlitz](https://stackblitz.com/github/wakujs/waku-navigation/tree/main/examples/01_minimal))
-- `examples/02_pending` — `useNavigationStatus_UNSTABLE` pending indicators on plain `<a>` for slow routes, client-suspense settling
+- `examples/02_pending` — `<Link>` with per-link `useNavigationStatus_UNSTABLE` pending indicators, two same-route links staying independent on click, a View Transitions link, and a non-navigation transition that leans on the browser's native spinner
 
 ---
 
@@ -84,57 +86,62 @@ Notes:
 - `scroll: false` is forwarded to the navigate event via the Navigation API's `info` channel, which is not persisted in history. The internal handler then intercepts with `scroll: 'manual'` so the browser skips its default after-transition scroll.
 - `prefetch(to)` calls `unstable_prefetchRsc` and, if the build publishes a `__WAKU_ROUTER_PREFETCH__` helper, preloads the route's JS chunks via `react-dom`'s `preloadModule`.
 
-### `useNavigationStatus_UNSTABLE({ href?, dataNavKey? })`
+### `<Link>`
+
+A plain `<a>` already navigates client-side, so `<Link>` is an _enhancement_, not a requirement. It adds the three things a bare `<a>` can't express:
 
-There is no `<Link>` — plain `<a>` navigates (the Navigation API intercepts same-origin clicks; see [`<Link>` → plain `<a>`](#link--plain-a)). The one thing a bare `<a>` can't express is per-link _pending_ state, because the indicator needs to bind a DOM anchor to React state. This hook supplies that binding, two ways:
+- a **type-safe `to`** — checked against your generated routes, like `waku/router`'s `<Link>`;
+- **prefetching** — `unstable_prefetchOnEnter` / `unstable_prefetchOnView`;
+- **navigation status** — readable by any descendant via `useNavigationStatus_UNSTABLE()`.
 
 ```tsx
-'use client';
-import { useNavigationStatus_UNSTABLE } from 'waku-navigation';
+import { Link } from 'waku-navigation';
 
-// (a) by destination href — nothing extra on the <a>:
-function NavSpinner({ href }: { href: string }) {
-  const { pending } = useNavigationStatus_UNSTABLE({ href });
-  return pending ? <span>…</span> : null;
-}
+<Link to="/slow">
+  Slow <NavSpinner />
+</Link>;
+```
 
-// (b) by data-nav-key — distinguishes two same-href anchors:
-function IdSpinner({ dataNavKey }: { dataNavKey: string }) {
-  const { pending } = useNavigationStatus_UNSTABLE({ dataNavKey });
-  return pending ? <span>…</span> : null;
-}
+```ts
+export type LinkProps = {
+  to: InferredPaths; // type-safe, from your generated routes
+  scroll?: boolean; // false keeps scroll position; otherwise browser default
+  unstable_prefetchOnEnter?: boolean; // prefetch on pointer enter
+  unstable_prefetchOnView?: boolean; // prefetch when scrolled into view
+  unstable_startTransition?: (fn: TransitionFunction) => void; // e.g. View Transitions
+  ref?: Ref<HTMLAnchorElement>;
+} & Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'>;
 ```
 
-```tsx
-<a href="/slow">Slow <NavSpinner href="/slow" /></a>
+`<Link>` does not intercept the click itself — the browser fires the navigate event and the router correlates it back to this instance. So modifier-clicks, `target`, `download`, and cross-origin `to` all keep their native behavior (use a plain `<a>` for those anyway). The props mirror `waku/router`'s `<Link>`, so migrating across is an import swap.
 
-<a href="/slow" data-nav-key="slow">Slow <IdSpinner dataNavKey="slow" /></a>
-```
+`unstable_startTransition` overrides how the route-commit transition is started — for example, to integrate the browser View Transitions API. When provided, the per-link pending state is bypassed (it stays `{}`), matching `waku/router`.
 
-`pending` is `true` while a matching navigation is in flight and clears in the same commit that reveals the new route — after the destination's client-side `<Suspense>` boundaries settle, and also on abort or error.
+### `useNavigationStatus_UNSTABLE()`
 
-The two match modes:
+Returns the navigation status of the enclosing `<Link>`, like React's `useFormStatus`. No arguments — it reads the `<Link>` by context.
 
-- **`{ href }`** matches any navigation whose destination is that href — the consumer just names the destination, and the `<a>` needs no attribute. Matching is same-origin and compares path **and query** (not bare pathname), so `{ href: '/search?q=a' }` does not light for `/search?q=b`. The fragment is ignored: `{ href: '/slow#x' }` is treated the same as `{ href: '/slow' }` (hash-only navigations never set `pending`). The trade-off: it keys off the destination, so every anchor to the same path+query shares it (no per-anchor independence). Think `<label htmlFor>` pointing at a route rather than an element.
-- **`{ dataNavKey }`** matches the navigation from the `<a data-nav-key="…">` with that id. This is what keeps two same-href anchors independent — give them different ids. For repeated or list-rendered links, generate the id with `useId()` in the client component that renders the `<a>` and pass it to both sides:
+```tsx
+'use client';
+import { useNavigationStatus_UNSTABLE } from 'waku-navigation';
 
-  ```tsx
-  'use client';
-  function SlowLink() {
-    const dataNavKey = useId();
-    return (
-      <a href="/slow" data-nav-key={dataNavKey}>
-        Slow <IdSpinner dataNavKey={dataNavKey} />
-      </a>
-    );
-  }
-  ```
+function NavSpinner() {
+  const { pending } = useNavigationStatus_UNSTABLE();
+  return pending ? <span>…</span> : null;
+}
+```
 
-Pass both (`{ href, dataNavKey }`) to match either. The consumer can live anywhere — inside the `<a>`, beside it, or in a distant component (e.g. a global loading bar) — since the match is by value, not DOM position. A match that nothing satisfies simply never goes `pending` (the empty-state equivalent of calling upstream's hook outside a `<Link>`).
+```tsx
+<Link to="/slow">
+  Slow <NavSpinner />
+</Link>
+```
 
-The counterpart of `waku/router/client`'s `useNavigationStatus_UNSTABLE`. A click matches the clicked anchor (its `data-nav-key` and/or the destination href); programmatic and back-forward navigations (no `sourceElement`) match by destination href, and resolve a `data-nav-key` from the first matching anchor in the DOM. Hash-only navigations complete instantly and never set `pending`.
+`pending` is `true` while the link's navigation is in flight and clears in the same commit that reveals the new route — after the destination's client-side `<Suspense>` boundaries settle, and also on abort or error. Two `<Link>`s to the same route stay **independent on click** (the router correlates the clicked one by its own element); programmatic and back/forward navigations have no source element, so every `<Link>` to the destination lights up together. Outside a `<Link>`, the hook returns `{}`.
 
-Internally the hook holds a `useOptimistic` state that the router flips inside the navigation transition; React reverts it automatically when the transition settles, so there's no subscription or cleanup to manage.
+Internally each `<Link>` holds a `useOptimistic` state that the router flips inside the navigation transition; React reverts it automatically when the transition settles, so there's no subscription or cleanup to manage.
+
+> **You often don't need a custom spinner at all.** React already drives the browser's native spinner for transitions — during a navigation the Navigation API holds the request pending until the new route commits, and for non-navigation transitions React (≥19.2) fires a fake navigation via `onDefaultTransitionIndicator` to spin that same native indicator. Reach for `useNavigationStatus_UNSTABLE` when you want an _in-page_, per-link indicator on top of the browser-level one. `examples/02_pending` includes a transition (the home page's "Load batch" button) that relies on the native spinner alone.
 
 ### `<Slice>`
 
@@ -160,71 +167,41 @@ import { Slice } from 'waku-navigation';
 
 `<Router>` takes no props in `waku-navigation` — there is no `initialRoute`, `unstable_fetchRscStore`, or `unstable_routeInterceptor`. The initial route comes from `window.navigation`. If you used `unstable_routeInterceptor` to rewrite a path before refetch, do it in your `useRouter().push` call site instead.
 
-### `<Link>` → plain `<a>`
+### `<Link>` (drop-in) or plain `<a>`
 
-There is no `<Link>` — drop it and use a plain `<a>`. The Navigation API intercepts same-origin `<a>` clicks for you, and cross-origin links, hash-only links, download links, and modifier-keyed clicks all behave correctly:
+`<Link>` is a drop-in — same import path swap, same props (`to`, `scroll`, `unstable_prefetchOnEnter`, `unstable_prefetchOnView`, `unstable_startTransition`, `ref`, and any `<a>` attributes):
 
 ```diff
 - import { Link } from 'waku/router/client';
-- <Link to="/about">About</Link>
-+ <a href="/about">About</a>
++ import { Link } from 'waku-navigation';
+  <Link to="/about">About</Link>
 ```
 
-Specific `<Link>` props translate as follows:
-
-| `<Link>` prop                | `waku-navigation` equivalent                                                                                  |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `to="/x"`                    | `<a href="/x">`                                                                                               |
-| `scroll={false}`             | Click handler that calls `useRouter().push(href, { scroll: false })`                                          |
-| `unstable_pending={node}`    | A consumer using `useNavigationStatus_UNSTABLE({ href })` (or `{ dataNavKey }`) to render `node` when pending |
-| `unstable_notPending={node}` | Same, rendering `node` when `!pending`                                                                        |
-| `unstable_prefetchOnEnter`   | `onMouseEnter={() => useRouter().prefetch(href)}` in a client component                                       |
-| `unstable_prefetchOnView`    | `IntersectionObserver` + `useRouter().prefetch(href)`                                                         |
-| `unstable_startTransition`   | Not needed — the router runs every navigation in a transition internally                                      |
-
-Example for prefetch-on-hover:
-
-```tsx
-'use client';
-import { useRouter } from 'waku-navigation';
+Or drop `<Link>` entirely where you don't need type-safety, prefetching, or status — a plain `<a>` navigates client-side on its own:
 
-export function PrefetchLink({
-  to,
-  children,
-}: {
-  to: string;
-  children: ReactNode;
-}) {
-  const { prefetch } = useRouter();
-  return (
-    <a href={to} onMouseEnter={() => prefetch(to)}>
-      {children}
-    </a>
-  );
-}
+```diff
+- <Link to="/about">About</Link>
++ <a href="/about">About</a>
 ```
 
+Cross-origin links, hash-only links, download links, and modifier-keyed clicks all behave correctly with a plain `<a>` — the Navigation API passes them through.
+
 ### `<Link>…<Consumer/></Link>` (navigation status)
 
-`waku/router` lets any descendant of a `<Link>` read its navigation status via `useNavigationStatus_UNSTABLE`, relying on the `<Link>` for context. With a plain `<a>` there's no context, so the consumer names what it watches — the destination `href` is the simplest, and needs nothing on the `<a>`:
+Unchanged — a descendant reads the enclosing `<Link>`'s status via the no-arg hook, exactly as in `waku/router`:
 
 ```diff
 - import { Link, useNavigationStatus_UNSTABLE } from 'waku/router/client';
-+ import { useNavigationStatus_UNSTABLE } from 'waku-navigation';
++ import { Link, useNavigationStatus_UNSTABLE } from 'waku-navigation';
 
-- function NavSpinner() {
--   const { pending } = useNavigationStatus_UNSTABLE();
-+ function NavSpinner({ href }: { href: string }) {
-+   const { pending } = useNavigationStatus_UNSTABLE({ href });
+  function NavSpinner() {
+    const { pending } = useNavigationStatus_UNSTABLE();
     return pending ? <span>…</span> : null;
   }
 
-- <Link to="/slow">Slow <NavSpinner /></Link>
-+ <a href="/slow">Slow <NavSpinner href="/slow" /></a>
+  <Link to="/slow">Slow <NavSpinner /></Link>
 ```
 
-Reach for `{ dataNavKey }` + `data-nav-key` on the `<a>` only when you need two same-href anchors to light up independently.
-
 ### `<Slice>`
 
 Same import path change as `useRouter`. All props (`id`, `lazy`, `fallback`, children) are unchanged.
@@ -297,6 +274,7 @@ These are all handled inside the navigate-event listener so apps usually don't n
 - **Form submission guard** — `<form method="POST">` submissions (`event.formData != null`) are passed through to the server.
 - **Hash-only navigations** — not intercepted by default (the browser scrolls to the anchor natively), but state is synced so `useRouter().hash` reflects the new fragment. If `useRouter().push('#x', { scroll: false })` is used, the handler intercepts with `scroll: 'manual'` to honor that.
 - **Abort during transition** — `event.signal` is checked between async steps so a fast-clicked second navigation cleanly cancels the first without committing stale state.
+- **React's default transition indicator** — React (≥19.2) fires a fake same-URL navigation tagged `info: 'react-transition'` for every transition, intercepting it to show the browser's native spinner. The router skips these (they aren't route changes), so an unrelated `useTransition` anywhere in your app never triggers a refetch.
 - **404 on the client** — a refetch that throws with `getErrorInfo(err)?.status === 404` is handled by refetching `/404` and pointing the slot there, mirroring Waku's behavior. The URL still reflects the user's request.
 - **Static route cache** — routes with `getConfig({ render: 'static' })` are added to a `staticPathSet` after their first fetch; revisits skip the refetch entirely (the RSC payload is already in Waku's store).
 - **`X-Waku-Router-Skip` header** — every refetch sends the etags of elements we already have (harvested from the RSC payload's `ETAG:`-prefixed entries) so the server can skip re-rendering shared layouts/slices whose etag still matches.
@@ -306,7 +284,7 @@ These are all handled inside the navigate-event listener so apps usually don't n
 
 ## Caveats / not yet implemented
 
-- No `<Link>` component — navigation is just plain `<a>`. Pending status is opt-in via `useNavigationStatus_UNSTABLE({ href })` (by destination) or `{ dataNavKey }` (by `data-nav-key`, for same-href independence). The `<Link>` niceties (`scroll`, `unstable_prefetchOnEnter`/`OnView`) compose from `useRouter().push(href, { scroll })` / `useRouter().prefetch(href)`.
+- `<Link>` is an enhancement over plain `<a>`, not a requirement: a plain `<a>` navigates client-side on its own; `<Link>` adds a type-safe `to`, prefetching, and per-link navigation status via `useNavigationStatus_UNSTABLE()`.
 - `unstable_routeInterceptor` (server-side route rewrite hook) is not supported.
 - `unstable_fetchRscStore` (custom RSC store) is not exposed on `<Router>`.
 - Requires a browser with the Navigation API. There is currently no fallback for older browsers.

package/dist/client.d.ts

@@ -1,4 +1,5 @@
-import { Slice } from 'waku/router/client';
+import { type AnchorHTMLAttributes, type ReactNode, type Ref } from 'react';
+import { Slice, type Unstable_InferredPaths as InferredPaths } from 'waku/router/client';
 export { Slice };
 type Route = {
     path: string;
@@ -8,13 +9,43 @@ type Route = {
 type NavigationStatus = {
     pending?: boolean;
 };
-type NavStatusMatch = {
-    href: string;
-    dataNavKey?: string;
-} | {
-    href?: string;
-    dataNavKey: string;
-};
+type TransitionFunction = () => void | Promise<void>;
+/**
+ * Navigation status of the enclosing {@link Link}, like React's
+ * `useFormStatus`. `pending` is `true` while the link's navigation is in
+ * flight, until the destination route's async components resolve. Returns `{}`
+ * outside a `<Link>`.
+ */
+export declare const useNavigationStatus_UNSTABLE: () => NavigationStatus;
+/** Props for {@link Link}. Mirrors `waku/router`'s `<Link>`. */
+export type LinkProps = {
+    /** Destination, type-checked against your app's generated routes. */
+    to: InferredPaths;
+    children: ReactNode;
+    /**
+     * Whether to scroll on navigation. `false` keeps the current scroll
+     * position; otherwise the browser's default after-navigation scroll applies.
+     */
+    scroll?: boolean;
+    /** Prefetch the route when the pointer enters the link. */
+    unstable_prefetchOnEnter?: boolean;
+    /** Prefetch the route when the link scrolls into view. */
+    unstable_prefetchOnView?: boolean;
+    /**
+     * Overrides how the route-commit transition is started, e.g. to integrate
+     * the browser View Transitions API. When set, the pending state is bypassed,
+     * so {@link useNavigationStatus_UNSTABLE} stays `{}` for this link.
+     */
+    unstable_startTransition?: ((fn: TransitionFunction) => void) | undefined;
+    ref?: Ref<HTMLAnchorElement> | undefined;
+} & Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'>;
+/**
+ * A type-safe, prefetching, status-aware link. A plain `<a>` already navigates
+ * client-side, so `<Link>` is an enhancement: it adds a type-checked `to`,
+ * prefetching, and per-link navigation status (read by descendants via
+ * {@link useNavigationStatus_UNSTABLE}). Mirrors `waku/router`'s `<Link>`.
+ */
+export declare function Link({ to, children, scroll, unstable_prefetchOnEnter, unstable_prefetchOnView, unstable_startTransition, ref: refProp, ...props }: LinkProps): import("react").JSX.Element;
 type PushReplaceOptions = {
     scroll?: boolean;
 };
@@ -22,6 +53,11 @@ type RouteChangeEvents = {
     on: (name: 'start' | 'complete', handler: (route: Route) => void) => void;
     off: (name: 'start' | 'complete', handler: (route: Route) => void) => void;
 };
+/**
+ * Imperative router handle: the current `path` / `query` / `hash`, plus
+ * `push` / `replace` / `reload` / `back` / `forward` / `prefetch` and
+ * `unstable_events`. Same shape as `waku/router/client`'s `useRouter`.
+ */
 export declare function useRouter(): {
     path: string;
     query: string;
@@ -34,6 +70,8 @@ export declare function useRouter(): {
     prefetch: (to: string) => void;
     unstable_events: RouteChangeEvents;
 };
-declare function useNavigationStatus({ href, dataNavKey, }: NavStatusMatch): NavigationStatus;
-export { useNavigationStatus as useNavigationStatus_UNSTABLE };
-export declare function Router(): import("react/jsx-runtime").JSX.Element;
+/**
+ * The client router. Reads the initial route from `window.navigation`, listens
+ * for navigate events, and renders the current page. Takes no props.
+ */
+export declare function Router(): import("react").JSX.Element;

package/dist/client.js

@@ -4,27 +4,95 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, startTransition, use, useCallback, useContext, useEffect, useId, useLayoutEffect, useMemo, useOptimistic, useRef, useState, } from 'react';
 import { preloadModule } from 'react-dom';
 import { Root, Slot, unstable_prefetchRsc as prefetchRsc, unstable_withEnhanceFetchFn as withEnhanceFetchFn, useElementsPromise_UNSTABLE as useElementsPromise, useRefetch, } from 'waku/minimal/client';
-import { Slice, unstable_encodeRoutePath as encodeRoutePath, unstable_getErrorInfo as getErrorInfo, unstable_parseRoute as parseRoute, unstable_getRouteSlotId as getRouteSlotId, unstable_IS_STATIC_ID as IS_STATIC_ID, unstable_ROUTE_ID as ROUTE_ID, unstable_RouterContext as RouterContext, unstable_SKIP_HEADER as SKIP_HEADER, } from 'waku/router/client';
-// Slice is re-exported from waku/router/client unchanged. It only needs the
-// router context (fetchingSlices + the elements promise) -- both of which our
-// <Router> already provides -- so the component works as-is.
+import { Slice, unstable_addBase as addBase, unstable_encodeRoutePath as encodeRoutePath, unstable_getErrorInfo as getErrorInfo, unstable_parseRoute as parseRoute, unstable_getRouteSlotId as getRouteSlotId, unstable_IS_STATIC_ID as IS_STATIC_ID, unstable_ROUTE_ID as ROUTE_ID, unstable_RouterContext as RouterContext, unstable_SKIP_HEADER as SKIP_HEADER, } from 'waku/router/client';
 export { Slice };
 const NOT_FOUND_PATH = '/404';
-// Authored by the app on a plain <a> to correlate it with a navigation-status
-// consumer, the way <label htmlFor> correlates with <input id>. The router
-// reads it off the clicked <a> (or, for programmatic navs, off the matching
-// <a> in the DOM) to know which consumers to mark pending.
-const NAV_KEY_ATTR = 'data-nav-key';
-// Mirrors ETAG_ID_PREFIX in waku's router/common.js, which is not exported
-// from waku/router/client. Elements under this prefix carry the etag for the
-// same-named slot; the X-Waku-Router-Skip header echoes them back so the
-// server can skip re-rendering unchanged slots.
+// Mirrors waku's unexported ETAG_ID_PREFIX (router/common.js).
 const ETAG_ID_PREFIX = 'ETAG:';
 const noopRegister = () => () => { };
 const NavStatusRegistryContext = createContext({
     register: noopRegister,
 });
+const NavigationStatusContext = createContext({});
+/**
+ * Navigation status of the enclosing {@link Link}, like React's
+ * `useFormStatus`. `pending` is `true` while the link's navigation is in
+ * flight, until the destination route's async components resolve. Returns `{}`
+ * outside a `<Link>`.
+ */
+export const useNavigationStatus_UNSTABLE = () => useContext(NavigationStatusContext);
+/**
+ * A type-safe, prefetching, status-aware link. A plain `<a>` already navigates
+ * client-side, so `<Link>` is an enhancement: it adds a type-checked `to`,
+ * prefetching, and per-link navigation status (read by descendants via
+ * {@link useNavigationStatus_UNSTABLE}). Mirrors `waku/router`'s `<Link>`.
+ */
+export function Link({ to, children, scroll, unstable_prefetchOnEnter, unstable_prefetchOnView, unstable_startTransition, ref: refProp, ...props }) {
+    var _a;
+    const base = (_a = import.meta.env) === null || _a === void 0 ? void 0 : _a.WAKU_CONFIG_BASE_PATH;
+    const resolvedTo = base ? addBase(to, base) : to;
+    const ctx = useContext(RouterContext);
+    const { register } = useContext(NavStatusRegistryContext);
+    const [status, setOptimisticStatus] = useOptimistic({});
+    const elementRef = useRef(null);
+    const setRef = useCallback((node) => {
+        elementRef.current = node;
+        if (typeof refProp === 'function')
+            refProp(node);
+        else if (refProp)
+            refProp.current = node;
+    }, [refProp]);
+    const id = useId();
+    useLayoutEffect(() => register(id, {
+        getElement: () => elementRef.current,
+        href: resolvedTo,
+        scroll,
+        unstable_startTransition,
+        setOptimisticStatus,
+    }), [
+        id,
+        resolvedTo,
+        scroll,
+        unstable_startTransition,
+        register,
+        setOptimisticStatus,
+    ]);
+    useEffect(() => {
+        if (!unstable_prefetchOnView || !elementRef.current)
+            return;
+        const observer = new IntersectionObserver((entries) => {
+            for (const entry of entries) {
+                if (!entry.isIntersecting)
+                    continue;
+                const url = new URL(resolvedTo, window.location.href);
+                if (url.href !== window.location.href) {
+                    ctx === null || ctx === void 0 ? void 0 : ctx.prefetchRoute(parseRoute(url));
+                }
+            }
+        }, { threshold: 0.1 });
+        observer.observe(elementRef.current);
+        return () => observer.disconnect();
+    }, [unstable_prefetchOnView, resolvedTo, ctx]);
+    const onMouseEnter = unstable_prefetchOnEnter
+        ? (event) => {
+            var _a;
+            const url = new URL(resolvedTo, window.location.href);
+            if (url.href !== window.location.href) {
+                ctx === null || ctx === void 0 ? void 0 : ctx.prefetchRoute(parseRoute(url));
+            }
+            (_a = props.onMouseEnter) === null || _a === void 0 ? void 0 : _a.call(props, event);
+        }
+        : props.onMouseEnter;
+    // No onClick: the browser fires the navigate event for the plain <a>, and
+    // InnerRouter's handler correlates it back to this instance.
+    return (_jsx(NavigationStatusContext.Provider, { value: status, children: _jsx("a", { ...props, href: resolvedTo, ref: setRef, onMouseEnter: onMouseEnter, children: children }) }));
+}
 const noopEvents = { on: () => { }, off: () => { } };
+/**
+ * Imperative router handle: the current `path` / `query` / `hash`, plus
+ * `push` / `replace` / `reload` / `back` / `forward` / `prefetch` and
+ * `unstable_events`. Same shape as `waku/router/client`'s `useRouter`.
+ */
 export function useRouter() {
     var _a, _b;
     const ctx = useContext(RouterContext);
@@ -54,35 +122,8 @@ export function useRouter() {
         unstable_events: ((_b = ctx === null || ctx === void 0 ? void 0 : ctx.routeChangeEvents) !== null && _b !== void 0 ? _b : noopEvents),
     };
 }
-// Counterpart of waku/router/client's useNavigationStatus_UNSTABLE, adapted
-// for plain <a>. Two ways to say which navigation you care about:
-//
-//   { href: '/slow' }   -- any navigation whose destination is /slow. Nothing
-//                          extra on the <a>; matches by destination, so every
-//                          anchor to /slow shares it (no independence).
-//   { dataNavKey: 'x' }  -- the navigation from <a data-nav-key="x">. Tells two
-//                          same-href anchors apart (give them different ids;
-//                          useId() for list-rendered ones).
-//
-// Pass both to match either. The consumer can live anywhere -- inside the <a>,
-// beside it, or far away. Returns { pending: undefined } until a matching
-// navigation is in flight; pending clears when the new route commits (after
-// client-side Suspense), or on abort/error.
-function useNavigationStatus({ href, dataNavKey, }) {
-    const [status, setOptimisticStatus] = useOptimistic({});
-    const { register } = useContext(NavStatusRegistryContext);
-    const id = useId();
-    useLayoutEffect(() => register(id, { href, dataNavKey, setOptimisticStatus }), [id, href, dataNavKey, register, setOptimisticStatus]);
-    return status;
-}
-export { useNavigationStatus as useNavigationStatus_UNSTABLE };
-// True when `href` (possibly relative) resolves to the same internal route as
-// `route`. Compared on origin + path + query -- not just pathname -- so
-// /search?q=a doesn't match /search?q=b, and a cross-origin href that happens
-// to share a path doesn't match an internal navigation. The fragment is
-// ignored (hash-only navigations never set pending). Malformed input returns
-// false rather than throwing, so a bad consumer href or odd DOM anchor can't
-// break the navigation handler.
+// Same origin + path + query (not pathname; fragment ignored). Malformed input
+// returns false rather than throwing.
 const routeMatchesHref = (href, route) => {
     let url;
     try {
@@ -102,15 +143,10 @@ function InnerRouter({ fallbackRoute }) {
     const [routeState, setRoute] = useState();
     let route = routeState;
     if (route === undefined) {
-        // First render only: the RSC payload records which route the server
-        // actually rendered (ROUTE_ID), so an unknown URL that was served the
-        // /404 page resolves to '/404' here. Suspending on `use` is free at this
-        // point -- the slots below suspend on the same promise during hydration
-        // -- but it must not happen on later renders: suspending InnerRouter
-        // inside the navigation transition keeps the navigation from ever
-        // committing. The hash starts as '' to match Waku's INTERNAL_ServerRouter
-        // SSR output (URL fragments aren't sent to the server) and is upgraded
-        // post-hydration in the effect below.
+        // First render only. ROUTE_ID records the route the server actually
+        // rendered, so an unknown URL served the /404 page resolves to '/404'. This
+        // must not suspend on later renders: suspending inside a navigation
+        // transition would keep it from ever committing.
         const elements = use(elementsPromise);
         const routeData = elements[ROUTE_ID];
         route =
@@ -119,26 +155,23 @@ function InnerRouter({ fallbackRoute }) {
                 : { ...fallbackRoute, hash: '' };
         setRoute(route);
     }
-    // Non-404 refetch failures (network errors, server 500s, etc.) get surfaced
-    // by rethrowing during render so the user's <ErrorBoundary> can catch them.
-    // The state clears on the next successful navigation.
+    // Rethrow during render so the user's <ErrorBoundary> catches non-404
+    // failures; cleared by the next successful navigation.
     const [renderError, setRenderError] = useState(null);
     if (renderError)
         throw renderError;
     useEffect(() => {
+        // SSR sends no fragment, so the hash starts ''; upgrade it post-hydration.
         if (fallbackRoute.hash) {
             // eslint-disable-next-line react-hooks/set-state-in-effect
             setRoute((r) => ({ ...r, hash: fallbackRoute.hash }));
         }
-        // Only on mount.
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, []);
     const registryRef = useRef(new Map());
     const staticPathSetRef = useRef(new Set());
     const cachedEtagsRef = useRef({});
-    // Stable Set so Waku's <Slice> can mutate it (add on fetch start, delete on
-    // fetch end) without losing state across re-renders. useMemo with [] keeps
-    // the same instance and avoids reading ref.current during render.
+    // Stable instance: <Slice> mutates this Set across renders.
     const fetchingSlices = useMemo(() => new Set(), []);
     useEffect(() => {
         elementsPromise.then((elements) => {
@@ -148,10 +181,10 @@ function InnerRouter({ fallbackRoute }) {
             }
             const etags = {};
             for (const [key, value] of Object.entries(elements)) {
-                // Drop empty (clear signal) and non-Latin1 (breaks fetch) tags.
+                // Skip empty (clear signal) and non-Latin1 (breaks the fetch header).
                 if (key.startsWith(ETAG_ID_PREFIX) &&
                     typeof value === 'string' &&
-                    /^[\u0020-\u00ff]+$/.test(value)) {
+                    /^[ -ÿ]+$/.test(value)) {
                     etags[key.slice(ETAG_ID_PREFIX.length)] = value;
                 }
             }
@@ -164,17 +197,15 @@ function InnerRouter({ fallbackRoute }) {
             registryRef.current.delete(id);
         };
     }, []);
-    // Adds the X-Waku-Router-Skip header mapping element ids to the etags we
-    // already hold, so the server can skip re-rendering elements whose etag
-    // still matches. Shared by navigate + prefetch.
+    // Send our cached etags via X-Waku-Router-Skip so the server can skip
+    // re-rendering slots whose etag still matches.
     const enhanceFetchWithSkip = useMemo(() => withEnhanceFetchFn((fetchFn) => (input, init) => {
         const headers = new Headers(init === null || init === void 0 ? void 0 : init.headers);
         headers.set(SKIP_HEADER, JSON.stringify(cachedEtagsRef.current));
         return fetchFn(input, { ...init, headers });
     }), []);
-    // Waku's prefetch cache keys the URLSearchParams by identity, so a fresh
-    // `new URLSearchParams(...)` on every call would invalidate the prefetch
-    // entry. We memoize by query string so the same params object is reused.
+    // Waku's prefetch cache keys params by identity, so reuse one object per
+    // query string or prefetch entries get invalidated.
     const rscParamsByQueryRef = useRef(new Map());
     const getRscParams = useCallback((query) => {
         let params = rscParamsByQueryRef.current.get(query);
@@ -200,21 +231,17 @@ function InnerRouter({ fallbackRoute }) {
             routeChangeListeners[name].delete(handler);
         },
     }), [routeChangeListeners]);
-    // Eagerly fetch the RSC for a route (used by useRouter().prefetch). Build
-    // output may also publish a __WAKU_ROUTER_PREFETCH__ helper that returns the
-    // JS chunk ids for a path; if present, we preload them too.
     const prefetchRoute = useCallback((next) => {
         var _a, _b;
         if (staticPathSetRef.current.has(next.path))
             return;
         prefetchRsc(encodeRoutePath(next.path), getRscParams(next.query), enhanceFetchWithSkip);
+        // When the build publishes it, __WAKU_ROUTER_PREFETCH__ yields the
+        // route's JS chunk ids to preload.
         (_b = (_a = globalThis).__WAKU_ROUTER_PREFETCH__) === null || _b === void 0 ? void 0 : _b.call(_a, next.path, (id) => preloadModule(id, { as: 'script' }));
     }, [enhanceFetchWithSkip, getRscParams]);
-    // Vite HMR: when a server file changes, Waku's dev runtime invokes any
-    // callbacks in __WAKU_RSC_RELOAD_LISTENERS__. We register one that drops
-    // our path/id caches (so a "static" route picks up the new content) and
-    // refetches the current route. In production import.meta.hot is undefined
-    // and the effect body returns early.
+    // Vite HMR (dev only): clear caches and refetch the current route when Waku's
+    // runtime fires __WAKU_RSC_RELOAD_LISTENERS__.
     useEffect(() => {
         var _a;
         if (!import.meta.hot)
@@ -234,25 +261,34 @@ function InnerRouter({ fallbackRoute }) {
     }, [route, refetch, getRscParams]);
     useEffect(() => {
         const callback = (event) => {
-            var _a, _b, _c;
+            var _a, _b, _c, _d;
             if (!event.canIntercept)
                 return;
             if (event.downloadRequest !== null || event.formData)
                 return;
+            // React >=19.2's default transition indicator fires fake navigations.
+            if (event.info === 'react-transition')
+                return;
             const nextRoute = parseRoute(new URL(event.destination.url));
-            // useRouter().push/replace forward { scroll } via `info`. The Navigation
-            // API itself doesn't persist `info` in history, so it only applies to
-            // this single navigation -- exactly what we want.
             const info = event.info;
-            const suppressScroll = (info === null || info === void 0 ? void 0 : info.scroll) === false;
-            // Hash-only navigations: by default we don't intercept (the browser
-            // handles URL + scroll natively), but if the caller explicitly asked
-            // to suppress scrolling we still need to intercept so we can pass
-            // scroll: 'manual' and skip the browser's anchor scroll.
+            const source = event
+                .sourceElement;
+            const clickedAnchor = (_b = (_a = source === null || source === void 0 ? void 0 : source.closest) === null || _a === void 0 ? void 0 : _a.call(source, 'a')) !== null && _b !== void 0 ? _b : null;
+            // Match the navigating <Link>(s): the clicked one by element identity (so
+            // two same-`to` links stay independent), or -- with no source element
+            // (programmatic / back-forward) -- every <Link> whose `to` hits the dest.
+            const matched = [];
+            for (const entry of registryRef.current.values()) {
+                const hit = clickedAnchor
+                    ? entry.getElement() === clickedAnchor
+                    : !source && routeMatchesHref(entry.href, nextRoute);
+                if (hit)
+                    matched.push(entry);
+            }
+            const resolvedScroll = (_c = info === null || info === void 0 ? void 0 : info.scroll) !== null && _c !== void 0 ? _c : (matched.length ? matched[0].scroll : undefined);
+            const suppressScroll = resolvedScroll === false;
             if (event.hashChange) {
-                // Hash-only navigations don't refetch, so 'start' and 'complete'
-                // both fire effectively together; emit both so subscribers don't
-                // have to special-case them.
+                // Hash-only: no refetch; intercept only to suppress the browser scroll.
                 emitRouteEvent('start', nextRoute);
                 if (suppressScroll) {
                     event.intercept({
@@ -271,35 +307,18 @@ function InnerRouter({ fallbackRoute }) {
             }
             emitRouteEvent('start', nextRoute);
             const signal = event.signal;
-            const source = event
-                .sourceElement;
-            // Resolve the navigating <a>'s data-nav-key (for dataNavKey matching):
-            // the clicked <a> (most precise, so two same-href anchors stay
-            // independent), or -- for programmatic push/replace and browser
-            // back/forward, which have no sourceElement -- the first nav-key anchor in
-            // the live DOM whose href resolves to the destination. href matching
-            // needs none of this; it keys off the destination route directly.
-            let navDataKey = (_c = (_b = (_a = source === null || source === void 0 ? void 0 : source.closest) === null || _a === void 0 ? void 0 : _a.call(source, `a[${NAV_KEY_ATTR}]`)) === null || _b === void 0 ? void 0 : _b.getAttribute(NAV_KEY_ATTR)) !== null && _c !== void 0 ? _c : null;
-            if (navDataKey === null && !source) {
-                for (const anchor of document.querySelectorAll(`a[${NAV_KEY_ATTR}]`)) {
-                    const href = anchor.getAttribute('href');
-                    if (href !== null && routeMatchesHref(href, nextRoute)) {
-                        navDataKey = anchor.getAttribute(NAV_KEY_ATTR);
-                        break;
-                    }
-                }
-            }
-            const pendingSetters = [];
-            for (const entry of registryRef.current.values()) {
-                const byKey = entry.dataNavKey !== undefined && entry.dataNavKey === navDataKey;
-                const byHref = entry.href !== undefined && routeMatchesHref(entry.href, nextRoute);
-                if (byKey || byHref)
-                    pendingSetters.push(entry.setOptimisticStatus);
-            }
+            // A clicked <Link>'s unstable_startTransition overrides the commit
+            // transition (View Transitions); its pending is then bypassed.
+            const customTransition = clickedAnchor
+                ? (_d = matched.find((e) => e.unstable_startTransition)) === null || _d === void 0 ? void 0 : _d.unstable_startTransition
+                : undefined;
+            const pendingSetters = matched
+                .filter((e) => !e.unstable_startTransition)
+                .map((e) => e.setOptimisticStatus);
             event.intercept({
                 ...(suppressScroll ? { scroll: 'manual' } : {}),
                 handler: () => new Promise((resolve, reject) => {
-                    // Always a transition: it keeps the previous page visible while the
+                    // Run in a transition: keeps the previous page visible while the
                     // next tree suspends, and scopes the optimistic pending updates so
                     // React reverts them on commit/abort/error.
                     startTransition(async () => {
@@ -331,15 +350,18 @@ function InnerRouter({ fallbackRoute }) {
                                     throw err;
                                 }
                             }
-                            // Updates after the first await lose the enclosing transition
-                            // scope (https://react.dev/reference/react/startTransition#caveats),
-                            // so re-wrap the commit -- otherwise it renders urgently and
-                            // the optimistic pending state reverts before the new tree is
-                            // ready.
-                            startTransition(() => {
+                            // Updates after the first await lose the transition scope
+                            // (https://react.dev/reference/react/startTransition#caveats),
+                            // so re-wrap the commit; a <Link>'s unstable_startTransition
+                            // takes over here.
+                            const commitRoute = () => {
                                 setRenderError(null);
                                 setRoute(targetRoute);
-                            });
+                            };
+                            if (customTransition)
+                                customTransition(commitRoute);
+                            else
+                                startTransition(commitRoute);
                             emitRouteEvent('complete', targetRoute);
                             resolve();
                         }
@@ -355,9 +377,8 @@ function InnerRouter({ fallbackRoute }) {
             window.navigation.removeEventListener('navigate', callback);
         };
     }, [refetch, enhanceFetchWithSkip, getRscParams, emitRouteEvent]);
-    // Mirror the shape Waku's INTERNAL_ServerRouter provides. We only care about
-    // `route` and `prefetchRoute`; the other fields are no-ops so the context
-    // value is type-compatible.
+    // Mirror waku's INTERNAL_ServerRouter context shape; only route and
+    // prefetchRoute are used.
     const notAvailable = (name) => () => {
         throw new Error(`${name} is not available in waku-navigation`);
     };
@@ -370,6 +391,10 @@ function InnerRouter({ fallbackRoute }) {
     }), [route, prefetchRoute, routeChangeEvents, fetchingSlices]);
     return (_jsx(RouterContext.Provider, { value: routerCtxValue, children: _jsx(NavStatusRegistryContext.Provider, { value: { register }, children: _jsx(Slot, { id: "root", children: _jsx(Slot, { id: getRouteSlotId(route.path) }) }) }) }));
 }
+/**
+ * The client router. Reads the initial route from `window.navigation`, listens
+ * for navigate events, and renders the current page. Takes no props.
+ */
 export function Router() {
     const initialRoute = parseRoute(new URL(window.navigation.currentEntry.url));
     return (_jsx(Root, { initialRscPath: encodeRoutePath(initialRoute.path), children: _jsx(InnerRouter, { fallbackRoute: initialRoute }) }));

package/dist/index.d.ts

@@ -1 +1,2 @@
-export { Router, Slice, useNavigationStatus_UNSTABLE, useRouter, } from './client.js';
+export { Link, Router, Slice, useNavigationStatus_UNSTABLE, useRouter, } from './client.js';
+export type { LinkProps } from './client.js';

package/dist/index.js

@@ -1 +1 @@
-export { Router, Slice, useNavigationStatus_UNSTABLE, useRouter, } from './client.js';
+export { Link, Router, Slice, useNavigationStatus_UNSTABLE, useRouter, } from './client.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "waku-navigation",
   "description": "Waku Router implementation with Navigation API",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "type": "module",
   "author": "Daishi Kato",
   "repository": {
@@ -30,30 +30,30 @@
   },
   "devDependencies": {
     "@eslint/js": "9.39.4",
-    "@playwright/test": "^1.60.0",
+    "@playwright/test": "^1.61.0",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
     "@types/dom-navigation": "^1.0.7",
-    "@types/node": "^25.7.0",
-    "@types/react": "^19.2.14",
+    "@types/node": "^25.9.3",
+    "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "eslint": "9.39.4",
-    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-jsx-a11y": "^6.10.2",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.1.1",
-    "happy-dom": "^20.9.0",
-    "prettier": "^3.8.3",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6",
-    "react-server-dom-webpack": "^19.2.6",
+    "happy-dom": "^20.10.4",
+    "prettier": "^3.8.4",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "react-server-dom-webpack": "^19.2.7",
     "ts-expect": "^1.3.0",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.59.3",
-    "vite": "^8.0.12",
-    "vitest": "^4.1.6",
+    "typescript-eslint": "^8.61.1",
+    "vite": "^8.0.16",
+    "vitest": "^4.1.9",
     "waku": "1.0.0-beta.3",
     "waku-navigation": "link:"
   },