waku-navigation 0.0.1 → 0.0.3

package/README.md

@@ -1,6 +1,10 @@
 # waku-navigation
 
-Experimental Waku Router implementation with Navigation API
+A drop-in replacement for `waku/router/client` built on the [Navigation API](https://developer.mozilla.org/docs/Web/API/Navigation_API) instead of the History API.
+
+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.
+
+> **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
 
@@ -8,9 +12,9 @@ Experimental Waku Router implementation with Navigation API
 npm install waku-navigation
 ```
 
-## Usage
+## Quick start
 
-Create this file as `./src/waku.client.tsx`:
+Create `./src/waku.client.tsx`:
 
 ```tsx
 import { StrictMode } from 'react';
@@ -23,9 +27,286 @@ const rootElement = (
   </StrictMode>
 );
 
-if ((globalThis as any).__WAKU_HYDRATE__) {
+if ((globalThis as Record<string, unknown>).__WAKU_HYDRATE__) {
   hydrateRoot(document, rootElement);
 } else {
-  createRoot(document as any).render(rootElement);
+  createRoot(document).render(rootElement);
+}
+```
+
+Pages and `pages/_slices/*` work exactly as in any Waku app — `waku-navigation` only replaces the client-side router.
+
+## 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
+
+---
+
+## API reference
+
+### `<Router>`
+
+```tsx
+import { Router } from 'waku-navigation';
+
+<Router />;
+```
+
+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()`
+
+Same shape as `waku/router/client`'s `useRouter`:
+
+```tsx
+import { useRouter } from 'waku-navigation';
+
+function Nav() {
+  const router = useRouter();
+  // router.path     -- current pathname (no leading base)
+  // router.query    -- query string (no leading '?')
+  // router.hash     -- '#section' or ''
+  // router.push(to, { scroll? })
+  // router.replace(to, { scroll? })
+  // router.reload()
+  // router.back()
+  // router.forward()
+  // router.prefetch(to)
+  // router.unstable_events.on('start' | 'complete', handler)
+  // router.unstable_events.off('start' | 'complete', handler)
 }
 ```
+
+Notes:
+
+- `push`/`replace` return `navigation.navigate(...).finished` (a promise that resolves when the navigation commits or rejects on abort).
+- `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? })`
+
+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
+<a href="/slow">Slow <NavSpinner href="/slow" /></a>
+
+<a href="/slow" data-nav-key="slow">Slow <IdSpinner dataNavKey="slow" /></a>
+```
+
+`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:
+
+- **`{ 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';
+  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>`
+
+```tsx
+import { Slice } from 'waku-navigation';
+
+<Slice id="clock" />
+<Slice id="banner" lazy fallback={<div>Loading…</div>} />
+```
+
+`Slice` is re-exported from `waku/router/client` unchanged. It works because our `<Router>` provides the same `unstable_RouterContext` shape Waku's `<Slice>` expects (the `fetchingSlices` set and `useElementsPromise`).
+
+---
+
+## Migration from `waku/router/client`
+
+### Drop-in: `<Router>` and `useRouter`
+
+```diff
+- import { Router, useRouter } from 'waku/router/client';
++ import { Router, useRouter } 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>`
+
+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>
+```
+
+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';
+
+export function PrefetchLink({
+  to,
+  children,
+}: {
+  to: string;
+  children: ReactNode;
+}) {
+  const { prefetch } = useRouter();
+  return (
+    <a href={to} onMouseEnter={() => prefetch(to)}>
+      {children}
+    </a>
+  );
+}
+```
+
+### `<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.
+
+### `ErrorBoundary` → your own
+
+`waku-navigation` does not ship an error boundary; any standard React error boundary works. Place it around `<Router>`:
+
+```tsx
+<ErrorBoundary>
+  <Router />
+</ErrorBoundary>
+```
+
+Non-404 refetch failures (network errors, server 5xx) are rethrown during render and bubble to the nearest boundary. 404s are handled internally — the router refetches `/404` and renders that route's tree, so you keep using your `pages/404.tsx` (with `getConfig` returning a `404` http status) the same as before.
+
+### `unstable_events`
+
+Same shape as in `waku/router/client`:
+
+```tsx
+const { unstable_events } = useRouter();
+
+useEffect(() => {
+  const onStart = (route) => console.log('start', route.path);
+  const onComplete = (route) => console.log('complete', route.path);
+  unstable_events.on('start', onStart);
+  unstable_events.on('complete', onComplete);
+  return () => {
+    unstable_events.off('start', onStart);
+    unstable_events.off('complete', onComplete);
+  };
+}, [unstable_events]);
+```
+
+`'start'` fires before the refetch; `'complete'` fires after `setRoute` inside the transition. Hash-only navigations fire both back-to-back.
+
+### Lower-level `unstable_*` exports
+
+These are unchanged primitives — keep importing them from `waku/router/client` directly:
+
+```ts
+import {
+  unstable_HAS404_ID,
+  unstable_IS_STATIC_ID,
+  unstable_ROUTE_ID,
+  unstable_SKIP_HEADER,
+  unstable_encodeRoutePath,
+  unstable_encodeSliceId,
+  unstable_getRouteSlotId,
+  unstable_getSliceSlotId,
+  unstable_getErrorInfo,
+  unstable_addBase,
+  unstable_removeBase,
+  unstable_RouterContext,
+  unstable_parseRoute,
+} from 'waku/router/client';
+```
+
+Internally `waku-navigation` uses these to interop with Waku's RSC store, slot IDs, and error metadata.
+
+---
+
+## What the router does for you
+
+These are all handled inside the navigate-event listener so apps usually don't need to think about them:
+
+- **Same-origin guard** — cross-origin navigations have `canIntercept: false` and are passed through to the browser.
+- **Download guard** — `<a download>` clicks (`event.downloadRequest !== null`) are passed through, so the browser issues the download instead of an RSC fetch.
+- **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.
+- **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.
+- **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
+
+- 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 +1,39 @@
+import { Slice } from 'waku/router/client';
+export { Slice };
+type Route = {
+    path: string;
+    query: string;
+    hash: string;
+};
+type NavigationStatus = {
+    pending?: boolean;
+};
+type NavStatusMatch = {
+    href: string;
+    dataNavKey?: string;
+} | {
+    href?: string;
+    dataNavKey: string;
+};
+type PushReplaceOptions = {
+    scroll?: boolean;
+};
+type RouteChangeEvents = {
+    on: (name: 'start' | 'complete', handler: (route: Route) => void) => void;
+    off: (name: 'start' | 'complete', handler: (route: Route) => void) => void;
+};
+export declare function useRouter(): {
+    path: string;
+    query: string;
+    hash: string;
+    push: (to: string, options?: PushReplaceOptions) => Promise<NavigationHistoryEntry> | undefined;
+    replace: (to: string, options?: PushReplaceOptions) => Promise<NavigationHistoryEntry> | undefined;
+    reload: () => Promise<NavigationHistoryEntry> | undefined;
+    back: () => void;
+    forward: () => void;
+    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;

package/dist/client.js

@@ -1,30 +1,376 @@
 /// <reference types="dom-navigation" />
 'use client';
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useState } from 'react';
-import { Root, Slot, useRefetch } from 'waku/minimal/client';
-import { unstable_encodeRoutePath as encodeRoutePath, unstable_getHttpStatusFromMeta as getHttpStatusFromMeta, unstable_parseRoute as parseRoute, unstable_getRouteSlotId as getRouteSlotId, } from 'waku/router/client';
-function InnerRouter({ initialRoute, httpStatus, }) {
+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.
+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.
+const ETAG_ID_PREFIX = 'ETAG:';
+const noopRegister = () => () => { };
+const NavStatusRegistryContext = createContext({
+    register: noopRegister,
+});
+const noopEvents = { on: () => { }, off: () => { } };
+export function useRouter() {
+    var _a, _b;
+    const ctx = useContext(RouterContext);
+    const route = (_a = ctx === null || ctx === void 0 ? void 0 : ctx.route) !== null && _a !== void 0 ? _a : { path: '/', query: '', hash: '' };
+    return {
+        path: route.path,
+        query: route.query,
+        hash: route.hash,
+        push: (to, options) => window.navigation.navigate(to, {
+            history: 'push',
+            info: { scroll: options === null || options === void 0 ? void 0 : options.scroll },
+        }).finished,
+        replace: (to, options) => window.navigation.navigate(to, {
+            history: 'replace',
+            info: { scroll: options === null || options === void 0 ? void 0 : options.scroll },
+        }).finished,
+        reload: () => window.navigation.reload().finished,
+        back: () => {
+            window.navigation.back();
+        },
+        forward: () => {
+            window.navigation.forward();
+        },
+        prefetch: (to) => {
+            ctx === null || ctx === void 0 ? void 0 : ctx.prefetchRoute(parseRoute(new URL(to, window.location.href)));
+        },
+        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.
+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();
-    const [routePath, setRoutePath] = useState(initialRoute.path);
+    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.
+    const [renderError, setRenderError] = useState(null);
+    if (renderError)
+        throw renderError;
+    useEffect(() => {
+        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.
+    const fetchingSlices = useMemo(() => new Set(), []);
+    useEffect(() => {
+        elementsPromise.then((elements) => {
+            const routeData = elements[ROUTE_ID];
+            if (routeData && elements[IS_STATIC_ID]) {
+                staticPathSetRef.current.add(routeData[0]);
+            }
+            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) => {
+        registryRef.current.set(id, entry);
+        return () => {
+            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.
+    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.
+    const rscParamsByQueryRef = useRef(new Map());
+    const getRscParams = useCallback((query) => {
+        let params = rscParamsByQueryRef.current.get(query);
+        if (!params) {
+            params = new URLSearchParams({ query });
+            rscParamsByQueryRef.current.set(query, params);
+        }
+        return params;
+    }, []);
+    const routeChangeListeners = useMemo(() => ({
+        start: new Set(),
+        complete: new Set(),
+    }), []);
+    const emitRouteEvent = useCallback((name, r) => {
+        for (const listener of routeChangeListeners[name])
+            listener(r);
+    }, [routeChangeListeners]);
+    const routeChangeEvents = useMemo(() => ({
+        on: (name, handler) => {
+            routeChangeListeners[name].add(handler);
+        },
+        off: (name, handler) => {
+            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);
+        (_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.
+    useEffect(() => {
+        var _a;
+        if (!import.meta.hot)
+            return;
+        const refetchRoute = () => {
+            staticPathSetRef.current.clear();
+            cachedEtagsRef.current = {};
+            refetch(encodeRoutePath(route.path), getRscParams(route.query));
+        };
+        const listeners = ((_a = globalThis).__WAKU_RSC_RELOAD_LISTENERS__ || (_a.__WAKU_RSC_RELOAD_LISTENERS__ = []));
+        listeners.unshift(refetchRoute);
+        return () => {
+            const i = listeners.indexOf(refetchRoute);
+            if (i !== -1)
+                listeners.splice(i, 1);
+        };
+    }, [route, refetch, getRscParams]);
     useEffect(() => {
         const callback = (event) => {
-            // TODO: check if it's an external navigation
-            event.intercept();
-            const route = parseRoute(new URL(event.destination.url));
-            const rscPath = encodeRoutePath(route.path);
-            refetch(rscPath);
-            setRoutePath(route.path);
+            var _a, _b, _c;
+            if (!event.canIntercept)
+                return;
+            if (event.downloadRequest !== null || event.formData)
+                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.
+            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.
+                emitRouteEvent('start', nextRoute);
+                if (suppressScroll) {
+                    event.intercept({
+                        scroll: 'manual',
+                        handler: async () => {
+                            setRoute(nextRoute);
+                            emitRouteEvent('complete', nextRoute);
+                        },
+                    });
+                }
+                else {
+                    setRoute(nextRoute);
+                    emitRouteEvent('complete', nextRoute);
+                }
+                return;
+            }
+            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);
+            }
+            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)) {
+                                    await refetch(encodeRoutePath(nextRoute.path), getRscParams(nextRoute.query), enhanceFetchWithSkip);
+                                }
+                                if (signal.aborted)
+                                    return resolve();
+                            }
+                            catch (err) {
+                                if (signal.aborted)
+                                    return resolve();
+                                if (((_a = getErrorInfo(err)) === null || _a === void 0 ? void 0 : _a.status) === 404) {
+                                    if (!staticPathSetRef.current.has(NOT_FOUND_PATH)) {
+                                        await refetch(encodeRoutePath(NOT_FOUND_PATH), getRscParams(''), enhanceFetchWithSkip);
+                                    }
+                                    if (signal.aborted)
+                                        return resolve();
+                                    targetRoute = { path: NOT_FOUND_PATH, query: '', hash: '' };
+                                }
+                                else {
+                                    setRenderError(err);
+                                    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(() => {
+                                setRenderError(null);
+                                setRoute(targetRoute);
+                            });
+                            emitRouteEvent('complete', targetRoute);
+                            resolve();
+                        }
+                        catch (err) {
+                            reject(err);
+                        }
+                    });
+                }),
+            });
         };
         window.navigation.addEventListener('navigate', callback);
         return () => {
             window.navigation.removeEventListener('navigate', callback);
         };
-    }, [refetch]);
-    return (_jsxs(Slot, { id: "root", children: [_jsx("meta", { name: "httpstatus", content: httpStatus }), _jsx(Slot, { id: getRouteSlotId(routePath) })] }));
+    }, [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.
+    const notAvailable = (name) => () => {
+        throw new Error(`${name} is not available in waku-navigation`);
+    };
+    const routerCtxValue = useMemo(() => ({
+        route,
+        changeRoute: notAvailable('changeRoute'),
+        prefetchRoute,
+        routeChangeEvents,
+        fetchingSlices,
+    }), [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) }) }) }) }));
 }
 export function Router() {
     const initialRoute = parseRoute(new URL(window.navigation.currentEntry.url));
-    const httpStatus = getHttpStatusFromMeta();
-    return (_jsx(Root, { initialRscPath: encodeRoutePath(initialRoute.path), children: _jsx(InnerRouter, { initialRoute: initialRoute, httpStatus: httpStatus }) }));
+    return (_jsx(Root, { initialRscPath: encodeRoutePath(initialRoute.path), children: _jsx(InnerRouter, { fallbackRoute: initialRoute }) }));
 }

package/dist/index.d.ts

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

package/dist/index.js

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

package/package.json

@@ -1,9 +1,8 @@
 {
   "name": "waku-navigation",
   "description": "Waku Router implementation with Navigation API",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "type": "module",
-  "packageManager": "pnpm@10.28.0",
   "author": "Daishi Kato",
   "repository": {
     "type": "git",
@@ -20,16 +19,6 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "compile": "rm -rf dist && tsc -p .",
-    "test": "pnpm run '/^test:.*/'",
-    "test:format": "prettier -c .",
-    "test:lint": "eslint .",
-    "test:types": "tsc -p . --noEmit",
-    "test:types:examples": "tsc -p examples --noEmit",
-    "test:spec": "vitest run",
-    "examples:01_minimal": "(cd examples/01_minimal; waku dev)"
-  },
   "keywords": [
     "react",
     "waku",
@@ -40,35 +29,48 @@
     "singleQuote": true
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.2",
+    "@eslint/js": "9.39.4",
+    "@playwright/test": "^1.60.0",
     "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/react": "^16.3.1",
+    "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
-    "@types/dom-navigation": "^1.0.6",
-    "@types/node": "^25.0.6",
-    "@types/react": "^19.2.8",
+    "@types/dom-navigation": "^1.0.7",
+    "@types/node": "^25.7.0",
+    "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "eslint": "^9.39.2",
+    "eslint": "9.39.4",
     "eslint-import-resolver-typescript": "^4.4.4",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-jsx-a11y": "^6.10.2",
     "eslint-plugin-react": "^7.37.5",
-    "eslint-plugin-react-hooks": "^7.0.1",
-    "happy-dom": "^20.1.0",
-    "prettier": "^3.7.4",
-    "react": "^19.2.3",
-    "react-dom": "^19.2.3",
-    "react-server-dom-webpack": "^19.2.3",
+    "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",
     "ts-expect": "^1.3.0",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.52.0",
-    "vite": "^7.3.1",
-    "vitest": "^4.0.16",
-    "waku": "https://pkg.pr.new/wakujs/waku@fc78f84",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.3",
+    "vite": "^8.0.12",
+    "vitest": "^4.1.6",
+    "waku": "1.0.0-beta.3",
     "waku-navigation": "link:"
   },
   "peerDependencies": {
     "react": ">=19.0.0",
-    "waku": ">=1.0.0-alpha.1"
+    "waku": ">=1.0.0-beta.3"
+  },
+  "scripts": {
+    "compile": "rm -rf dist && tsc -p .",
+    "test": "pnpm run '/^test:.*/'",
+    "test:format": "prettier -c .",
+    "test:lint": "eslint .",
+    "test:types": "tsc -p . --noEmit",
+    "test:types:examples": "tsc -p examples --noEmit",
+    "test:types:e2e": "tsc -p tsconfig.e2e.json",
+    "test:spec": "vitest run",
+    "e2e": "pnpm compile && playwright test",
+    "examples:01_minimal": "(cd examples/01_minimal; waku dev)"
   }
-}
+}