waku-navigation 0.0.1 → 0.0.2

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,228 @@ 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` — `<Pending>` 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`, 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`.
+
+### `<Pending>`
+
+```tsx
+import { Pending } from 'waku-navigation';
+
+<Pending fallback={<Spinner />}>
+  <a href="/slow">Go slow</a>
+</Pending>;
+```
+
+`<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.
+
+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.
+
+`<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.
+
+### `<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>`
+
+```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:
+
+| `<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                                |
+
+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>
+  );
+}
+```
+
+### `<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,
+  unstable_getHttpStatusFromMeta,
+} 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 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.
+
+---
+
+## 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.
+- `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,32 @@
+import { type ReactNode } from 'react';
+import { Slice } from 'waku/router/client';
+export { Slice };
+type Route = {
+    path: string;
+    query: string;
+    hash: 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;
+};
+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;

package/dist/client.js

@@ -1,30 +1,315 @@
 /// <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';
+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 { 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.
+export { Slice };
+const NOT_FOUND_PATH = '/404';
+const PENDING_ATTR = 'data-waku-pending';
+const noopRegister = () => () => { };
+const PendingRegistryContext = 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),
+    };
+}
+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, }) {
     const refetch = useRefetch();
-    const [routePath, setRoutePath] = useState(initialRoute.path);
+    // 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 [renderError, setRenderError] = useState(null);
+    if (renderError)
+        throw renderError;
+    useEffect(() => {
+        if (initialRoute.hash) {
+            // eslint-disable-next-line react-hooks/set-state-in-effect
+            setRoute((r) => ({ ...r, hash: initialRoute.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 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));
+        }, () => { });
+    }, [elementsPromise]);
+    const register = useCallback((id, entry) => {
+        registryRef.current.set(id, entry);
+        return () => {
+            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.
+    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]));
+        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();
+            cachedIdSetRef.current.clear();
+            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, _d;
+            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;
+            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());
+            event.intercept({
+                ...(suppressScroll ? { scroll: 'manual' } : {}),
+                handler: () => new Promise((resolve, reject) => {
+                    startTransition(async () => {
+                        var _a;
+                        try {
+                            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;
+                                }
+                            }
+                            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(PendingRegistryContext.Provider, { value: { register }, children: _jsxs(Slot, { id: "root", children: [_jsx("meta", { name: "httpstatus", content: httpStatus }), _jsx(Slot, { id: getRouteSlotId(route.path) })] }) }) }));
 }
 export function Router() {
-    const initialRoute = parseRoute(new URL(window.navigation.currentEntry.url));
     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 }) }));
 }

package/dist/index.d.ts

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

package/dist/index.js

@@ -1 +1 @@
-export { Router } from './client.js';
+export { Pending, Router, Slice, 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.2",
   "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.0",
     "waku-navigation": "link:"
   },
   "peerDependencies": {
     "react": ">=19.0.0",
-    "waku": ">=1.0.0-alpha.1"
+    "waku": ">=1.0.0-alpha.10"
+  },
+  "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)"
   }
-}
+}