waku-navigation 0.0.2 → 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` — `<Pending>` 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
 
 ---
 
@@ -53,7 +55,7 @@ import { Router } from 'waku-navigation';
 <Router />;
 ```
 
-No props. It reads the initial route from `window.navigation.currentEntry.url`, sets up the navigate-event listener, and renders the page slot. It mirrors the shape Waku's `INTERNAL_ServerRouter` provides during SSR, so server-rendered markup hydrates without a flicker.
+No props. It reads the initial route from `window.navigation.currentEntry.url` (preferring the route recorded in the RSC payload, so a server-rendered 404 page resolves to `/404`), sets up the navigate-event listener, and renders the page slot. It mirrors the shape Waku's `INTERNAL_ServerRouter` provides during SSR, so server-rendered markup hydrates without a flicker.
 
 ### `useRouter()`
 
@@ -84,21 +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`.
 
-### `<Pending>`
+### `<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:
+
+- 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
-import { Pending } from 'waku-navigation';
+import { Link } from 'waku-navigation';
+
+<Link to="/slow">
+  Slow <NavSpinner />
+</Link>;
+```
+
+```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'>;
+```
+
+`<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.
+
+`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`.
+
+### `useNavigationStatus_UNSTABLE()`
+
+Returns the navigation status of the enclosing `<Link>`, like React's `useFormStatus`. No arguments — it reads the `<Link>` by context.
+
+```tsx
+'use client';
+import { useNavigationStatus_UNSTABLE } from 'waku-navigation';
 
-<Pending fallback={<Spinner />}>
-  <a href="/slow">Go slow</a>
-</Pending>;
+function NavSpinner() {
+  const { pending } = useNavigationStatus_UNSTABLE();
+  return pending ? <span>…</span> : null;
+}
+```
+
+```tsx
+<Link to="/slow">
+  Slow <NavSpinner />
+</Link>
 ```
 
-`<Pending>` wraps an `<a>` and shows `fallback` while a navigation to that `<a>`'s href is in flight. Each `<Pending>` gets a unique id (via `useId`) that's stamped on the wrapped `<a>`; the router reads `event.sourceElement` to know which Pending fired so two Pendings pointing at the same href stay independent.
+`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 `{}`.
 
-For navigations that have no `sourceElement` — `useRouter().push('/slow')`, `navigation.navigate(...)`, browser back/forward — the router falls back to the first `<Pending>` whose wrapped `<a>`'s href resolves to the destination path. So a Pending around a `<a href="/slow">` lights up for `useRouter().push('/slow')` too.
+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.
 
-`<Pending>` only shows its fallback for the actual route change; React's transition keeps the previous page visible until the new tree (including any client-side `<Suspense>` boundaries) is ready to commit.
+> **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>`
 
@@ -124,46 +167,39 @@ 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>`
+
+`<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';
++ import { Link } from 'waku-navigation';
+  <Link to="/about">About</Link>
+```
+
+Or drop `<Link>` entirely where you don't need type-safety, prefetching, or status — a plain `<a>` navigates client-side on its own:
+
+```diff
 - <Link to="/about">About</Link>
 + <a href="/about">About</a>
 ```
 
-The Navigation API intercepts same-origin `<a>` clicks for you. Cross-origin links, hash-only links, download links, and modifier-keyed clicks all behave correctly without `<Link>`. Specific `<Link>` props translate as follows:
+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>` prop                | `<a>` / `waku-navigation` equivalent                                                   |
-| ---------------------------- | -------------------------------------------------------------------------------------- |
-| `to="/x"`                    | `href="/x"`                                                                            |
-| `scroll={false}`             | Click handler that calls `useRouter().push(href, { scroll: false })`                   |
-| `unstable_pending={node}`    | Wrap the `<a>` in `<Pending fallback={node}>`                                          |
-| `unstable_notPending={node}` | No direct equivalent yet — render conditionally based on `useRouter().unstable_events` |
-| `unstable_prefetchOnEnter`   | `onMouseEnter={() => useRouter().prefetch(href)}` in a client component                |
-| `unstable_prefetchOnView`    | `IntersectionObserver` + `useRouter().prefetch(href)`                                  |
-| `unstable_startTransition`   | Not needed — the router uses `useTransition` internally                                |
+### `<Link>…<Consumer/></Link>` (navigation status)
 
-Example for prefetch-on-hover:
+Unchanged — a descendant reads the enclosing `<Link>`'s status via the no-arg hook, exactly as in `waku/router`:
 
-```tsx
-'use client';
-import { useRouter } from 'waku-navigation';
+```diff
+- import { Link, useNavigationStatus_UNSTABLE } from 'waku/router/client';
++ import { Link, useNavigationStatus_UNSTABLE } from 'waku-navigation';
 
-export function PrefetchLink({
-  to,
-  children,
-}: {
-  to: string;
-  children: ReactNode;
-}) {
-  const { prefetch } = useRouter();
-  return (
-    <a href={to} onMouseEnter={() => prefetch(to)}>
-      {children}
-    </a>
-  );
-}
+  function NavSpinner() {
+    const { pending } = useNavigationStatus_UNSTABLE();
+    return pending ? <span>…</span> : null;
+  }
+
+  <Link to="/slow">Slow <NavSpinner /></Link>
 ```
 
 ### `<Slice>`
@@ -222,7 +258,6 @@ import {
   unstable_removeBase,
   unstable_RouterContext,
   unstable_parseRoute,
-  unstable_getHttpStatusFromMeta,
 } from 'waku/router/client';
 ```
 
@@ -239,16 +274,17 @@ 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 lists the element IDs we already have so the server can skip re-rendering shared layouts/slices.
-- **HMR cache invalidation** — when Waku's dev runtime fires `globalThis.__WAKU_RSC_RELOAD_LISTENERS__` (Vite HMR update), the router clears `staticPathSet` and `cachedIdSet` and refetches the current route. Guarded by `import.meta.hot` so it's stripped in production.
+- **`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.
+- **HMR cache invalidation** — when Waku's dev runtime fires `globalThis.__WAKU_RSC_RELOAD_LISTENERS__` (Vite HMR update), the router clears `staticPathSet` and `cachedEtags` and refetches the current route. Guarded by `import.meta.hot` so it's stripped in production.
 
 ---
 
 ## Caveats / not yet implemented
 
-- `<Link>` is not provided. Plain `<a>` covers the same default behavior; the `unstable_*` Link niceties (`unstable_notPending`, custom `unstable_startTransition`) need a small client component if you want them.
+- `<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,11 +1,51 @@
-import { type ReactNode } from 'react';
-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;
     query: string;
     hash: string;
 };
+type NavigationStatus = {
+    pending?: boolean;
+};
+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;
 };
@@ -13,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;
@@ -25,8 +70,8 @@ export declare function useRouter(): {
     prefetch: (to: string) => void;
     unstable_events: RouteChangeEvents;
 };
-export declare function Pending({ fallback, children, }: {
-    fallback: ReactNode;
-    children: ReactNode;
-}): import("react/jsx-runtime").JSX.Element;
-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

@@ -1,21 +1,98 @@
 /// <reference types="dom-navigation" />
 'use client';
-import { Fragment as _Fragment, jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
-import { Children, cloneElement, createContext, isValidElement, useCallback, useContext, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, useTransition, } from 'react';
+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_getHttpStatusFromMeta as getHttpStatusFromMeta, 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';
-const PENDING_ATTR = 'data-waku-pending';
+// Mirrors waku's unexported ETAG_ID_PREFIX (router/common.js).
+const ETAG_ID_PREFIX = 'ETAG:';
 const noopRegister = () => () => { };
-const PendingRegistryContext = createContext({
+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);
@@ -45,71 +122,73 @@ export function useRouter() {
         unstable_events: ((_b = ctx === null || ctx === void 0 ? void 0 : ctx.routeChangeEvents) !== null && _b !== void 0 ? _b : noopEvents),
     };
 }
-export function Pending({ fallback, children, }) {
-    const [isPending, startTransition] = useTransition();
-    const { register } = useContext(PendingRegistryContext);
-    const id = useId();
-    const stamped = Children.map(children, (child) => {
-        if (isValidElement(child) && child.type === 'a') {
-            return cloneElement(child, {
-                [PENDING_ATTR]: id,
-            });
-        }
-        return child;
-    });
-    // Capture the wrapped <a>'s href so that programmatic / back-forward
-    // navigations (which have no event.sourceElement) can still find their
-    // Pending by matching the destination path.
-    const href = Children.toArray(children)
-        .map((child) => {
-        if (isValidElement(child) && child.type === 'a') {
-            const { href: h } = child.props;
-            return typeof h === 'string' ? h : undefined;
-        }
-        return undefined;
-    })
-        .find((h) => h !== undefined);
-    useLayoutEffect(() => register(id, { href, startTransition }), [id, href, register, startTransition]);
-    return (_jsxs(_Fragment, { children: [stamped, isPending ? fallback : null] }));
-}
-function InnerRouter({ initialRoute, httpStatus, }) {
+// Same origin + path + query (not pathname; fragment ignored). Malformed input
+// returns false rather than throwing.
+const routeMatchesHref = (href, route) => {
+    let url;
+    try {
+        url = new URL(href, window.location.href);
+    }
+    catch (_a) {
+        return false;
+    }
+    if (url.origin !== window.location.origin)
+        return false;
+    const parsed = parseRoute(url);
+    return parsed.path === route.path && parsed.query === route.query;
+};
+function InnerRouter({ fallbackRoute }) {
     const refetch = useRefetch();
-    // Waku's INTERNAL_ServerRouter renders the SSR tree with hash: '' (URL
-    // fragments aren't sent to the server), so we mirror that to keep the
-    // first client render in sync, then upgrade to the real hash post-hydration.
-    const [route, setRoute] = useState(() => ({
-        ...initialRoute,
-        hash: '',
-    }));
-    // 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.
+    const elementsPromise = useElementsPromise();
+    const [routeState, setRoute] = useState();
+    let route = routeState;
+    if (route === undefined) {
+        // 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 =
+            routeData && routeData[0] !== fallbackRoute.path
+                ? { path: routeData[0], query: routeData[1], hash: '' }
+                : { ...fallbackRoute, hash: '' };
+        setRoute(route);
+    }
+    // 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(() => {
-        if (initialRoute.hash) {
+        // 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: initialRoute.hash }));
+            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 cachedIdSetRef = useRef(new Set());
-    // 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.
+    const cachedEtagsRef = useRef({});
+    // Stable instance: <Slice> mutates this Set across renders.
     const fetchingSlices = useMemo(() => new Set(), []);
-    const elementsPromise = useElementsPromise();
     useEffect(() => {
         elementsPromise.then((elements) => {
             const routeData = elements[ROUTE_ID];
             if (routeData && elements[IS_STATIC_ID]) {
                 staticPathSetRef.current.add(routeData[0]);
             }
-            cachedIdSetRef.current = new Set(Object.keys(elements).filter((k) => !k.startsWith('_') && k !== ROUTE_ID && k !== IS_STATIC_ID));
+            const etags = {};
+            for (const [key, value] of Object.entries(elements)) {
+                // Skip empty (clear signal) and non-Latin1 (breaks the fetch header).
+                if (key.startsWith(ETAG_ID_PREFIX) &&
+                    typeof value === 'string' &&
+                    /^[ -ÿ]+$/.test(value)) {
+                    etags[key.slice(ETAG_ID_PREFIX.length)] = value;
+                }
+            }
+            cachedEtagsRef.current = etags;
         }, () => { });
     }, [elementsPromise]);
     const register = useCallback((id, entry) => {
@@ -118,16 +197,15 @@ function InnerRouter({ initialRoute, httpStatus, }) {
             registryRef.current.delete(id);
         };
     }, []);
-    // Adds the X-Waku-Router-Skip header listing element ids we already have,
-    // so the server can skip re-rendering them. 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([...cachedIdSetRef.current]));
+        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);
@@ -153,28 +231,24 @@ function InnerRouter({ initialRoute, httpStatus, }) {
             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)
             return;
         const refetchRoute = () => {
             staticPathSetRef.current.clear();
-            cachedIdSetRef.current.clear();
+            cachedEtagsRef.current = {};
             refetch(encodeRoutePath(route.path), getRscParams(route.query));
         };
         const listeners = ((_a = globalThis).__WAKU_RSC_RELOAD_LISTENERS__ || (_a.__WAKU_RSC_RELOAD_LISTENERS__ = []));
@@ -192,20 +266,29 @@ function InnerRouter({ initialRoute, httpStatus, }) {
                 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({
@@ -224,31 +307,25 @@ function InnerRouter({ initialRoute, httpStatus, }) {
             }
             emitRouteEvent('start', nextRoute);
             const signal = event.signal;
-            const source = event
-                .sourceElement;
-            const id = (_c = (_b = (_a = source === null || source === void 0 ? void 0 : source.closest) === null || _a === void 0 ? void 0 : _a.call(source, `a[${PENDING_ATTR}]`)) === null || _b === void 0 ? void 0 : _b.getAttribute(PENDING_ATTR)) !== null && _c !== void 0 ? _c : null;
-            // Prefer the source-element match (most precise: tied to the actual
-            // clicked <a>). For programmatic push/replace and browser back/forward
-            // there's no sourceElement, so fall back to any <Pending> whose
-            // wrapped <a>'s href resolves to this destination path.
-            let registered = id ? registryRef.current.get(id) : undefined;
-            if (!registered) {
-                for (const entry of registryRef.current.values()) {
-                    if (entry.href !== undefined &&
-                        new URL(entry.href, window.location.href).pathname ===
-                            nextRoute.path) {
-                        registered = entry;
-                        break;
-                    }
-                }
-            }
-            const startTransition = (_d = registered === null || registered === void 0 ? void 0 : registered.startTransition) !== null && _d !== void 0 ? _d : ((fn) => fn());
+            // 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) => {
+                    // 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 () => {
                         var _a;
                         try {
+                            for (const set of pendingSetters)
+                                set({ pending: true });
                             let targetRoute = nextRoute;
                             try {
                                 if (!staticPathSetRef.current.has(nextRoute.path)) {
@@ -273,8 +350,18 @@ function InnerRouter({ initialRoute, httpStatus, }) {
                                     throw err;
                                 }
                             }
-                            setRenderError(null);
-                            setRoute(targetRoute);
+                            // 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();
                         }
@@ -290,9 +377,8 @@ function InnerRouter({ initialRoute, httpStatus, }) {
             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`);
     };
@@ -303,13 +389,13 @@ function InnerRouter({ initialRoute, httpStatus, }) {
         routeChangeEvents,
         fetchingSlices,
     }), [route, prefetchRoute, routeChangeEvents, fetchingSlices]);
-    return (_jsx(RouterContext.Provider, { value: routerCtxValue, children: _jsx(PendingRegistryContext.Provider, { value: { register }, children: _jsxs(Slot, { id: "root", children: [_jsx("meta", { name: "httpstatus", content: httpStatus }), _jsx(Slot, { id: getRouteSlotId(route.path) })] }) }) }));
+    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 httpStatus = getHttpStatusFromMeta();
-    const parsed = parseRoute(new URL(window.navigation.currentEntry.url));
-    const initialRoute = httpStatus === '404'
-        ? { path: NOT_FOUND_PATH, query: '', hash: '' }
-        : parsed;
-    return (_jsx(Root, { initialRscPath: encodeRoutePath(initialRoute.path), children: _jsx(InnerRouter, { initialRoute: initialRoute, httpStatus: httpStatus }) }));
+    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 { Pending, Router, Slice, 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 { Pending, Router, Slice, 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.2",
+  "version": "0.0.4",
   "type": "module",
   "author": "Daishi Kato",
   "repository": {
@@ -30,36 +30,36 @@
   },
   "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",
-    "waku": "1.0.0-beta.0",
+    "typescript-eslint": "^8.61.1",
+    "vite": "^8.0.16",
+    "vitest": "^4.1.9",
+    "waku": "1.0.0-beta.3",
     "waku-navigation": "link:"
   },
   "peerDependencies": {
     "react": ">=19.0.0",
-    "waku": ">=1.0.0-alpha.10"
+    "waku": ">=1.0.0-beta.3"
   },
   "scripts": {
     "compile": "rm -rf dist && tsc -p .",