@real-router/react 0.24.1 → 0.25.0

package/README.md

@@ -17,13 +17,18 @@ npm install @real-router/react @real-router/core @real-router/browser-plugin
 
 ## Entry Points
 
-| Import Path                 | React Version | Runtime           | Includes                                               |
-| --------------------------- | ------------- | ----------------- | ------------------------------------------------------ |
-| `@real-router/react`        | 19.2+         | DOM               | Full API (hooks, `Link`, `RouteView` with `keepAlive`) |
-| `@real-router/react/legacy` | 18+           | DOM               | All hooks and `Link`, no `RouteView`                   |
-| `@real-router/react/ink`    | 19.2+         | Terminal (Ink 7+) | Hooks, `InkRouterProvider`, `InkLink`, no `RouteView`  |
+| Import Path                        | React Version | Runtime                                | Includes                                                                                                                                                |
+| ---------------------------------- | ------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@real-router/react`               | 19.2+         | DOM                                    | Full client API (hooks, `Link`, `RouteView` with `keepAlive`, `RouterErrorBoundary`). **No SSR-feature components** — those live at `/ssr`.             |
+| `@real-router/react/ssr`           | 19.2+         | DOM (SSR-aware)                        | `<ClientOnly>`, `<ServerOnly>`, `<Await>`, `<Streamed>`, `useDeferred`, `<HttpStatusCode>`, `<HttpStatusProvider>`, `createHttpStatusSink` |
+| `@real-router/react/legacy`        | 18+           | DOM                                    | Client API for React 18 (no `RouteView`, no SSR helpers)                                                                                                |
+| `@real-router/react/legacy/ssr`    | 18+           | DOM (SSR-aware)                        | SSR-feature subset for React 18 — same as `/ssr` minus `<Await>` (which depends on React 19's `use(promise)`)                                           |
+| `@real-router/react/ink`           | 19.2+         | Terminal (Ink 7+)                      | Hooks, `InkRouterProvider`, `InkLink` — no `Link`, no `RouteView`, no `announceNavigation`                                                              |
+| `@real-router/react` (`react-server` condition) | 19+ | RSC bundler                            | **Type-only** re-exports for Server Components — no client runtime. Same condition applies to `/ssr` for prop types.                                    |
 
-All entries share the same underlying hook code. `/legacy` excludes React 19.2 `<Activity>`; `/ink` excludes DOM-bound primitives (`<a>`-based `Link`, `announceNavigation`) and replaces them with keyboard-driven terminal equivalents.
+All client entries share the same underlying hook code. `/legacy` excludes React 19.2 `<Activity>`; `/ink` excludes DOM-bound primitives (`<a>`-based `Link`, `announceNavigation`) and replaces them with keyboard-driven terminal equivalents. The `/ssr` split keeps server-only prop types out of the client TypeScript context for apps that don't touch SSR (bundle cost is ≈ 0 thanks to `"sideEffects": false`).
+
+The root export resolves to a **type-only entry** when bundlers apply the `react-server` condition (Vite RSC, Webpack RSC, Turbopack, Parcel) — Server Components can import public API types without pulling client-only code into the server bundle. Per-request data fetching is handled by [@real-router/rsc-server-plugin](https://www.npmjs.com/package/@real-router/rsc-server-plugin), not this entry. See [RSC Integration wiki guide](https://github.com/greydragon888/real-router/wiki/RSC-Integration).
 
 ## Quick Start
 
@@ -202,6 +207,31 @@ const LazyDashboard = lazy(() => import("./Dashboard"));
 
 `fallback` and `keepAlive` work together — `<Activity>` wraps the whole match including the `<Suspense>` boundary.
 
+#### `RouteView.Self`
+
+Renders when the active route name **exactly equals** the parent `<RouteView>`'s `nodeName`. Use it for leaf views where the parent route itself is the destination — e.g. `/users` rendering a directory page while `/users/:id` renders inside a nested `<RouteView nodeName="users">`.
+
+```tsx
+<RouteView nodeName="users">
+  <RouteView.Self>
+    <UsersIndex /> {/* rendered for route name === "users" */}
+  </RouteView.Self>
+  <RouteView.Match segment="profile">
+    <UserProfile /> {/* rendered for "users.profile" and descendants */}
+  </RouteView.Match>
+  <RouteView.NotFound>
+    <NotFoundPage />
+  </RouteView.NotFound>
+</RouteView>
+```
+
+| Prop       | Type        | Description                                                                                  |
+| ---------- | ----------- | -------------------------------------------------------------------------------------------- |
+| `fallback` | `ReactNode` | Symmetric with `RouteView.Match` — wraps `children` in `<Suspense>` when defined.            |
+| `children` | `ReactNode` | Content to render when the active route name equals the parent `<RouteView>`'s `nodeName`.   |
+
+First-wins: if multiple `<RouteView.Self>` elements appear, only the first contributes to the rendered output (same precedence semantics as `<RouteView.NotFound>`). An activating `<RouteView.Match>` suppresses both `Self` and `NotFound`.
+
 ### `<RouterErrorBoundary>`
 
 Declarative error handling for navigation errors. Shows a fallback **alongside** children (not instead of) when a guard rejects or a route is not found.
@@ -223,6 +253,94 @@ Auto-resets on next successful navigation. Works with both `<Link>` and imperati
 
 Available from both `@real-router/react` and `@real-router/react/legacy`.
 
+### `<ClientOnly>` / `<ServerOnly>`
+
+Paired SSR-aware boundaries. `<ClientOnly>` renders `fallback` on the server (and on the client first paint, to match SSR HTML), then swaps in `children` after mount. `<ServerOnly>` is the symmetric inverse.
+
+```tsx
+import { ClientOnly, ServerOnly } from "@real-router/react/ssr";
+
+<ClientOnly fallback={<Skeleton />}>
+  <BrowserApiWidget />
+</ClientOnly>
+
+<ServerOnly>
+  <SeoMetaStrip />
+</ServerOnly>
+```
+
+Implementation: `useState(false)` + `useEffect(() => setMounted(true), [])`. Server emits the SSR-side branch, client first paint matches it (no hydration mismatch), the post-mount effect triggers a single re-render that swaps the rendered branch.
+
+Available from `@real-router/react/ssr` and `@real-router/react/legacy/ssr`. End-to-end dogfooding lives in [`examples/web/react/ssr-examples/ssr/`](../../examples/web/react/ssr-examples/ssr/) (see `e2e/ssr-boundaries.spec.ts`).
+
+### `<Streamed>` / `<Await>` / `useDeferred`
+
+Three pieces of the deferred-data pipeline (paired with [`@real-router/ssr-data-plugin`](https://www.npmjs.com/package/@real-router/ssr-data-plugin)'s `defer()` API). `<Streamed>` is a cross-adapter alias for `<Suspense>` so route bundles can use the same boundary name across Solid/Vue/Svelte/React. `<Await<T> name="key">` reads the deferred promise the loader published under that key and hands the resolved value to a render-prop. `useDeferred<T>(key)` returns the same promise for callers that want to compose with `use()` or a third-party suspense library.
+
+```tsx
+import { Streamed, Await, useDeferred } from "@real-router/react/ssr";
+
+// Render-prop form — works in React 19.2+ via internal `use(promise)`.
+<Streamed fallback={<Spinner />}>
+  <Await<Review[]> name="reviews">
+    {(reviews) => <ReviewList items={reviews} />}
+  </Await>
+</Streamed>;
+
+// Manual form — works on React 18+ (`/legacy/ssr` entry).
+function Reviews() {
+  const reviews = use(useDeferred<Review[]>("reviews"));
+  return <ReviewList items={reviews} />;
+}
+```
+
+`<Await>` is React 19.2+ only (depends on `use(promise)`); `<Streamed>` and `useDeferred` ship in both `/ssr` and `/legacy/ssr`. End-to-end example: [`examples/web/react/ssr-examples/ssr-streaming/`](../../examples/web/react/ssr-examples/ssr-streaming/).
+
+### `<HttpStatusCode>` / `<HttpStatusProvider>` / `createHttpStatusSink`
+
+Render-time HTTP status declaration for SSR responses. Mount `<HttpStatusCode code={N} />` inside a route component (typical use: a `<RouteView.NotFound>` glob page) — it writes `N` to the nearest `<HttpStatusProvider>`'s sink during render and returns `null`. After `renderToString` / `renderToReadableStream`, read `sink.code` and pass it to your response.
+
+```tsx
+// app.tsx
+import { HttpStatusCode } from "@real-router/react/ssr";
+
+function NotFound() {
+  return (
+    <>
+      <HttpStatusCode code={404} />
+      <h1>Page not found</h1>
+    </>
+  );
+}
+
+// entry-server.tsx
+import { renderToString } from "react-dom/server";
+import {
+  HttpStatusProvider,
+  createHttpStatusSink,
+} from "@real-router/react/ssr";
+
+const sink = createHttpStatusSink();
+const html = renderToString(
+  <HttpStatusProvider sink={sink}>
+    <RouterProvider router={router}>
+      <App />
+    </RouterProvider>
+  </HttpStatusProvider>,
+);
+response.status(sink.code ?? 200).send(html);
+```
+
+| Export                           | Kind      | Purpose                                                                                                                                                  |
+| -------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<HttpStatusCode code={N}/>`     | component | Writes `code` to the optional context sink during render. Last write wins across multiple instances. No-op without a provider.                            |
+| `<HttpStatusProvider sink={…}>`  | component | Supplies an `HttpStatusSink` to descendant `<HttpStatusCode />` via React context.                                                                       |
+| `createHttpStatusSink()`         | utility   | Returns a fresh `{ code: number \| undefined }` sink — construct one per request on the server, read `sink.code` after rendering.                         |
+
+Loader-driven errors (`LoaderNotFound` → 404, `LoaderRedirect` → 30x) keep working as before; this component covers render-time decisions only. **Streaming SSR caveat**: mount `<HttpStatusCode>` in the shell (above every `<Suspense>` that could delay it), or `await stream.allReady` before reading `sink.code` — once the response status flushes, later writes are lost.
+
+Available from `@real-router/react/ssr` and `@real-router/react/legacy/ssr`.
+
 ## React 18 Migration
 
 One import path change — all hooks and `Link` work identically:
@@ -234,6 +352,8 @@ One import path change — all hooks and `Link` work identically:
 
 `RouteView` is not available from `/legacy`. Use `useRouteNode` with a switch/case pattern instead.
 
+`useRouteExit` and `useRouteEnter` are also not available from `/legacy` — they depend on React 19's concurrent-mode scheduling guarantees. Use `router.subscribeLeave()` directly for exit guards, and `useEffect` for mount-time analytics on React 18.
+
 ## Ink (Terminal UI)
 
 `@real-router/react/ink` lets you build terminal apps with the same hooks you use in the browser.
@@ -285,7 +405,7 @@ render(
 );
 ```
 
-**Navigation contract:** Tab moves focus between `InkLink`s, Enter calls `router.navigate(...)`. `RouteView` and the DOM `Link` are intentionally absent from this entry — compose routes with `useRouteNode("")` and a switch.
+**Navigation contract:** Tab moves focus between `InkLink`s, Enter calls `router.navigate(...)`. `RouteView` and the DOM `Link` are intentionally absent from this entry — compose routes with `useRouteNode("")` and a switch. `RouterErrorBoundary` is available for terminal error handling.
 
 **Install:**
 

package/dist/cjs/Await-whr-pcvo.d.ts

@@ -0,0 +1,41 @@
+import { ReactNode } from "react";
+
+//#region src/components/Await.d.ts
+interface AwaitProps<T> {
+  /** Deferred key declared in the loader's `defer({ deferred: { <name>: ... } })`. */
+  readonly name: string;
+  /** Render the resolved value. Suspends while pending; throws inside the
+   * nearest Error Boundary on rejection. */
+  readonly children: (value: T) => ReactNode;
+}
+/**
+ * Ergonomic wrapper around `useDeferred(name)` + React 19's `use(promise)`.
+ *
+ * ```tsx
+ * <Suspense fallback={<Spinner />}>
+ *   <Await<Review[]> name="reviews">
+ *     {(reviews) => <ReviewList items={reviews} />}
+ *   </Await>
+ * </Suspense>
+ * ```
+ *
+ * Equivalent to:
+ *
+ * ```tsx
+ * function Inner() {
+ *   const reviews = use(useDeferred<Review[]>("reviews"));
+ *   return <ReviewList items={reviews} />;
+ * }
+ * ```
+ *
+ * Pick `<Await>` for cross-adapter consistency with the SvelteKit
+ * `{#await}` / Solid `<Await/>` shape; pick the inline `use(useDeferred(...))`
+ * form if you prefer one fewer abstraction.
+ */
+declare function Await<T = unknown>({
+  name,
+  children
+}: AwaitProps<T>): ReactNode;
+//#endregion
+export { AwaitProps as n, Await as t };
+//# sourceMappingURL=Await-whr-pcvo.d.ts.map

package/dist/cjs/Await-whr-pcvo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Await-whr-pcvo.d.ts","names":[],"sources":["../../src/components/Await.tsx"],"mappings":";;;UAMiB,UAAA;;WAEN,IAAA;EAFgB;;EAAA,SAKhB,QAAA,GAAW,KAAA,EAAO,CAAA,KAAM,SAAA;AAAA;;;;;;;;AA2BnC;;;;;;;;;;;;;;;;;iBAAgB,KAAA,aAAA,CAAA;EACd,IAAA;EACA;AAAA,GACC,UAAA,CAAW,CAAA,IAAK,SAAA"}

package/dist/cjs/HttpStatusProvider-Dh6cMr95.d.ts

@@ -0,0 +1,143 @@
+import { ReactNode } from "react";
+
+//#region src/components/ClientOnly.d.ts
+interface ClientOnlyProps {
+  readonly children: ReactNode;
+  readonly fallback?: ReactNode;
+}
+declare function ClientOnly({
+  children,
+  fallback
+}: ClientOnlyProps): ReactNode;
+//#endregion
+//#region src/components/ServerOnly.d.ts
+interface ServerOnlyProps {
+  readonly children: ReactNode;
+  readonly fallback?: ReactNode;
+}
+declare function ServerOnly({
+  children,
+  fallback
+}: ServerOnlyProps): ReactNode;
+//#endregion
+//#region src/components/Streamed.d.ts
+interface StreamedProps {
+  /** Shown while any descendant `use(promise)` / `<Await>` is pending. */
+  readonly fallback: ReactNode;
+  readonly children: ReactNode;
+}
+/**
+ * Cross-adapter alias for `<Suspense fallback={…}>`. Pairs with `<Await>`
+ * for symmetry with `<Streamed>` boundaries in the SvelteKit / Solid
+ * deferred-data conventions.
+ *
+ * ```tsx
+ * <Streamed fallback={<Spinner />}>
+ *   <Await<Review[]> name="reviews">
+ *     {(reviews) => <ReviewList items={reviews} />}
+ *   </Await>
+ * </Streamed>
+ * ```
+ *
+ * The component is a thin wrapper around React's native `<Suspense>` — no
+ * additional behaviour. Use plain `<Suspense>` directly if you don't need
+ * the cross-framework naming alignment.
+ */
+declare function Streamed({
+  fallback,
+  children
+}: StreamedProps): ReactNode;
+//#endregion
+//#region src/components/HttpStatusCode.d.ts
+interface HttpStatusCodeProps {
+  /** HTTP status to apply to the response. Common values: 404, 410, 451, 503. */
+  readonly code: number;
+}
+/**
+ * Render-time HTTP status declaration. Mount inside a route component (typical
+ * use case: a glob `*` route's NotFound page) when the status is decided by
+ * the rendered tree rather than a loader.
+ *
+ * Writes `code` to the nearest `<HttpStatusProvider>`'s sink during render and
+ * returns `null`. With no provider mounted (the standard client-side case)
+ * the component is a silent no-op — same component tree hydrates without
+ * touching the DOM or warning about mismatches.
+ *
+ * Loader-driven errors (`LoaderNotFound` → 404, `LoaderRedirect` → 30x) keep
+ * working as before; this component covers render-time decisions only.
+ *
+ * Last write wins when several `<HttpStatusCode />` instances mount in the
+ * same render pass — sink reflects the last component that ran.
+ *
+ * ```tsx
+ * // entry-server.tsx
+ * import { renderToString } from "react-dom/server";
+ * import { createHttpStatusSink, HttpStatusProvider } from "@real-router/react/ssr";
+ *
+ * const sink = createHttpStatusSink();
+ * const html = renderToString(
+ *   <HttpStatusProvider sink={sink}>
+ *     <RouterProvider router={router}>
+ *       <App />
+ *     </RouterProvider>
+ *   </HttpStatusProvider>,
+ * );
+ * response.status(sink.code ?? 200).send(html);
+ * ```
+ *
+ * **Streaming SSR (`renderToReadableStream`):** the response status MUST be
+ * sent before the first body byte flushes. If `<HttpStatusCode />` is mounted
+ * inside a late-resolving `<Suspense>` boundary, the sink write may happen
+ * AFTER the headers are already on the wire — the override is then lost.
+ * Either mount the component in the shell (above every `<Suspense>` that
+ * could delay it) or `await stream.allReady` before reading `sink.code`
+ * (which forfeits streaming benefits). For non-streaming SSR
+ * (`renderToString`) there is no such ordering concern.
+ *
+ * **Valid `code` range:** Node's `res.end()` throws `Invalid status code` on
+ * `NaN`, `0`, negative values, or values `> 999` — this surfaces as a 5xx /
+ * dropped connection, not silent corruption. Pass a real HTTP status integer
+ * (commonly 4xx/5xx; 100-999 is what Node accepts).
+ */
+declare function HttpStatusCode({
+  code
+}: HttpStatusCodeProps): ReactNode;
+//#endregion
+//#region src/utils/createHttpStatusSink.d.ts
+/**
+ * Render-scoped HTTP status sink. Created per request on the server, passed to
+ * `<HttpStatusProvider sink={...}>`, and read after `renderToString` /
+ * `renderToReadableStream` to apply the value to the HTTP response.
+ *
+ * Last write wins: if the rendered tree mounts more than one
+ * `<HttpStatusCode />`, the value reflects the last component that ran during
+ * the render pass.
+ *
+ * No-op on the client — `<HttpStatusCode />` reads the optional context and
+ * skips the write when no provider is mounted, so the same component tree can
+ * be hydrated without changing behaviour.
+ *
+ * Constraints:
+ * - **Per-request only.** Don't share a sink across requests; the rendered
+ *   tree mutates `code` in place. Module-level singletons leak status
+ *   between concurrent requests.
+ * - **Don't `Object.freeze` the sink.** The component writes to `.code`;
+ *   freezing makes the assignment throw under ESM strict mode.
+ */
+interface HttpStatusSink {
+  code: number | undefined;
+}
+declare function createHttpStatusSink(): HttpStatusSink;
+//#endregion
+//#region src/components/HttpStatusProvider.d.ts
+interface HttpStatusProviderProps {
+  readonly sink: HttpStatusSink;
+  readonly children: ReactNode;
+}
+declare function HttpStatusProvider({
+  sink,
+  children
+}: HttpStatusProviderProps): ReactNode;
+//#endregion
+export { HttpStatusCode as a, StreamedProps as c, ClientOnly as d, ClientOnlyProps as f, createHttpStatusSink as i, ServerOnly as l, HttpStatusProviderProps as n, HttpStatusCodeProps as o, HttpStatusSink as r, Streamed as s, HttpStatusProvider as t, ServerOnlyProps as u };
+//# sourceMappingURL=HttpStatusProvider-Dh6cMr95.d.ts.map

package/dist/cjs/HttpStatusProvider-Dh6cMr95.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpStatusProvider-Dh6cMr95.d.ts","names":[],"sources":["../../src/components/ClientOnly.tsx","../../src/components/ServerOnly.tsx","../../src/components/Streamed.tsx","../../src/components/HttpStatusCode.tsx","../../src/utils/createHttpStatusSink.ts","../../src/components/HttpStatusProvider.tsx"],"mappings":";;;UAIiB,eAAA;EAAA,SACN,QAAA,EAAU,SAAA;EAAA,SACV,QAAA,GAAW,SAAA;AAAA;AAAA,iBAGN,UAAA,CAAA;EACd,QAAA;EACA;AAAA,GACC,eAAA,GAAkB,SAAA;;;UCRJ,eAAA;EAAA,SACN,QAAA,EAAU,SAAA;EAAA,SACV,QAAA,GAAW,SAAA;AAAA;AAAA,iBAGN,UAAA,CAAA;EACd,QAAA;EACA;AAAA,GACC,eAAA,GAAkB,SAAA;;;UCRJ,aAAA;;WAEN,QAAA,EAAU,SAAA;EAAA,SACV,QAAA,EAAU,SAAA;AAAA;;;;;;;;AFErB;;;;;;;;;;iBEkBgB,QAAA,CAAA;EAAW,QAAA;EAAU;AAAA,GAAY,aAAA,GAAgB,SAAA;;;UCrBhD,mBAAA;;WAEN,IAAA;AAAA;;;;;;;;;AHCX;;;;;;;;;;;;;;;;;;;;ACLA;;;;;;;;;;AAKA;;;;;;;;iBEgDgB,cAAA,CAAA;EAAiB;AAAA,GAAQ,mBAAA,GAAsB,SAAA;;;;;;AHrD/D;;;;;;;;;;AAKA;;;;;;;UIWiB,cAAA;EACf,IAAA;AAAA;AAAA,iBAGc,oBAAA,CAAA,GAAwB,cAAA;;;UCjBvB,uBAAA;EAAA,SACN,IAAA,EAAM,cAAA;EAAA,SACN,QAAA,EAAU,SAAA;AAAA;AAAA,iBAGL,kBAAA,CAAA;EACd,IAAA;EACA;AAAA,GACC,uBAAA,GAA0B,SAAA"}

package/dist/cjs/Link-BspioC76.js

@@ -0,0 +1,2 @@
+const e=require(`./useRoute-Dudo2K_0.js`),t=require(`./RouterProvider-fJvMO5Tc.js`);let n=require(`react`),r=require(`react/jsx-runtime`);function i(e,n){return e.routeName===n.routeName&&e.className===n.className&&e.activeClassName===n.activeClassName&&e.activeStrict===n.activeStrict&&e.ignoreQueryParams===n.ignoreQueryParams&&e.onClick===n.onClick&&e.target===n.target&&e.style===n.style&&e.children===n.children&&e.hash===n.hash&&t.u(e.routeParams,n.routeParams)&&t.u(e.routeOptions,n.routeOptions)}const a=(0,n.memo)(({routeName:i,routeParams:a=e.r,routeOptions:o=e.n,className:s,activeClassName:c=`active`,activeStrict:l=!1,ignoreQueryParams:u=!0,hash:d,onClick:f,target:p,children:m,...h})=>{let g=t.p(),_=t.o(i,a,l,u,d),v=t.c(g,i,a,d===void 0?void 0:{hash:d}),y=e=>{f&&(f(e),e.defaultPrevented)||!t.d(e.nativeEvent)||p===`_blank`||(e.preventDefault(),t.l(g,i,a,d,o).catch(()=>{}))},b=(0,n.useMemo)(()=>t.s(_,c,s),[_,c,s]);return(0,r.jsx)(`a`,{...h,href:v,className:b,onClick:y,children:m})},i);a.displayName=`Link`,Object.defineProperty(exports,`t`,{enumerable:!0,get:function(){return a}});
+//# sourceMappingURL=Link-BspioC76.js.map

package/dist/cjs/Link-BspioC76.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Link-BspioC76.js","names":["shallowEqual","EMPTY_PARAMS","EMPTY_OPTIONS","useRouter","useIsActiveRoute","buildHref","shouldNavigate","buildActiveClassName"],"sources":["../../src/components/Link.tsx"],"sourcesContent":["import { memo, useMemo } from \"react\";\n\nimport { EMPTY_PARAMS, EMPTY_OPTIONS } from \"../constants\";\nimport {\n  shouldNavigate,\n  buildHref,\n  buildActiveClassName,\n  navigateWithHash,\n  shallowEqual,\n} from \"../dom-utils\";\nimport { useIsActiveRoute } from \"../hooks/useIsActiveRoute\";\nimport { useRouter } from \"../hooks/useRouter\";\n\nimport type { LinkProps } from \"../types\";\nimport type { FC, MouseEvent } from \"react\";\n\nfunction areLinkPropsEqual(\n  prev: Readonly<LinkProps>,\n  next: Readonly<LinkProps>,\n): boolean {\n  return (\n    prev.routeName === next.routeName &&\n    prev.className === next.className &&\n    prev.activeClassName === next.activeClassName &&\n    prev.activeStrict === next.activeStrict &&\n    prev.ignoreQueryParams === next.ignoreQueryParams &&\n    prev.onClick === next.onClick &&\n    prev.target === next.target &&\n    prev.style === next.style &&\n    prev.children === next.children &&\n    prev.hash === next.hash &&\n    shallowEqual(prev.routeParams, next.routeParams) &&\n    shallowEqual(prev.routeOptions, next.routeOptions)\n  );\n}\n\nconst LinkImpl: FC<LinkProps> = ({\n  routeName,\n  routeParams = EMPTY_PARAMS,\n  routeOptions = EMPTY_OPTIONS,\n  className,\n  activeClassName = \"active\",\n  activeStrict = false,\n  ignoreQueryParams = true,\n  hash,\n  onClick,\n  target,\n  children,\n  ...props\n}) => {\n  // memo + areLinkPropsEqual guarantees that on bail-out the component does\n  // not render; on render, routeParams/routeOptions either changed reference\n  // (true change) or comparator failed (e.g., BigInt fallback to identity),\n  // so they're safe to use directly in hook deps.\n\n  const router = useRouter();\n\n  // When `hash` prop is set, active state requires both route AND hash to\n  // match (#532). Without this, three tab links sharing routeName=\"settings\"\n  // would all be marked active by route-name alone, defeating tab semantics.\n  const isActive = useIsActiveRoute(\n    routeName,\n    routeParams,\n    activeStrict,\n    ignoreQueryParams,\n    hash,\n  );\n\n  // No useMemo: outer memo()+shallowEqual prevents Link re-render unless a\n  // prop actually changed. When this body runs, either `hash` differs from\n  // last render or another prop changed — in both cases the `{ hash }` alloc\n  // is unavoidable. The useMemo wrapper added one closure + deps slot per\n  // render without saving an allocation.\n  const hashOption = hash === undefined ? undefined : { hash };\n  const href = buildHref(router, routeName, routeParams, hashOption);\n\n  // useCallback was wasteful: 7 deps recreated the closure on every meaningful\n  // render anyway, and `<a onClick>` does not benefit from a stable function\n  // identity (no child-memo-bail-out chain past it). Inline arrow function is\n  // what React Compiler emits automatically for this shape.\n  const handleClick = (evt: MouseEvent<HTMLAnchorElement>) => {\n    if (onClick) {\n      onClick(evt);\n\n      if (evt.defaultPrevented) {\n        return;\n      }\n    }\n\n    if (!shouldNavigate(evt.nativeEvent) || target === \"_blank\") {\n      return;\n    }\n\n    evt.preventDefault();\n    navigateWithHash(router, routeName, routeParams, hash, routeOptions).catch(\n      () => {},\n    );\n  };\n\n  // Memoize the joined class string. parseTokens + Set + join on every render\n  // adds up on pages with N Links navigating frequently; deps cover every\n  // input the function reads so cache invalidation is exact.\n  const finalClassName = useMemo(\n    () => buildActiveClassName(isActive, activeClassName, className),\n    [isActive, activeClassName, className],\n  );\n\n  return (\n    <a {...props} href={href} className={finalClassName} onClick={handleClick}>\n      {children}\n    </a>\n  );\n};\n\nexport const Link: FC<LinkProps> = memo(LinkImpl, areLinkPropsEqual);\n\nLink.displayName = \"Link\";\n"],"mappings":"0IAgBA,SAAS,EACP,EACA,EACS,CACT,OACE,EAAK,YAAc,EAAK,WACxB,EAAK,YAAc,EAAK,WACxB,EAAK,kBAAoB,EAAK,iBAC9B,EAAK,eAAiB,EAAK,cAC3B,EAAK,oBAAsB,EAAK,mBAChC,EAAK,UAAY,EAAK,SACtB,EAAK,SAAW,EAAK,QACrB,EAAK,QAAU,EAAK,OACpB,EAAK,WAAa,EAAK,UACvB,EAAK,OAAS,EAAK,MACnBA,EAAAA,EAAa,EAAK,YAAa,EAAK,YAAY,EAChDA,EAAAA,EAAa,EAAK,aAAc,EAAK,aAAa,CAkFtD,MAAa,GAAA,EAAA,EAAA,OA9EoB,CAC/B,YACA,cAAcC,EAAAA,EACd,eAAeC,EAAAA,EACf,YACA,kBAAkB,SAClB,eAAe,GACf,oBAAoB,GACpB,OACA,UACA,SACA,WACA,GAAG,KACC,CAMJ,IAAM,EAASC,EAAAA,GAAW,CAKpB,EAAWC,EAAAA,EACf,EACA,EACA,EACA,EACA,EACD,CAQK,EAAOC,EAAAA,EAAU,EAAQ,EAAW,EADvB,IAAS,IAAA,GAAY,IAAA,GAAY,CAAE,OAAM,CACM,CAM5D,EAAe,GAAuC,CACtD,IACF,EAAQ,EAAI,CAER,EAAI,mBAKN,CAACC,EAAAA,EAAe,EAAI,YAAY,EAAI,IAAW,WAInD,EAAI,gBAAgB,CACpB,EAAA,EAAiB,EAAQ,EAAW,EAAa,EAAM,EAAa,CAAC,UAC7D,GACP,GAMG,GAAA,EAAA,EAAA,aACEC,EAAAA,EAAqB,EAAU,EAAiB,EAAU,CAChE,CAAC,EAAU,EAAiB,EAAU,CACvC,CAED,OACE,EAAA,EAAA,KAAC,IAAD,CAAG,GAAI,EAAa,OAAM,UAAW,EAAgB,QAAS,EAC3D,WACC,CAAA,EAI0C,EAAkB,CAEpE,EAAK,YAAc"}

package/dist/cjs/RouterErrorBoundary-BlJmaoyr.d.ts

@@ -0,0 +1,47 @@
+import { HTMLAttributes, MouseEventHandler, ReactElement, ReactNode } from "react";
+import { NavigationOptions, Navigator, Params, RouterError, State } from "@real-router/core";
+
+//#region src/types.d.ts
+interface RouteState<P extends Params = Params> {
+  route: State<P> | undefined;
+  previousRoute?: State | undefined;
+}
+type RouteContext<P extends Params = Params> = {
+  navigator: Navigator;
+} & RouteState<P>;
+interface LinkProps<P extends Params = Params> extends HTMLAttributes<HTMLAnchorElement> {
+  routeName: string;
+  routeParams?: P;
+  routeOptions?: NavigationOptions;
+  activeClassName?: string;
+  activeStrict?: boolean;
+  ignoreQueryParams?: boolean;
+  /**
+   * URL fragment (decoded form, no leading "#") (#532).
+   * - omitted/`undefined` → preserve current fragment on same-route navigation
+   * - `""` → clear fragment
+   * - non-empty → set fragment
+   *
+   * Requires a URL plugin (browser-plugin or navigation-plugin) for full
+   * round-trip; hash-plugin ignores the prop with a one-time dev warning.
+   */
+  hash?: string;
+  target?: string;
+  onClick?: MouseEventHandler<HTMLAnchorElement>;
+  onMouseOver?: MouseEventHandler<HTMLAnchorElement>;
+}
+//#endregion
+//#region src/components/RouterErrorBoundary.d.ts
+interface RouterErrorBoundaryProps {
+  readonly children: ReactNode;
+  readonly fallback: (error: RouterError, resetError: () => void) => ReactNode;
+  readonly onError?: (error: RouterError, toRoute: State | null, fromRoute: State | null) => void;
+}
+declare function RouterErrorBoundary({
+  children,
+  fallback,
+  onError
+}: RouterErrorBoundaryProps): ReactElement;
+//#endregion
+export { RouteContext as i, RouterErrorBoundaryProps as n, LinkProps as r, RouterErrorBoundary as t };
+//# sourceMappingURL=RouterErrorBoundary-BlJmaoyr.d.ts.map

package/dist/cjs/RouterErrorBoundary-BlJmaoyr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RouterErrorBoundary-BlJmaoyr.d.ts","names":[],"sources":["../../src/types.ts","../../src/components/RouterErrorBoundary.tsx"],"mappings":";;;;UAQiB,UAAA,WAAqB,MAAA,GAAS,MAAA;EAC7C,KAAA,EAAO,KAAA,CAAM,CAAA;EACb,aAAA,GAAgB,KAAA;AAAA;AAAA,KAGN,YAAA,WAAuB,MAAA,GAAS,MAAA;EAC1C,SAAA,EAAW,SAAA;AAAA,IACT,UAAA,CAAW,CAAA;AAAA,UAEE,SAAA,WACL,MAAA,GAAS,MAAA,UACX,cAAA,CAAe,iBAAA;EACvB,SAAA;EACA,WAAA,GAAc,CAAA;EACd,YAAA,GAAe,iBAAA;EACf,eAAA;EACA,YAAA;EACA,iBAAA;EAjB6C;;;;;;;;AAK/C;EAsBE,IAAA;EACA,MAAA;EACA,OAAA,GAAU,iBAAA,CAAkB,iBAAA;EAC5B,WAAA,GAAc,iBAAA,CAAkB,iBAAA;AAAA;;;UCxBjB,wBAAA;EAAA,SACN,QAAA,EAAU,SAAA;EAAA,SACV,QAAA,GAAW,KAAA,EAAO,WAAA,EAAa,UAAA,iBAA2B,SAAA;EAAA,SAC1D,OAAA,IACP,KAAA,EAAO,WAAA,EACP,OAAA,EAAS,KAAA,SACT,SAAA,EAAW,KAAA;AAAA;AAAA,iBAIC,mBAAA,CAAA;EACd,QAAA;EACA,QAAA;EACA;AAAA,GACC,wBAAA,GAA2B,YAAA"}

package/dist/cjs/{RouterProvider-Bj1_NbpA.d.ts → RouterProvider-DvC9mViF.d.ts}

@@ -1,4 +1,4 @@
-import { l as LinkProps } from "./useRouterTransition-BYit_9Mt.js";
+import { r as LinkProps } from "./RouterErrorBoundary-BlJmaoyr.js";
 import { FC, ReactNode } from "react";
 import { NavigationOptions, Params, Router, State } from "@real-router/core";
 
@@ -45,4 +45,4 @@ interface RouteProviderProps {
 declare const RouterProvider: FC<RouteProviderProps>;
 //#endregion
 export { Link as n, RouterProvider as t };
-//# sourceMappingURL=RouterProvider-Bj1_NbpA.d.ts.map
+//# sourceMappingURL=RouterProvider-DvC9mViF.d.ts.map

package/dist/cjs/RouterProvider-DvC9mViF.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RouterProvider-DvC9mViF.d.ts","names":[],"sources":["../../src/components/Link.tsx","../../../../shared/dom-utils/scroll-restore.ts","../../src/RouterProvider.tsx"],"mappings":";;;;;cAkHa,IAAA,EAAM,EAAA,CAAG,SAAA;;;KCxGV,qBAAA;AAAA,UAEK,wBAAA;EACf,IAAA,GAAO,qBAAA;EACP,eAAA;EACA,eAAA,UAAyB,WAAA;EDmGyC;;;;;;;ACxGpE;;;;;EAkBE,QAAA,GAAW,cAAA;EAhB4B;;;;;;;EAwBvC,UAAA;AAAA;;;UCrBe,kBAAA;EACf,MAAA,EAAQ,MAAA;EACR,QAAA,EAAU,SAAA;EACV,kBAAA;EACA,iBAAA,GAAoB,wBAAA;EACpB,eAAA;AAAA;AAAA,cAGW,cAAA,EAAgB,EAAA,CAAG,kBAAA"}

package/dist/cjs/RouterProvider-fJvMO5Tc.js

@@ -0,0 +1,2 @@
+const e=require(`./useRoute-Dudo2K_0.js`);let t=require(`react`),n=require(`@real-router/core`),r=require(`@real-router/route-utils`),i=require(`react/jsx-runtime`),a=require(`@real-router/sources`),o=require(`@real-router/core/api`);const s=()=>{let n=(0,t.useContext)(e.s);if(!n)throw Error(`useRouter must be used within a RouterProvider`);return n};function c(e){let r=s(),i=(0,t.useMemo)(()=>(0,a.createRouteNodeSource)(r,e),[r,e]),o=(0,t.useSyncExternalStore)(i.subscribe,i.getSnapshot,i.getSnapshot),c=(0,n.getNavigator)(r);return(0,t.useMemo)(()=>({navigator:c,route:o.route,previousRoute:o.previousRoute}),[c,o])}const l=`data-real-router-announcer`,u=Object.freeze({destroy:()=>{}});function d(e,t){if(typeof document>`u`)return u;let n=t?.prefix??`Navigated to `,r=t?.getAnnouncementText,i=!0,a=!1,o=!1,s=``,c=null,l,d=f(),g=(e,t)=>{s=e,clearTimeout(l),d.textContent=e,l=setTimeout(()=>{d.textContent=``,s=``},7e3),h(t)},_=setTimeout(()=>{if(a=!0,c!==null&&!o){let e=c;c=null,g(e,document.querySelector(`h1`))}},100),v=e.subscribe(({route:e})=>{if(i){i=!1;return}requestAnimationFrame(()=>{requestAnimationFrame(()=>{if(o)return;let t=document.querySelector(`h1`),i=m(e,n,r,t);if(!(!i||i===s)){if(!a){c=i;return}g(i,t)}})})});return{destroy(){o=!0,v(),clearTimeout(l),clearTimeout(_),p()}}}function f(){let e=document.querySelector(`[${l}]`);if(e)return e;let t=document.createElement(`div`);return t.setAttribute(`style`,`position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);clip-path:inset(50%);white-space:nowrap;border:0`),t.setAttribute(`aria-live`,`assertive`),t.setAttribute(`aria-atomic`,`true`),t.setAttribute(l,``),(document.body??document.documentElement).prepend(t),t}function p(){document.querySelector(`[${l}]`)?.remove()}function m(e,t,n,r){if(n)try{let t=n(e);if(t)return t}catch(e){console.error(`[real-router] getAnnouncementText threw; falling back to default resolution.`,e)}let i=(r?.textContent??``).trim(),a=e.name.startsWith(`@@`)?``:e.name;return`${t}${i||document.title||a||globalThis.location.pathname}`}function h(e){e&&(e.hasAttribute(`tabindex`)||e.setAttribute(`tabindex`,`-1`),e.focus({preventScroll:!0}))}const g=Object.freeze({destroy:()=>{}});function _(e,t){if(globalThis.window===void 0)return g;let n=t?.mode??`restore`;if(n===`native`)return g;let r=t?.anchorScrolling??!0,i=t?.scrollContainer,a=t?.behavior??`auto`,o=t?.storageKey??`real-router:scroll`,s,c=()=>{if(s!==void 0)return s;try{let e=sessionStorage.getItem(o);s=e?JSON.parse(e):{}}catch{s={}}return s},l=(e,t)=>{try{let n=c();if(n[e]===t)return;n[e]=t,sessionStorage.setItem(o,JSON.stringify(n))}catch{}},u=history.scrollRestoration;try{history.scrollRestoration=`manual`}catch{}let d=()=>{let e=i?.();return e?e.scrollTop:globalThis.scrollY},f=e=>{let t=i?.();t?t.scrollTo({top:e,left:0,behavior:a}):globalThis.scrollTo({top:e,left:0,behavior:a})},p=e=>{let t=e.context?.url?.hash;if(t!==void 0){if(r&&t.length>0){let e=document.getElementById(t);if(e){e.scrollIntoView({behavior:a});return}}f(0);return}let n=globalThis.location.hash;if(r&&n.length>1){let e;try{e=decodeURIComponent(n.slice(1))}catch{e=n.slice(1)}let t=document.getElementById(e);if(t){t.scrollIntoView({behavior:a});return}}f(0)},m=!1,h=!1,_=e=>{try{return y(e)}catch{return h||(h=!0,console.error(`[real-router] scroll-restore: route "${e.name}" has params that cannot be canonicalized (e.g. BigInt or cyclic structure). Scroll position will not be captured or restored for this route.`)),null}},v=e.subscribe(({route:e,previousRoute:t})=>{let r=e.context.navigation;if(t){let e=_(t);e!==null&&l(e,d())}requestAnimationFrame(()=>{if(!m){if(n===`top`||!r){p(e);return}if(r.navigationType!==`replace`){if(r.direction===`back`||r.navigationType===`traverse`||r.navigationType===`reload`){let t=_(e);f(t===null?0:c()[t]??0);return}p(e)}}})}),b=()=>{let t=e.getState();if(t){let e=_(t);e!==null&&l(e,d())}};return globalThis.addEventListener(`pagehide`,b),{destroy:()=>{if(!m){m=!0,v(),globalThis.removeEventListener(`pagehide`,b);try{history.scrollRestoration=u}catch{}}}}}const v=new WeakMap;function y(e){let t=v.get(e);if(t!==void 0)return t;let n=`${e.name}:${b(e.params)}`;return v.set(e,n),n}function b(e){return JSON.stringify(e,x)}function x(e,t){if(typeof t==`function`)return`<fn>`;if(typeof t==`symbol`)return`<sym>`;if(typeof t==`object`&&t&&!Array.isArray(t)){let e=Object.create(null),n=Object.keys(t).sort((e,t)=>e.localeCompare(t));for(let r of n)e[r]=t[r];return e}return t}const S=Object.freeze({destroy:()=>{}});function C(e){if(typeof document>`u`||typeof document.startViewTransition!=`function`)return S;let t=null,n=null,r=!1,i=()=>{t?.(),t=null},a=e.subscribeLeave(({signal:e})=>{if(!e.aborted)return r=!1,i(),new Promise(a=>{let o=new Promise(e=>{t=e});e.addEventListener(`abort`,()=>{r||(i(),n?.skipTransition?.(),a())},{once:!0});try{n=document.startViewTransition(()=>(a(),o))}catch{i(),a()}})}),o=e.subscribe(()=>{let e=t;r=!0,t=null,e===null?n=null:setTimeout(()=>{e(),n=null},0)});return{destroy:()=>{a(),o(),n?.skipTransition?.(),n=null,i()}}}function w(e){return e.button===0&&!e.metaKey&&!e.altKey&&!e.ctrlKey&&!e.shiftKey}const T=/%[\dA-Fa-f]{2}/;function E(e){if(T.test(e))try{return encodeURI(decodeURIComponent(e)).replaceAll(`#`,`%23`)}catch{}return encodeURI(e).replaceAll(`#`,`%23`)}function D(e,t,n,r){try{let i=r?.hash,a;i!==void 0&&(a=i.startsWith(`#`)?i.slice(1):i);let o=e.buildUrl;if(o){let e=o(t,n,a===void 0?void 0:{hash:a});if(typeof e==`string`&&e.length>0)return e}let s=e.buildPath(t,n);if(typeof s!=`string`||s.length===0){console.error(`[real-router] Route "${t}" yielded an empty path. The element will render without an href attribute.`);return}return a?`${s}#${E(a)}`:s}catch{console.error(`[real-router] Route "${t}" is not defined. The element will render without an href attribute.`);return}}function O(e,t,n,r,i){let a={...i};r!==void 0&&(a.hash=r);let o=e.getState();if(o?.name===t&&N(o.params,n)){let e=o.context?.url?.hash??``;e!==(r??e)&&(a.force=!0,a.hashChange=!0)}return e.navigate(t,n,a)}const k=/\s/,A=/\S+/g;function j(e){return e?k.test(e)?e.match(A)??[]:[e]:[]}function M(e,t,n){if(e&&t){let e=j(t);if(e.length===0)return n??void 0;if(!n)return e.join(` `);let r=j(n),i=new Set(r);for(let t of e)i.has(t)||(i.add(t),r.push(t));return r.join(` `)}return n??void 0}function N(e,t){if(Object.is(e,t))return!0;if(!e||!t)return!1;let n=Object.keys(e);if(n.length!==Object.keys(t).length)return!1;let r=e,i=t;for(let e of n)if(!Object.prototype.hasOwnProperty.call(t,e)||!Object.is(r[e],i[e]))return!1;return!0}function P(e,n,r=!1,i=!0,o){let c=s(),l=(0,t.useMemo)(()=>(0,a.createActiveRouteSource)(c,e,n,{strict:r,ignoreQueryParams:i,...o!==void 0&&{hash:o}}),[c,e,n,r,i,o]);return(0,t.useSyncExternalStore)(l.subscribe,l.getSnapshot,l.getSnapshot)}function F({children:e,fallback:n,onError:r}){let o=s(),c=(0,t.useMemo)(()=>(0,a.createDismissableError)(o),[o]),l=(0,t.useSyncExternalStore)(c.subscribe,c.getSnapshot,c.getSnapshot),u=(0,t.useRef)(r);return(0,t.useLayoutEffect)(()=>{u.current=r}),(0,t.useEffect)(()=>{l.error&&u.current?.(l.error,l.toRoute,l.fromRoute)},[l.version]),(0,i.jsxs)(i.Fragment,{children:[e,l.error?n(l.error,l.resetError):null]})}const I=()=>{let n=(0,t.useContext)(e.a);if(!n)throw Error(`useNavigator must be used within a RouterProvider`);return n},L=()=>(0,r.getRouteUtils)((0,o.getPluginApi)(s()).getTree());function R(){let e=(0,a.getTransitionSource)(s());return(0,t.useSyncExternalStore)(e.subscribe,e.getSnapshot,e.getSnapshot)}const z=({router:r,children:o,announceNavigation:s,scrollRestoration:c,viewTransitions:l})=>{(0,t.useEffect)(()=>{if(!s)return;let e=d(r);return()=>{e.destroy()}},[s,r]);let u=c?.mode,f=c?.anchorScrolling,p=c?.behavior,m=c?.storageKey,h=c!==void 0;(0,t.useEffect)(()=>{if(!h)return;let e=_(r,{mode:u,anchorScrolling:f,behavior:p,storageKey:m,scrollContainer:c.scrollContainer});return()=>{e.destroy()}},[r,h,u,f,p,m]),(0,t.useEffect)(()=>{if(!l)return;let e=C(r);return()=>{e.destroy()}},[r,l]);let g=(0,t.useMemo)(()=>(0,n.getNavigator)(r),[r]),v=(0,t.useMemo)(()=>(0,a.createRouteSource)(r),[r]),y=(0,t.useSyncExternalStore)(v.subscribe,v.getSnapshot,v.getSnapshot),b=(0,t.useMemo)(()=>({navigator:g,route:y.route,previousRoute:y.previousRoute}),[g,y]);return(0,i.jsx)(e.s.Provider,{value:r,children:(0,i.jsx)(e.a.Provider,{value:g,children:(0,i.jsx)(e.o.Provider,{value:b,children:o})})})};Object.defineProperty(exports,`a`,{enumerable:!0,get:function(){return F}}),Object.defineProperty(exports,`c`,{enumerable:!0,get:function(){return D}}),Object.defineProperty(exports,`d`,{enumerable:!0,get:function(){return w}}),Object.defineProperty(exports,`f`,{enumerable:!0,get:function(){return c}}),Object.defineProperty(exports,`i`,{enumerable:!0,get:function(){return I}}),Object.defineProperty(exports,`l`,{enumerable:!0,get:function(){return O}}),Object.defineProperty(exports,`n`,{enumerable:!0,get:function(){return R}}),Object.defineProperty(exports,`o`,{enumerable:!0,get:function(){return P}}),Object.defineProperty(exports,`p`,{enumerable:!0,get:function(){return s}}),Object.defineProperty(exports,`r`,{enumerable:!0,get:function(){return L}}),Object.defineProperty(exports,`s`,{enumerable:!0,get:function(){return M}}),Object.defineProperty(exports,`t`,{enumerable:!0,get:function(){return z}}),Object.defineProperty(exports,`u`,{enumerable:!0,get:function(){return N}});
+//# sourceMappingURL=RouterProvider-fJvMO5Tc.js.map