waku-navigation 0.0.2 → 0.0.3

package/README.md

@@ -39,7 +39,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` — `useNavigationStatus_UNSTABLE` pending indicators on plain `<a>` for slow routes, client-suspense settling
 
 ---
 
@@ -53,7 +53,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 +84,57 @@ 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>`
+### `useNavigationStatus_UNSTABLE({ href?, dataNavKey? })`
+
+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:
+
+```tsx
+'use client';
+import { useNavigationStatus_UNSTABLE } 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;
+}
+
+// (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;
+}
+```
 
 ```tsx
-import { Pending } from 'waku-navigation';
+<a href="/slow">Slow <NavSpinner href="/slow" /></a>
 
-<Pending fallback={<Spinner />}>
-  <a href="/slow">Go slow</a>
-</Pending>;
+<a href="/slow" data-nav-key="slow">Slow <IdSpinner dataNavKey="slow" /></a>
 ```
 
-`<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 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.
+
+The two match modes:
 
-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.
+- **`{ 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:
 
-`<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.
+  ```tsx
+  'use client';
+  function SlowLink() {
+    const dataNavKey = useId();
+    return (
+      <a href="/slow" data-nav-key={dataNavKey}>
+        Slow <IdSpinner dataNavKey={dataNavKey} />
+      </a>
+    );
+  }
+  ```
+
+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>`).
+
+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`.
+
+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.
 
 ### `<Slice>`
 
@@ -126,23 +162,25 @@ import { Slice } from 'waku-navigation';
 
 ### `<Link>` → 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:
+
 ```diff
 - import { Link } from 'waku/router/client';
 - <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:
+Specific `<Link>` props translate as follows:
 
-| `<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>` 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:
 
@@ -166,6 +204,27 @@ export function PrefetchLink({
 }
 ```
 
+### `<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>`:
+
+```diff
+- import { Link, useNavigationStatus_UNSTABLE } from 'waku/router/client';
++ import { useNavigationStatus_UNSTABLE } from 'waku-navigation';
+
+- function NavSpinner() {
+-   const { pending } = useNavigationStatus_UNSTABLE();
++ function NavSpinner({ href }: { href: string }) {
++   const { pending } = useNavigationStatus_UNSTABLE({ href });
+    return pending ? <span>…</span> : null;
+  }
+
+- <Link to="/slow">Slow <NavSpinner /></Link>
++ <a href="/slow">Slow <NavSpinner href="/slow" /></a>
+```
+
+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.
@@ -222,7 +281,6 @@ import {
   unstable_removeBase,
   unstable_RouterContext,
   unstable_parseRoute,
-  unstable_getHttpStatusFromMeta,
 } from 'waku/router/client';
 ```
 
@@ -241,14 +299,14 @@ These are all handled inside the navigate-event listener so apps usually don't n
 - **Abort during transition** — `event.signal` is checked between async steps so a fast-clicked second navigation cleanly cancels the first without committing stale state.
 - **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.
+- 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)`.
 - `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,3 @@
-import { type ReactNode } from 'react';
 import { Slice } from 'waku/router/client';
 export { Slice };
 type Route = {
@@ -6,6 +5,16 @@ type Route = {
     query: string;
     hash: string;
 };
+type NavigationStatus = {
+    pending?: boolean;
+};
+type NavStatusMatch = {
+    href: string;
+    dataNavKey?: string;
+} | {
+    href?: string;
+    dataNavKey: string;
+};
 type PushReplaceOptions = {
     scroll?: boolean;
 };
@@ -25,8 +34,6 @@ 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;
+declare function useNavigationStatus({ href, dataNavKey, }: NavStatusMatch): NavigationStatus;
+export { useNavigationStatus as useNavigationStatus_UNSTABLE };
 export declare function Router(): import("react/jsx-runtime").JSX.Element;

package/dist/client.js

@@ -1,18 +1,27 @@
 /// <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';
+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.
 export { Slice };
 const NOT_FOUND_PATH = '/404';
-const PENDING_ATTR = 'data-waku-pending';
+// 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.
+const ETAG_ID_PREFIX = 'ETAG:';
 const noopRegister = () => () => { };
-const PendingRegistryContext = createContext({
+const NavStatusRegistryContext = createContext({
     register: noopRegister,
 });
 const noopEvents = { on: () => { }, off: () => { } };
@@ -45,42 +54,71 @@ 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);
+// 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();
-    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] }));
+    useLayoutEffect(() => register(id, { href, dataNavKey, setOptimisticStatus }), [id, href, dataNavKey, register, setOptimisticStatus]);
+    return status;
 }
-function InnerRouter({ initialRoute, httpStatus, }) {
+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.
+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: '',
-    }));
+    const elementsPromise = useElementsPromise();
+    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.
+        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);
+    }
     // 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.
@@ -88,28 +126,36 @@ function InnerRouter({ initialRoute, httpStatus, }) {
     if (renderError)
         throw renderError;
     useEffect(() => {
-        if (initialRoute.hash) {
+        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());
+    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.
     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)) {
+                // Drop empty (clear signal) and non-Latin1 (breaks fetch) tags.
+                if (key.startsWith(ETAG_ID_PREFIX) &&
+                    typeof value === 'string' &&
+                    /^[\u0020-\u00ff]+$/.test(value)) {
+                    etags[key.slice(ETAG_ID_PREFIX.length)] = value;
+                }
+            }
+            cachedEtagsRef.current = etags;
         }, () => { });
     }, [elementsPromise]);
     const register = useCallback((id, entry) => {
@@ -118,11 +164,12 @@ 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.
+    // 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.
     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
@@ -174,7 +221,7 @@ function InnerRouter({ initialRoute, httpStatus, }) {
             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__ = []));
@@ -187,7 +234,7 @@ function InnerRouter({ initialRoute, httpStatus, }) {
     }, [route, refetch, getRscParams]);
     useEffect(() => {
         const callback = (event) => {
-            var _a, _b, _c, _d;
+            var _a, _b, _c;
             if (!event.canIntercept)
                 return;
             if (event.downloadRequest !== null || event.formData)
@@ -226,29 +273,40 @@ function InnerRouter({ initialRoute, httpStatus, }) {
             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;
+            // 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 startTransition = (_d = registered === null || registered === void 0 ? void 0 : registered.startTransition) !== null && _d !== void 0 ? _d : ((fn) => fn());
+            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);
+            }
             event.intercept({
                 ...(suppressScroll ? { scroll: 'manual' } : {}),
                 handler: () => new Promise((resolve, reject) => {
+                    // Always a transition: it 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 +331,15 @@ function InnerRouter({ initialRoute, httpStatus, }) {
                                     throw err;
                                 }
                             }
-                            setRenderError(null);
-                            setRoute(targetRoute);
+                            // 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(() => {
+                                setRenderError(null);
+                                setRoute(targetRoute);
+                            });
                             emitRouteEvent('complete', targetRoute);
                             resolve();
                         }
@@ -303,13 +368,9 @@ 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) }) }) }) }));
 }
 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 @@
-export { Pending, Router, Slice, useRouter } from './client.js';
+export { Router, Slice, useNavigationStatus_UNSTABLE, useRouter, } from './client.js';

package/dist/index.js

@@ -1 +1 @@
-export { Pending, Router, Slice, useRouter } from './client.js';
+export { 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.3",
   "type": "module",
   "author": "Daishi Kato",
   "repository": {
@@ -54,12 +54,12 @@
     "typescript-eslint": "^8.59.3",
     "vite": "^8.0.12",
     "vitest": "^4.1.6",
-    "waku": "1.0.0-beta.0",
+    "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 .",