@rshono/core 1.0.0-rc.23 → 1.0.0-rc.24

package/README.md

@@ -103,7 +103,9 @@ export default async function Profile({ params, ctx }: PageProps<'/profile/:id'>
 
 - Pages receive `{ url, params, ctx }` — `PageProps<'/profile/:id'>` types `params.id`, and `url` is a real
   `URL`. The same pair reaches a `'use client'` component from `useNavigation()`, so a read moves across the
-  boundary unchanged.
+  boundary unchanged — except the fragment, which a browser never sends to the server: `PageProps.url` never
+  has one, while `useNavigation().url.hash` is read from the address bar after hydration and follows in-page
+  links and Back/Forward.
 - **`ctx` is the request context** — `ctx.req`, cookies, env, middleware variables, the proxy-aware URL. It is
   the same object `getRequestContext()` returns from `@rshono/core/server`, handed over so a page needs no
   import. Reading it on a `render: 'static'` page throws: a page rendered once at build time has no request.

package/dist/router.d.ts

@@ -57,9 +57,11 @@ export interface PageProps<Path extends string = string, E extends Env = Env> {
      * On a `render: 'static'` route this is the build-time URL — rendered once against `siteUrl`, so the
      * origin is `siteUrl`'s and `url.searchParams` is always empty, on first paint and after a soft
      * navigation alike. **`useNavigation().url` is the same frozen URL, not a way around it**: the payload
-     * carries one `href` and both readings come from it. Mark the route `render: 'dynamic'` if the page
-     * depends on the query; a `'use client'` component that only wants it after hydration can read
-     * `location.search` in an effect.
+     * carries one `href` and both readings come from it. The fragment is the one part no payload can carry
+     * — a browser never sends `#…` with the request — so this prop never has one, while
+     * `useNavigation().url.hash` is read from the browser after hydration. Mark the route
+     * `render: 'dynamic'` if the page depends on the query; a `'use client'` component that only wants it
+     * after hydration can read `location.search` in an effect.
      */
     url: URL;
     /** Matched route params for this request, e.g. `{ id: '42' }` for `/profile/:id`. */

package/dist/router.js.map

@@ -1 +1 @@
-{"version":3,"file":"router.js","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAkQA;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAY;IACtC,OAAO,KAAK,CAAC,IAAI,KAAK,UAAU,CAAC;AACnC,CAAC;AA6LD,MAAM,UAAU,YAAY,CAAC,KAAqC;IAChE,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,CAAE,KAAqB,CAAC;AAC3E,CAAC","sourcesContent":["import type { Env, Handler } from 'hono';\nimport type { ParamKeys, ParamKeyToRecord } from 'hono/types';\nimport type { ReactNode } from 'react';\n// Type-only, so importing `@rshono/core` pulls in none of `context.ts`'s runtime machinery.\nimport type { RequestContext } from './runtime/context.js';\n\ntype Simplify<T> = { [K in keyof T]: T[K] } & {};\ntype UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;\n\n/**\n * The `params` record implied by a route path pattern — one required `string` key per `:param`\n * segment, `Record<string, never>` for a path with none. Paths use Hono's syntax, so `:id`,\n * `:id{[0-9]+}` and `*` all work.\n *\n * You rarely name this directly; {@link PageProps} applies it for you.\n *\n * @typeParam P - The literal route path, e.g. `'/users/:id/posts/:postId'`.\n *\n * @example\n * ```ts\n * type P = PathParams<'/users/:id/posts/:postId'>; // { id: string; postId: string }\n * ```\n *\n * @see {@link https://hono.dev/docs/api/routing#path-parameter | Hono — path parameters}\n */\nexport type PathParams<P extends string> =\n  ParamKeys<P> extends never ? Record<string, never> : Simplify<UnionToIntersection<ParamKeyToRecord<ParamKeys<P>>>>;\n\n/**\n * Props every page component receives. Pass the route's path as the type argument to get `params`\n * typed key-by-key; without it `params` falls back to an open `Record<string, string>`.\n *\n * `defineRoutes` checks each page's props against `PageProps<path>`, so a mismatched path literal is\n * a type error at the route definition. `url` and `params` mirror what `useNavigation()` gives a\n * `'use client'` component, so a read moves across the server/client line unchanged.\n *\n * @typeParam Path - The literal path this page is mounted at, e.g. `'/profile/:id'`.\n * @typeParam E - The app's Hono {@link Env}, to type {@link RequestContext.var} and\n *   {@link RequestContext.env} on {@link PageProps.ctx}.\n *\n * @example\n * ```tsx\n * import type { PageProps } from '@rshono/core';\n *\n * export default async function Profile({ params, url }: PageProps<'/profile/:id'>) {\n *   const user = await db.getUser(params.id); // params.id is string\n *   const tab = url.searchParams.get('tab') ?? 'overview';\n *   return <Layout>{user.name} — {tab}</Layout>;\n * }\n * ```\n *\n * @see {@link https://www.rshono.com/docs/pages#page-props | Docs — page props}\n */\nexport interface PageProps<Path extends string = string, E extends Env = Env> {\n  /**\n   * The absolute browser-facing request {@link URL}, proxy-header aware (`X-Forwarded-Host` /\n   * `-Proto`). A fresh instance per request, so mutating it is local to the page; it is not\n   * serializable, so hand a `'use client'` component `url.href` rather than `url`.\n   *\n   * On a `render: 'static'` route this is the build-time URL — rendered once against `siteUrl`, so the\n   * origin is `siteUrl`'s and `url.searchParams` is always empty, on first paint and after a soft\n   * navigation alike. **`useNavigation().url` is the same frozen URL, not a way around it**: the payload\n   * carries one `href` and both readings come from it. Mark the route `render: 'dynamic'` if the page\n   * depends on the query; a `'use client'` component that only wants it after hydration can read\n   * `location.search` in an effect.\n   */\n  url: URL;\n  /** Matched route params for this request, e.g. `{ id: '42' }` for `/profile/:id`. */\n  params: string extends Path ? Record<string, string> : PathParams<Path>;\n  /**\n   * The request context — the object `getRequestContext()` returns, handed to the page so cookies,\n   * headers, env and middleware variables are reachable without an import.\n   *\n   * Server-only, non-enumerable (a `{...props}` spread and `JSON.stringify` both skip it) and never\n   * serialized. Passing it to a `'use client'` component fails the render, because it wraps the live\n   * request — read what you need here and pass plain values down.\n   *\n   * Non-enumerable is the one place this API breaks a JavaScript expectation, and it is unavoidable: an\n   * enumerable `ctx` would put `ctx.hono.env` — every binding and secret — into React's dev-only\n   * serialization of a server component's props, which walks own enumerable properties. So `<Child\n   * {...props} />` hands a **server** child `ctx: undefined` with no error, while the type says otherwise.\n   * Nested server components are meant to call `getRequestContext()` for the same object rather than\n   * receive it, which is also the fix if a spread has already cost you an afternoon.\n   *\n   * Reading it on a `render: 'static'` route throws: a prerendered page has no per-request context.\n   * Mark the route `render: 'dynamic'`, or use the `url` / `params` props.\n   *\n   * @example\n   * ```tsx\n   * export default function Dashboard({ ctx }: PageProps) {\n   *   const session = ctx.cookies.get('session');\n   *   if (!session) redirect('/login');\n   *   return <Layout>Signed in as {session}</Layout>;\n   * }\n   * ```\n   */\n  ctx: RequestContext<E>;\n}\n\n/**\n * A page: a React **server component** rendering the entire document (`<html>…</html>`), usually via\n * a shared layout. It may be `async` and await data directly.\n *\n * Each page module default-exports exactly one. Interactive parts belong in `'use client'` components\n * the page imports — only those ship JS.\n *\n * @typeParam P - The component's props; for a page these are {@link PageProps}.\n *\n * @see {@link https://react.dev/reference/rsc/server-components | React — Server Components}\n * @see {@link https://www.rshono.com/docs/pages | Docs — pages}\n */\n// `any`, not `unknown`: this default is what an unparameterised `PageComponent` means in a user's own\n// annotation, and `unknown` props would reject every component that declares the props it actually takes.\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type PageComponent<P = any> = (props: P) => ReactNode | Promise<ReactNode>;\n\n/**\n * The shape an `{ type: 'endpoint' }` route's server module must have: a single named `handler`\n * export. It only ever loads on the server, so importing a database client or reading secrets from it\n * is safe.\n *\n * @example\n * ```ts\n * // src/health.ts\n * import type { Handler } from 'hono';\n *\n * export const handler: Handler = (c) => c.json({ ok: true });\n * ```\n *\n * @see {@link https://www.rshono.com/docs/routing#endpoint-routes | Docs — endpoint routes}\n */\nexport interface EndpointServerModule {\n  /**\n   * A Hono {@link Handler} for every request the route matches. It is passed Hono's `Context`, so the\n   * request, the response builders (`c.json`, `c.text`, `c.body`) and middleware variables are all\n   * reached through it.\n   *\n   * @see {@link https://hono.dev/docs/api/context | Hono — Context}\n   */\n  handler: Handler;\n}\n\n/**\n * A page route — a path rendered by a server component. This is the default\n * route kind, so `type` can be omitted.\n *\n * @example\n * ```ts\n * { path: '/profile/:id', component: () => import('./components/profile') }\n * ```\n */\nexport interface PageRoute {\n  /** Discriminates a page from an endpoint; optional because `'page'` is the default. */\n  type?: 'page';\n  /**\n   * Hono-style path pattern, e.g. `/`, `/profile/:id`, `/files/*`. Routes are matched in\n   * declaration order.\n   *\n   * @see {@link https://hono.dev/docs/api/routing | Hono — routing}\n   */\n  path: string;\n  /**\n   * Dynamic import of the page module, whose default export is the {@link PageComponent}.\n   *\n   * Write it inline as `() => import('…')`: the framework detects that exact form and injects the\n   * `'use server-entry'` directive that attaches the page's client JS and CSS. Wire the component up\n   * any other way — a variable, a barrel re-export, a computed specifier — and you have to put\n   * `'use server-entry'` on the page module's first line yourself.\n   *\n   * @example\n   * ```ts\n   * component: () => import('./components/profile')\n   * ```\n   *\n   * @see {@link https://www.rshono.com/docs/pages#the-use-server-entry-directive | Docs — the `'use server-entry'` directive}\n   */\n  component: () => Promise<{ default: PageComponent }>;\n  /** `'static'` prerenders the route at build time; `'dynamic'` (the default) renders per request. */\n  render?: 'static' | 'dynamic';\n  /**\n   * For a `render: 'static'` route with params: the param sets to prerender, one page each. Runs at\n   * build time on the server, so it may hit a database or read the filesystem.\n   *\n   * A parameterised static route without this falls back to rendering per request, with a build\n   * warning. Wildcard (`*`), optional and regex params cannot be prerendered.\n   *\n   * **Every value has to be one portable file name**, since that is what a prerendered page is stored as,\n   * and the build fails naming the value rather than writing a page nothing will serve. So: no\n   * `\\ / : * ? \" < > |` or control characters, no trailing `.` or space, and not a reserved Windows device\n   * name (`CON`, `NUL`, `COM1`, …) — the last two enforced everywhere, so a build that works on macOS is\n   * not one that fails in CI on Windows.\n   *\n   * @example\n   * ```ts\n   * {\n   *   path: '/docs/:slug',\n   *   render: 'static',\n   *   component: () => import('./components/documentation'),\n   *   staticPaths: async () => (await db.docs.all()).map((d) => ({ slug: d.slug })),\n   * }\n   * ```\n   *\n   * @see {@link https://www.rshono.com/docs/routing#static-rendering | Docs — static rendering}\n   */\n  staticPaths?: () => Array<Record<string, string>> | Promise<Array<Record<string, string>>>;\n}\n\n/**\n * An endpoint route — a path served by a raw Hono handler instead of a React\n * component. Use it for JSON APIs, webhooks, redirects, feeds, or anything that\n * isn't an HTML page.\n *\n * @example\n * ```ts\n * { type: 'endpoint', path: '/api/health', server: () => import('./health') }\n * ```\n *\n * @see {@link https://www.rshono.com/docs/routing#endpoint-routes | Docs — endpoint routes}\n */\nexport interface EndpointRoute {\n  /** Marks this route as an endpoint rather than a page. Required. */\n  type: 'endpoint';\n  /**\n   * Hono-style path pattern, e.g. `/api/health`, `/api/users/:id`.\n   *\n   * @see {@link https://hono.dev/docs/api/routing | Hono — routing}\n   */\n  path: string;\n  /**\n   * HTTP method to match, or a list of them. Defaults to `'all'` — every method.\n   *\n   * There is no `'head'`: Hono dispatches a `HEAD` as a `GET` and strips the body off the response, so a\n   * `HEAD` is already answered by the `'get'` handler (and by `'all'`), and a route registered for `HEAD`\n   * alone would never be reached.\n   *\n   * A list is how a two-method endpoint says so; `'all'` inside one is refused, since it is either the\n   * whole thing or a mistake. A method the route does not name gets Hono's 404 rather than the handler.\n   *\n   * @example\n   * ```ts\n   * { type: 'endpoint', path: '/api/session', method: ['get', 'delete'], server: () => import('./session') }\n   * ```\n   */\n  method?: HTTPMethod | readonly HTTPMethod[];\n  /** Dynamic import of the {@link EndpointServerModule} exporting `handler`. */\n  server: () => Promise<EndpointServerModule>;\n}\n\n/**\n * HTTP methods an {@link EndpointRoute} can match. `'all'` matches every method.\n *\n * No `'head'`, deliberately — see {@link EndpointRoute.method}. A `HEAD` reaches the `'get'` handler.\n */\nexport type HTTPMethod = 'get' | 'post' | 'put' | 'patch' | 'delete' | 'options' | 'all';\n\n/** Any entry in the `routes` array: a {@link PageRoute} or an {@link EndpointRoute}. */\nexport type Route = PageRoute | EndpointRoute;\n\n/**\n * Narrows a {@link Route} to a {@link PageRoute} — `type` is optional on page routes, so anything not\n * explicitly `'endpoint'` is one.\n *\n * @internal\n */\nexport function isPageRoute(route: Route): route is PageRoute {\n  return route.type !== 'endpoint';\n}\n\n/**\n * A page the framework falls back to rather than routes to — `notFound` and `error` in\n * {@link RouteConfig}. Same contract as a {@link PageRoute} `component`, without a path of its own.\n */\nexport interface FallbackPage {\n  /** Dynamic import of the page module; its default export is the {@link PageComponent}. */\n  component: () => Promise<{ default: PageComponent }>;\n}\n\n/**\n * The error detail handed to the `error` page. Redacted in production — a generic\n * `'Internal Server Error'` and no `stack`; in dev, the real message and stack.\n */\nexport interface ErrorPageInfo {\n  /** The thrown error's message in dev; `'Internal Server Error'` in production. */\n  message: string;\n  /**\n   * The stack trace — **dev only**, and `undefined` in every build. Optional for that reason rather than\n   * because some errors lack one, so a page that renders it should guard on it, not on a mode flag.\n   */\n  stack?: string;\n}\n\n/**\n * Props for the `error` page declared in {@link RouteConfig.error} — the usual {@link PageProps} plus\n * the redaction-aware {@link ErrorPageInfo}.\n *\n * In a build `error.message` is the generic `'Internal Server Error'` and `error.stack` is `undefined`, so\n * the page below guards on the stack rather than on a mode flag — there is no mode flag to guard on.\n *\n * @typeParam E - The app's Hono {@link Env}, forwarded to {@link PageProps.ctx}.\n *\n * @example\n * ```tsx\n * import type { ErrorPageProps } from '@rshono/core';\n *\n * export default function ServerError({ error }: ErrorPageProps) {\n *   return (\n *     <html>\n *       <body>\n *         <h1>Something went wrong</h1>\n *         <p>{error.message}</p>\n *         {error.stack && <pre>{error.stack}</pre>}\n *       </body>\n *     </html>\n *   );\n * }\n * ```\n */\nexport type ErrorPageProps<E extends Env = Env> = PageProps<string, E> & {\n  /** The error that failed the request, redacted in production — see {@link ErrorPageInfo}. */\n  error: ErrorPageInfo;\n};\n\n/**\n * The object form accepted by {@link defineRoutes}: the route table plus the two\n * optional framework-owned pages.\n *\n * @typeParam TRoutes - Inferred tuple of route literals, which is what makes the\n *   per-route `path` → props check possible.\n *\n * @see {@link https://www.rshono.com/docs/routing#notfound-and-error | Docs — notFound and error pages}\n */\nexport interface RouteConfig<TRoutes extends readonly Route[] = readonly Route[]> {\n  /** Every page and endpoint in the app, matched in order. */\n  routes: TRoutes;\n  /** Page rendered with a 404 status for unmatched paths and for `notFound()` calls. */\n  notFound?: FallbackPage;\n  /**\n   * Page rendered with a 500 status when a request throws — a page component, a page module that will not\n   * load, an endpoint, a server action, or middleware. Receives {@link ErrorPageProps}.\n   *\n   * It is a *fresh* render, with its own flight payload, so it hydrates and behaves like any other page.\n   * An app that declares none gets the framework's plain 500 document instead. If the `error` page itself\n   * throws, that is reported too and the framework's document answers.\n   */\n  error?: FallbackPage;\n}\n\n/**\n * The same check for `staticPaths`, whose param sets have to fill the route's own path: a key that does not\n * is otherwise a build-time throw from `interpolatePath` rather than a type error.\n *\n * Keys only, not full assignability, because the declared field type is `Record<string, string>` and a\n * `staticPaths` annotated as returning exactly that has to stay accepted — an index signature carries no\n * key to check, so it passes. Skipped where the path has no params, because `staticPaths` is not called for\n * such a route at all and an error there would be about the wrong thing.\n */\ntype ValidateStaticPaths<R, P extends string> =\n  ParamKeys<P> extends never\n    ? R\n    : R extends { staticPaths: () => infer Sets }\n      ? Awaited<Sets> extends ReadonlyArray<infer Set>\n        ? [keyof PathParams<P>] extends [keyof Set]\n          ? R\n          : R & { staticPaths: `every param set staticPaths returns needs the params of '${P}'` }\n        : R\n      : R;\n\n// `PageProps<P, any>`, not `PageProps<P>`: only the *path* is being checked, and pinning the Env would\n// fail every page that declares its own (`PageProps<'/x', MyEnv>`, to type `ctx.var`).\ntype ValidateRoute<R> = R extends {\n  path: infer P extends string;\n  component: () => Promise<{ default: PageComponent<infer CP> }>;\n}\n  ? // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the Env is deliberately unpinned; see above.\n    [PageProps<P, any>] extends [CP]\n    ? ValidateStaticPaths<R, P>\n    : R & { component: `component props are not satisfied by PageProps<'${P}'>` }\n  : R;\n\ntype ValidateRoutes<TRoutes extends readonly Route[]> = { [K in keyof TRoutes]: ValidateRoute<TRoutes[K]> };\n\n/**\n * Refuses a key that is not a {@link RouteConfig} field — a typo'd `notfound` is otherwise a fallback page\n * that never renders, and nothing at runtime looks for one.\n *\n * Excess-property checking did this while the object form was an overload of its own with a concrete\n * parameter type. It cannot once the parameter is generic and inferred from the argument, because the\n * inferred type *has* the extra key. The message here is the better one anyway: it lands on the field.\n */\ntype ValidateConfigKeys<T> =\n  Exclude<keyof T, keyof RouteConfig> extends never\n    ? T\n    : T & Record<Exclude<keyof T, keyof RouteConfig>, 'not a defineRoutes field — the fields are routes, notFound and error'>;\n\n/** The check for whichever of the two accepted shapes was passed. */\ntype ValidateInput<T> = T extends readonly Route[]\n  ? ValidateRoutes<T>\n  : T extends { routes: infer R extends readonly Route[] }\n    ? ValidateConfigKeys<T> & { routes: ValidateRoutes<R> }\n    : T;\n\n/** The route tuple inside either shape, so the return type carries the literals through both. */\ntype RoutesOf<T> = T extends readonly Route[] ? T : T extends { routes: infer R extends readonly Route[] } ? R : readonly Route[];\n\n/**\n * Declares the app's route table. Export the result as `routes` from `src/routes.ts` — the one file\n * rshono requires. It only ever runs on the server, so importing server-only modules from it (inside\n * `staticPaths`, say) is safe.\n *\n * Takes a {@link RouteConfig} — the `routes` array plus the optional `notFound` and `error` pages — or a\n * bare {@link Route} array as shorthand for an app with neither.\n *\n * Beyond typing the config, every page is cross-checked against its own path: props not satisfied by\n * `PageProps<'<its path>'>` make the `component` field a type error, and a `staticPaths` whose param sets do\n * not fill the path makes that field one.\n *\n * **One signature over both shapes, deliberately.** The array form used to be a second overload, which meant\n * a mistake inside a bare array was reported as an overload-resolution failure whose *first* line was the\n * object form's complaint — \"Property 'routes' is missing\" — pointing at a change the author should not make.\n * The real message was on line 8. A single signature reports the argument once, at the field that is wrong.\n *\n * @param input - A {@link RouteConfig}, or the bare `routes` array.\n * @returns The config, unchanged and fully typed; an array is wrapped as `{ routes }`.\n *\n * @example\n * ```ts\n * // src/routes.ts\n * import { defineRoutes } from '@rshono/core';\n *\n * export const routes = defineRoutes({\n *   routes: [\n *     { path: '/', component: () => import('./components/home') },\n *     { path: '/profile/:id', component: () => import('./components/profile') },\n *     {\n *       path: '/docs/:slug',\n *       render: 'static',\n *       component: () => import('./components/documentation'),\n *       staticPaths: async () => [{ slug: 'getting-started' }, { slug: 'deployment' }],\n *     },\n *     { type: 'endpoint', path: '/api/health', server: () => import('./health') },\n *   ],\n *   notFound: { component: () => import('./components/404') },\n *   error: { component: () => import('./components/500') },\n * });\n * ```\n *\n * @example\n * ```ts\n * // The shorthand, for an app with no notFound or error page.\n * export const routes = defineRoutes([{ path: '/', component: () => import('./components/home') }]);\n * ```\n *\n * @see {@link https://www.rshono.com/docs/routing | Docs — routing}\n */\nexport function defineRoutes<const T extends readonly Route[] | RouteConfig<readonly Route[]>>(input: T & ValidateInput<T>): RouteConfig<RoutesOf<T>>;\nexport function defineRoutes(input: readonly Route[] | RouteConfig): RouteConfig {\n  return Array.isArray(input) ? { routes: input } : (input as RouteConfig);\n}\n"]}
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAoQA;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAY;IACtC,OAAO,KAAK,CAAC,IAAI,KAAK,UAAU,CAAC;AACnC,CAAC;AA6LD,MAAM,UAAU,YAAY,CAAC,KAAqC;IAChE,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,CAAE,KAAqB,CAAC;AAC3E,CAAC","sourcesContent":["import type { Env, Handler } from 'hono';\nimport type { ParamKeys, ParamKeyToRecord } from 'hono/types';\nimport type { ReactNode } from 'react';\n// Type-only, so importing `@rshono/core` pulls in none of `context.ts`'s runtime machinery.\nimport type { RequestContext } from './runtime/context.js';\n\ntype Simplify<T> = { [K in keyof T]: T[K] } & {};\ntype UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;\n\n/**\n * The `params` record implied by a route path pattern — one required `string` key per `:param`\n * segment, `Record<string, never>` for a path with none. Paths use Hono's syntax, so `:id`,\n * `:id{[0-9]+}` and `*` all work.\n *\n * You rarely name this directly; {@link PageProps} applies it for you.\n *\n * @typeParam P - The literal route path, e.g. `'/users/:id/posts/:postId'`.\n *\n * @example\n * ```ts\n * type P = PathParams<'/users/:id/posts/:postId'>; // { id: string; postId: string }\n * ```\n *\n * @see {@link https://hono.dev/docs/api/routing#path-parameter | Hono — path parameters}\n */\nexport type PathParams<P extends string> =\n  ParamKeys<P> extends never ? Record<string, never> : Simplify<UnionToIntersection<ParamKeyToRecord<ParamKeys<P>>>>;\n\n/**\n * Props every page component receives. Pass the route's path as the type argument to get `params`\n * typed key-by-key; without it `params` falls back to an open `Record<string, string>`.\n *\n * `defineRoutes` checks each page's props against `PageProps<path>`, so a mismatched path literal is\n * a type error at the route definition. `url` and `params` mirror what `useNavigation()` gives a\n * `'use client'` component, so a read moves across the server/client line unchanged.\n *\n * @typeParam Path - The literal path this page is mounted at, e.g. `'/profile/:id'`.\n * @typeParam E - The app's Hono {@link Env}, to type {@link RequestContext.var} and\n *   {@link RequestContext.env} on {@link PageProps.ctx}.\n *\n * @example\n * ```tsx\n * import type { PageProps } from '@rshono/core';\n *\n * export default async function Profile({ params, url }: PageProps<'/profile/:id'>) {\n *   const user = await db.getUser(params.id); // params.id is string\n *   const tab = url.searchParams.get('tab') ?? 'overview';\n *   return <Layout>{user.name} — {tab}</Layout>;\n * }\n * ```\n *\n * @see {@link https://www.rshono.com/docs/pages#page-props | Docs — page props}\n */\nexport interface PageProps<Path extends string = string, E extends Env = Env> {\n  /**\n   * The absolute browser-facing request {@link URL}, proxy-header aware (`X-Forwarded-Host` /\n   * `-Proto`). A fresh instance per request, so mutating it is local to the page; it is not\n   * serializable, so hand a `'use client'` component `url.href` rather than `url`.\n   *\n   * On a `render: 'static'` route this is the build-time URL — rendered once against `siteUrl`, so the\n   * origin is `siteUrl`'s and `url.searchParams` is always empty, on first paint and after a soft\n   * navigation alike. **`useNavigation().url` is the same frozen URL, not a way around it**: the payload\n   * carries one `href` and both readings come from it. The fragment is the one part no payload can carry\n   * — a browser never sends `#…` with the request — so this prop never has one, while\n   * `useNavigation().url.hash` is read from the browser after hydration. Mark the route\n   * `render: 'dynamic'` if the page depends on the query; a `'use client'` component that only wants it\n   * after hydration can read `location.search` in an effect.\n   */\n  url: URL;\n  /** Matched route params for this request, e.g. `{ id: '42' }` for `/profile/:id`. */\n  params: string extends Path ? Record<string, string> : PathParams<Path>;\n  /**\n   * The request context — the object `getRequestContext()` returns, handed to the page so cookies,\n   * headers, env and middleware variables are reachable without an import.\n   *\n   * Server-only, non-enumerable (a `{...props}` spread and `JSON.stringify` both skip it) and never\n   * serialized. Passing it to a `'use client'` component fails the render, because it wraps the live\n   * request — read what you need here and pass plain values down.\n   *\n   * Non-enumerable is the one place this API breaks a JavaScript expectation, and it is unavoidable: an\n   * enumerable `ctx` would put `ctx.hono.env` — every binding and secret — into React's dev-only\n   * serialization of a server component's props, which walks own enumerable properties. So `<Child\n   * {...props} />` hands a **server** child `ctx: undefined` with no error, while the type says otherwise.\n   * Nested server components are meant to call `getRequestContext()` for the same object rather than\n   * receive it, which is also the fix if a spread has already cost you an afternoon.\n   *\n   * Reading it on a `render: 'static'` route throws: a prerendered page has no per-request context.\n   * Mark the route `render: 'dynamic'`, or use the `url` / `params` props.\n   *\n   * @example\n   * ```tsx\n   * export default function Dashboard({ ctx }: PageProps) {\n   *   const session = ctx.cookies.get('session');\n   *   if (!session) redirect('/login');\n   *   return <Layout>Signed in as {session}</Layout>;\n   * }\n   * ```\n   */\n  ctx: RequestContext<E>;\n}\n\n/**\n * A page: a React **server component** rendering the entire document (`<html>…</html>`), usually via\n * a shared layout. It may be `async` and await data directly.\n *\n * Each page module default-exports exactly one. Interactive parts belong in `'use client'` components\n * the page imports — only those ship JS.\n *\n * @typeParam P - The component's props; for a page these are {@link PageProps}.\n *\n * @see {@link https://react.dev/reference/rsc/server-components | React — Server Components}\n * @see {@link https://www.rshono.com/docs/pages | Docs — pages}\n */\n// `any`, not `unknown`: this default is what an unparameterised `PageComponent` means in a user's own\n// annotation, and `unknown` props would reject every component that declares the props it actually takes.\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type PageComponent<P = any> = (props: P) => ReactNode | Promise<ReactNode>;\n\n/**\n * The shape an `{ type: 'endpoint' }` route's server module must have: a single named `handler`\n * export. It only ever loads on the server, so importing a database client or reading secrets from it\n * is safe.\n *\n * @example\n * ```ts\n * // src/health.ts\n * import type { Handler } from 'hono';\n *\n * export const handler: Handler = (c) => c.json({ ok: true });\n * ```\n *\n * @see {@link https://www.rshono.com/docs/routing#endpoint-routes | Docs — endpoint routes}\n */\nexport interface EndpointServerModule {\n  /**\n   * A Hono {@link Handler} for every request the route matches. It is passed Hono's `Context`, so the\n   * request, the response builders (`c.json`, `c.text`, `c.body`) and middleware variables are all\n   * reached through it.\n   *\n   * @see {@link https://hono.dev/docs/api/context | Hono — Context}\n   */\n  handler: Handler;\n}\n\n/**\n * A page route — a path rendered by a server component. This is the default\n * route kind, so `type` can be omitted.\n *\n * @example\n * ```ts\n * { path: '/profile/:id', component: () => import('./components/profile') }\n * ```\n */\nexport interface PageRoute {\n  /** Discriminates a page from an endpoint; optional because `'page'` is the default. */\n  type?: 'page';\n  /**\n   * Hono-style path pattern, e.g. `/`, `/profile/:id`, `/files/*`. Routes are matched in\n   * declaration order.\n   *\n   * @see {@link https://hono.dev/docs/api/routing | Hono — routing}\n   */\n  path: string;\n  /**\n   * Dynamic import of the page module, whose default export is the {@link PageComponent}.\n   *\n   * Write it inline as `() => import('…')`: the framework detects that exact form and injects the\n   * `'use server-entry'` directive that attaches the page's client JS and CSS. Wire the component up\n   * any other way — a variable, a barrel re-export, a computed specifier — and you have to put\n   * `'use server-entry'` on the page module's first line yourself.\n   *\n   * @example\n   * ```ts\n   * component: () => import('./components/profile')\n   * ```\n   *\n   * @see {@link https://www.rshono.com/docs/pages#the-use-server-entry-directive | Docs — the `'use server-entry'` directive}\n   */\n  component: () => Promise<{ default: PageComponent }>;\n  /** `'static'` prerenders the route at build time; `'dynamic'` (the default) renders per request. */\n  render?: 'static' | 'dynamic';\n  /**\n   * For a `render: 'static'` route with params: the param sets to prerender, one page each. Runs at\n   * build time on the server, so it may hit a database or read the filesystem.\n   *\n   * A parameterised static route without this falls back to rendering per request, with a build\n   * warning. Wildcard (`*`), optional and regex params cannot be prerendered.\n   *\n   * **Every value has to be one portable file name**, since that is what a prerendered page is stored as,\n   * and the build fails naming the value rather than writing a page nothing will serve. So: no\n   * `\\ / : * ? \" < > |` or control characters, no trailing `.` or space, and not a reserved Windows device\n   * name (`CON`, `NUL`, `COM1`, …) — the last two enforced everywhere, so a build that works on macOS is\n   * not one that fails in CI on Windows.\n   *\n   * @example\n   * ```ts\n   * {\n   *   path: '/docs/:slug',\n   *   render: 'static',\n   *   component: () => import('./components/documentation'),\n   *   staticPaths: async () => (await db.docs.all()).map((d) => ({ slug: d.slug })),\n   * }\n   * ```\n   *\n   * @see {@link https://www.rshono.com/docs/routing#static-rendering | Docs — static rendering}\n   */\n  staticPaths?: () => Array<Record<string, string>> | Promise<Array<Record<string, string>>>;\n}\n\n/**\n * An endpoint route — a path served by a raw Hono handler instead of a React\n * component. Use it for JSON APIs, webhooks, redirects, feeds, or anything that\n * isn't an HTML page.\n *\n * @example\n * ```ts\n * { type: 'endpoint', path: '/api/health', server: () => import('./health') }\n * ```\n *\n * @see {@link https://www.rshono.com/docs/routing#endpoint-routes | Docs — endpoint routes}\n */\nexport interface EndpointRoute {\n  /** Marks this route as an endpoint rather than a page. Required. */\n  type: 'endpoint';\n  /**\n   * Hono-style path pattern, e.g. `/api/health`, `/api/users/:id`.\n   *\n   * @see {@link https://hono.dev/docs/api/routing | Hono — routing}\n   */\n  path: string;\n  /**\n   * HTTP method to match, or a list of them. Defaults to `'all'` — every method.\n   *\n   * There is no `'head'`: Hono dispatches a `HEAD` as a `GET` and strips the body off the response, so a\n   * `HEAD` is already answered by the `'get'` handler (and by `'all'`), and a route registered for `HEAD`\n   * alone would never be reached.\n   *\n   * A list is how a two-method endpoint says so; `'all'` inside one is refused, since it is either the\n   * whole thing or a mistake. A method the route does not name gets Hono's 404 rather than the handler.\n   *\n   * @example\n   * ```ts\n   * { type: 'endpoint', path: '/api/session', method: ['get', 'delete'], server: () => import('./session') }\n   * ```\n   */\n  method?: HTTPMethod | readonly HTTPMethod[];\n  /** Dynamic import of the {@link EndpointServerModule} exporting `handler`. */\n  server: () => Promise<EndpointServerModule>;\n}\n\n/**\n * HTTP methods an {@link EndpointRoute} can match. `'all'` matches every method.\n *\n * No `'head'`, deliberately — see {@link EndpointRoute.method}. A `HEAD` reaches the `'get'` handler.\n */\nexport type HTTPMethod = 'get' | 'post' | 'put' | 'patch' | 'delete' | 'options' | 'all';\n\n/** Any entry in the `routes` array: a {@link PageRoute} or an {@link EndpointRoute}. */\nexport type Route = PageRoute | EndpointRoute;\n\n/**\n * Narrows a {@link Route} to a {@link PageRoute} — `type` is optional on page routes, so anything not\n * explicitly `'endpoint'` is one.\n *\n * @internal\n */\nexport function isPageRoute(route: Route): route is PageRoute {\n  return route.type !== 'endpoint';\n}\n\n/**\n * A page the framework falls back to rather than routes to — `notFound` and `error` in\n * {@link RouteConfig}. Same contract as a {@link PageRoute} `component`, without a path of its own.\n */\nexport interface FallbackPage {\n  /** Dynamic import of the page module; its default export is the {@link PageComponent}. */\n  component: () => Promise<{ default: PageComponent }>;\n}\n\n/**\n * The error detail handed to the `error` page. Redacted in production — a generic\n * `'Internal Server Error'` and no `stack`; in dev, the real message and stack.\n */\nexport interface ErrorPageInfo {\n  /** The thrown error's message in dev; `'Internal Server Error'` in production. */\n  message: string;\n  /**\n   * The stack trace — **dev only**, and `undefined` in every build. Optional for that reason rather than\n   * because some errors lack one, so a page that renders it should guard on it, not on a mode flag.\n   */\n  stack?: string;\n}\n\n/**\n * Props for the `error` page declared in {@link RouteConfig.error} — the usual {@link PageProps} plus\n * the redaction-aware {@link ErrorPageInfo}.\n *\n * In a build `error.message` is the generic `'Internal Server Error'` and `error.stack` is `undefined`, so\n * the page below guards on the stack rather than on a mode flag — there is no mode flag to guard on.\n *\n * @typeParam E - The app's Hono {@link Env}, forwarded to {@link PageProps.ctx}.\n *\n * @example\n * ```tsx\n * import type { ErrorPageProps } from '@rshono/core';\n *\n * export default function ServerError({ error }: ErrorPageProps) {\n *   return (\n *     <html>\n *       <body>\n *         <h1>Something went wrong</h1>\n *         <p>{error.message}</p>\n *         {error.stack && <pre>{error.stack}</pre>}\n *       </body>\n *     </html>\n *   );\n * }\n * ```\n */\nexport type ErrorPageProps<E extends Env = Env> = PageProps<string, E> & {\n  /** The error that failed the request, redacted in production — see {@link ErrorPageInfo}. */\n  error: ErrorPageInfo;\n};\n\n/**\n * The object form accepted by {@link defineRoutes}: the route table plus the two\n * optional framework-owned pages.\n *\n * @typeParam TRoutes - Inferred tuple of route literals, which is what makes the\n *   per-route `path` → props check possible.\n *\n * @see {@link https://www.rshono.com/docs/routing#notfound-and-error | Docs — notFound and error pages}\n */\nexport interface RouteConfig<TRoutes extends readonly Route[] = readonly Route[]> {\n  /** Every page and endpoint in the app, matched in order. */\n  routes: TRoutes;\n  /** Page rendered with a 404 status for unmatched paths and for `notFound()` calls. */\n  notFound?: FallbackPage;\n  /**\n   * Page rendered with a 500 status when a request throws — a page component, a page module that will not\n   * load, an endpoint, a server action, or middleware. Receives {@link ErrorPageProps}.\n   *\n   * It is a *fresh* render, with its own flight payload, so it hydrates and behaves like any other page.\n   * An app that declares none gets the framework's plain 500 document instead. If the `error` page itself\n   * throws, that is reported too and the framework's document answers.\n   */\n  error?: FallbackPage;\n}\n\n/**\n * The same check for `staticPaths`, whose param sets have to fill the route's own path: a key that does not\n * is otherwise a build-time throw from `interpolatePath` rather than a type error.\n *\n * Keys only, not full assignability, because the declared field type is `Record<string, string>` and a\n * `staticPaths` annotated as returning exactly that has to stay accepted — an index signature carries no\n * key to check, so it passes. Skipped where the path has no params, because `staticPaths` is not called for\n * such a route at all and an error there would be about the wrong thing.\n */\ntype ValidateStaticPaths<R, P extends string> =\n  ParamKeys<P> extends never\n    ? R\n    : R extends { staticPaths: () => infer Sets }\n      ? Awaited<Sets> extends ReadonlyArray<infer Set>\n        ? [keyof PathParams<P>] extends [keyof Set]\n          ? R\n          : R & { staticPaths: `every param set staticPaths returns needs the params of '${P}'` }\n        : R\n      : R;\n\n// `PageProps<P, any>`, not `PageProps<P>`: only the *path* is being checked, and pinning the Env would\n// fail every page that declares its own (`PageProps<'/x', MyEnv>`, to type `ctx.var`).\ntype ValidateRoute<R> = R extends {\n  path: infer P extends string;\n  component: () => Promise<{ default: PageComponent<infer CP> }>;\n}\n  ? // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the Env is deliberately unpinned; see above.\n    [PageProps<P, any>] extends [CP]\n    ? ValidateStaticPaths<R, P>\n    : R & { component: `component props are not satisfied by PageProps<'${P}'>` }\n  : R;\n\ntype ValidateRoutes<TRoutes extends readonly Route[]> = { [K in keyof TRoutes]: ValidateRoute<TRoutes[K]> };\n\n/**\n * Refuses a key that is not a {@link RouteConfig} field — a typo'd `notfound` is otherwise a fallback page\n * that never renders, and nothing at runtime looks for one.\n *\n * Excess-property checking did this while the object form was an overload of its own with a concrete\n * parameter type. It cannot once the parameter is generic and inferred from the argument, because the\n * inferred type *has* the extra key. The message here is the better one anyway: it lands on the field.\n */\ntype ValidateConfigKeys<T> =\n  Exclude<keyof T, keyof RouteConfig> extends never\n    ? T\n    : T & Record<Exclude<keyof T, keyof RouteConfig>, 'not a defineRoutes field — the fields are routes, notFound and error'>;\n\n/** The check for whichever of the two accepted shapes was passed. */\ntype ValidateInput<T> = T extends readonly Route[]\n  ? ValidateRoutes<T>\n  : T extends { routes: infer R extends readonly Route[] }\n    ? ValidateConfigKeys<T> & { routes: ValidateRoutes<R> }\n    : T;\n\n/** The route tuple inside either shape, so the return type carries the literals through both. */\ntype RoutesOf<T> = T extends readonly Route[] ? T : T extends { routes: infer R extends readonly Route[] } ? R : readonly Route[];\n\n/**\n * Declares the app's route table. Export the result as `routes` from `src/routes.ts` — the one file\n * rshono requires. It only ever runs on the server, so importing server-only modules from it (inside\n * `staticPaths`, say) is safe.\n *\n * Takes a {@link RouteConfig} — the `routes` array plus the optional `notFound` and `error` pages — or a\n * bare {@link Route} array as shorthand for an app with neither.\n *\n * Beyond typing the config, every page is cross-checked against its own path: props not satisfied by\n * `PageProps<'<its path>'>` make the `component` field a type error, and a `staticPaths` whose param sets do\n * not fill the path makes that field one.\n *\n * **One signature over both shapes, deliberately.** The array form used to be a second overload, which meant\n * a mistake inside a bare array was reported as an overload-resolution failure whose *first* line was the\n * object form's complaint — \"Property 'routes' is missing\" — pointing at a change the author should not make.\n * The real message was on line 8. A single signature reports the argument once, at the field that is wrong.\n *\n * @param input - A {@link RouteConfig}, or the bare `routes` array.\n * @returns The config, unchanged and fully typed; an array is wrapped as `{ routes }`.\n *\n * @example\n * ```ts\n * // src/routes.ts\n * import { defineRoutes } from '@rshono/core';\n *\n * export const routes = defineRoutes({\n *   routes: [\n *     { path: '/', component: () => import('./components/home') },\n *     { path: '/profile/:id', component: () => import('./components/profile') },\n *     {\n *       path: '/docs/:slug',\n *       render: 'static',\n *       component: () => import('./components/documentation'),\n *       staticPaths: async () => [{ slug: 'getting-started' }, { slug: 'deployment' }],\n *     },\n *     { type: 'endpoint', path: '/api/health', server: () => import('./health') },\n *   ],\n *   notFound: { component: () => import('./components/404') },\n *   error: { component: () => import('./components/500') },\n * });\n * ```\n *\n * @example\n * ```ts\n * // The shorthand, for an app with no notFound or error page.\n * export const routes = defineRoutes([{ path: '/', component: () => import('./components/home') }]);\n * ```\n *\n * @see {@link https://www.rshono.com/docs/routing | Docs — routing}\n */\nexport function defineRoutes<const T extends readonly Route[] | RouteConfig<readonly Route[]>>(input: T & ValidateInput<T>): RouteConfig<RoutesOf<T>>;\nexport function defineRoutes(input: readonly Route[] | RouteConfig): RouteConfig {\n  return Array.isArray(input) ? { routes: input } : (input as RouteConfig);\n}\n"]}

package/dist/runtime/navigation.d.ts

@@ -39,6 +39,12 @@ export interface NavigationState {
     /**
      * The full current {@link URL}. A fresh instance per navigation, so mutating it affects nothing else
      * — it is not written back to the address bar.
+     *
+     * The path, query and origin travel in the page payload, but the fragment cannot: a browser leaves `#…`
+     * out of the request line, so the server renders every page without one. `url.hash` is therefore read
+     * from the browser after hydration and follows `hashchange` — an in-page link, Back/Forward between
+     * anchors of one document, or opening the document at one. Nothing else about the URL is affected; see
+     * {@link useNavigation} for the `render: 'static'` case.
      */
     url: URL;
     /** Matched route params for the current page, e.g. `{ id: '42' }` for `/profile/:id`. */
@@ -71,11 +77,16 @@ export declare function RouterProvider({ href, params, children }: {
  * during SSR — no hydration flicker — and update on every navigation. `router` holds the imperative
  * actions plus a `pending` flag, `true` while a soft navigation is in flight.
  *
+ * The fragment is the exception the payload cannot cover: a browser never sends `#…` to the server, so
+ * `url.hash` is read from the address bar after hydration and kept in sync on `hashchange` — an in-page
+ * link, Back/Forward between anchors, or opening the document at `#section` — with no request either way.
+ * Everything before the `#` remains what the payload carried.
+ *
  * **On a `render: 'static'` route `url` is frozen at build time**, origin included and query empty. The
  * payload is one prerendered set of bytes and this reads the `href` in it, so it is the page's own
- * `PageProps.url` — the same value, not a live one. A page whose output depends on the query wants
- * `render: 'dynamic'`; a component that only needs it after hydration can read `location.search` in an
- * effect.
+ * `PageProps.url` — the same value, not a live one, `url.hash` aside. A page whose output depends on the
+ * query wants `render: 'dynamic'`; a component that only needs it after hydration can read
+ * `location.search` in an effect.
  *
  * Hooks can't run in a server component; read the same data there from `getRequestContext()`.
  *

package/dist/runtime/navigation.js

@@ -1,6 +1,6 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useContext, useMemo } from 'react';
+import { createContext, useContext, useMemo, useSyncExternalStore } from 'react';
 const noop = () => { };
 const defaultRouter = { push: noop, replace: noop, back: noop, forward: noop, refresh: noop, pending: false };
 /**
@@ -10,6 +10,27 @@ const defaultRouter = { push: noop, replace: noop, back: noop, forward: noop, re
  */
 export const RouterContext = createContext(defaultRouter);
 const NavigationContext = createContext(null);
+/**
+ * The browser's fragment navigation: the one part of the address a payload can never carry, and the one part
+ * that can move without a page data request. `hashchange` is every way it moves within a document — an
+ * in-page link, Back/Forward between anchors of one page, opening the document at `#section` covered by the
+ * post-hydration check `useSyncExternalStore` makes for a changed snapshot. A cross-page `#anchor` commits a
+ * payload instead; the re-render that follows reads the fragment then.
+ */
+function subscribeToHash(onStoreChange) {
+    window.addEventListener('hashchange', onStoreChange);
+    return () => window.removeEventListener('hashchange', onStoreChange);
+}
+/** The live fragment, `#…` included, or `''`. */
+const readHash = () => window.location.hash;
+/**
+ * What the fragment reads as while the server snapshot is in use — server render and hydration. The server
+ * never saw one, so the payload's URL has none; answering with the live fragment here would render markup
+ * the server did not and fail hydration. The empty string is exactly what the payload carries, and the
+ * post-hydration re-render that `useSyncExternalStore` performs for a changed snapshot is where the
+ * browser's own arrives.
+ */
+const readServerHash = () => '';
 /**
  * Publishes the per-render location and params for {@link useNavigation} to read. The RSC entry wraps
  * every page in one.
@@ -18,7 +39,14 @@ const NavigationContext = createContext(null);
  */
 export function RouterProvider({ href, params, children }) {
     const router = useContext(RouterContext);
-    const value = useMemo(() => ({ url: new URL(href), params, router }), [href, params, router]);
+    // `href` is the payload's URL — see `subscribeToHash` — so the browser's fragment is applied on top of it.
+    // This is the only client-side part of `url`; path, query and origin stay exactly what the payload said.
+    const hash = useSyncExternalStore(subscribeToHash, readHash, readServerHash);
+    const value = useMemo(() => {
+        const url = new URL(href);
+        url.hash = hash;
+        return { url, params, router };
+    }, [href, hash, params, router]);
     return _jsx(NavigationContext.Provider, { value: value, children: children });
 }
 /**
@@ -29,11 +57,16 @@ export function RouterProvider({ href, params, children }) {
  * during SSR — no hydration flicker — and update on every navigation. `router` holds the imperative
  * actions plus a `pending` flag, `true` while a soft navigation is in flight.
  *
+ * The fragment is the exception the payload cannot cover: a browser never sends `#…` to the server, so
+ * `url.hash` is read from the address bar after hydration and kept in sync on `hashchange` — an in-page
+ * link, Back/Forward between anchors, or opening the document at `#section` — with no request either way.
+ * Everything before the `#` remains what the payload carried.
+ *
  * **On a `render: 'static'` route `url` is frozen at build time**, origin included and query empty. The
  * payload is one prerendered set of bytes and this reads the `href` in it, so it is the page's own
- * `PageProps.url` — the same value, not a live one. A page whose output depends on the query wants
- * `render: 'dynamic'`; a component that only needs it after hydration can read `location.search` in an
- * effect.
+ * `PageProps.url` — the same value, not a live one, `url.hash` aside. A page whose output depends on the
+ * query wants `render: 'dynamic'`; a component that only needs it after hydration can read
+ * `location.search` in an effect.
  *
  * Hooks can't run in a server component; read the same data there from `getRequestContext()`.
  *

package/dist/runtime/navigation.js.map

@@ -1 +1 @@
-{"version":3,"file":"navigation.js","sourceRoot":"","sources":["../../src/runtime/navigation.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,OAAO,EAAkB,MAAM,OAAO,CAAC;AAmD3E,MAAM,IAAI,GAAG,GAAG,EAAE,GAAE,CAAC,CAAC;AAEtB,MAAM,aAAa,GAAqB,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAEhI;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAAmB,aAAa,CAAC,CAAC;AAE5E,MAAM,iBAAiB,GAAG,aAAa,CAAyB,IAAI,CAAC,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAyE;IAC9H,MAAM,MAAM,GAAG,UAAU,CAAC,aAAa,CAAC,CAAC;IACzC,MAAM,KAAK,GAAG,OAAO,CAAkB,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAE/G,OAAO,KAAC,iBAAiB,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YAAG,QAAQ,GAA8B,CAAC;AAC3F,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,KAAK,GAAG,UAAU,CAAC,iBAAiB,CAAC,CAAC;IAC5C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,mKAAmK,CACpK,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC","sourcesContent":["'use client';\n\nimport { createContext, useContext, useMemo, type ReactNode } from 'react';\n\n/**\n * Imperative navigation actions, reached as `useNavigation().router`.\n *\n * Every action is a **soft** navigation: the page's flight payload is fetched and applied in place, so\n * client component state outside the changed subtree survives. Off-site hrefs — and a traversal that leaves\n * the app — fall back to a full load.\n *\n * Soft navigation is the browser's\n * {@link https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API | Navigation API}; where that is\n * missing, every action below is still correct and simply performs a real browser load.\n *\n * @example\n * ```tsx\n * const { router } = useNavigation();\n * router.push('/dashboard');    // navigate, new history entry\n * router.replace('/login');     // navigate, no new entry\n * router.back();                // one entry back, as the browser's button does\n * router.forward();             // one entry forward\n * router.refresh();             // re-run this route's server components\n * ```\n */\nexport interface NavigationRouter {\n  /** Navigates to `href` and pushes a new history entry. */\n  push(href: string): void;\n  /** Navigates to `href`, replacing the current history entry instead of adding one. */\n  replace(href: string): void;\n  /** Steps one entry back in the browser's session history. Nothing to go back to is a no-op. */\n  back(): void;\n  /** Steps one entry forward in the browser's session history. A no-op on the newest entry. */\n  forward(): void;\n  /** Re-fetches the current route from the server, re-running its server components. */\n  refresh(): void;\n  /** `true` while a soft navigation is in flight — use it to disable controls or show a spinner. */\n  pending: boolean;\n}\n\n/** The current location plus the {@link NavigationRouter}, as returned by {@link useNavigation}. */\nexport interface NavigationState {\n  /**\n   * The full current {@link URL}. A fresh instance per navigation, so mutating it affects nothing else\n   * — it is not written back to the address bar.\n   */\n  url: URL;\n  /** Matched route params for the current page, e.g. `{ id: '42' }` for `/profile/:id`. */\n  params: Record<string, string>;\n  /** Imperative navigation actions and the `pending` flag. */\n  router: NavigationRouter;\n}\n\nconst noop = () => {};\n\nconst defaultRouter: NavigationRouter = { push: noop, replace: noop, back: noop, forward: noop, refresh: noop, pending: false };\n\n/**\n * Carries the live {@link NavigationRouter} from the hydration runtime down to {@link RouterProvider}.\n *\n * @internal\n */\nexport const RouterContext = createContext<NavigationRouter>(defaultRouter);\n\nconst NavigationContext = createContext<NavigationState | null>(null);\n\n/**\n * Publishes the per-render location and params for {@link useNavigation} to read. The RSC entry wraps\n * every page in one.\n *\n * @internal\n */\nexport function RouterProvider({ href, params, children }: { href: string; params: Record<string, string>; children: ReactNode }) {\n  const router = useContext(RouterContext);\n  const value = useMemo<NavigationState>(() => ({ url: new URL(href), params, router }), [href, params, router]);\n\n  return <NavigationContext.Provider value={value}>{children}</NavigationContext.Provider>;\n}\n\n/**\n * Reactive access to the current URL and programmatic navigation, in one hook. Call it from a\n * `'use client'` component.\n *\n * `url` and `params` are computed on the server and travel in the flight payload, so they are correct\n * during SSR — no hydration flicker — and update on every navigation. `router` holds the imperative\n * actions plus a `pending` flag, `true` while a soft navigation is in flight.\n *\n * **On a `render: 'static'` route `url` is frozen at build time**, origin included and query empty. The\n * payload is one prerendered set of bytes and this reads the `href` in it, so it is the page's own\n * `PageProps.url` — the same value, not a live one. A page whose output depends on the query wants\n * `render: 'dynamic'`; a component that only needs it after hydration can read `location.search` in an\n * effect.\n *\n * Hooks can't run in a server component; read the same data there from `getRequestContext()`.\n *\n * @example\n * ```tsx\n * 'use client';\n * import { useNavigation } from '@rshono/core/client';\n *\n * export function NextPage() {\n *   const { url, router } = useNavigation();\n *   const page = Number(url.searchParams.get('page') ?? '1');\n *   return (\n *     <button disabled={router.pending} onClick={() => router.push(`${url.pathname}?page=${page + 1}`)}>\n *       Next {router.pending ? '…' : ''}\n *     </button>\n *   );\n * }\n * ```\n *\n * @returns The current {@link NavigationState}: `url` and `params`, plus `router`\n * ({@link NavigationRouter}) with `push` / `replace` / `back` / `forward` / `refresh` / `pending`.\n * @throws If called outside a page's React tree, where there is no navigation\n *   context to read.\n *\n * @see {@link https://www.rshono.com/docs/api#rshonocoreclient | Docs — `@rshono/core/client`}\n * @see {@link https://www.rshono.com/docs/pages#client-components | Docs — client components}\n */\nexport function useNavigation(): NavigationState {\n  const value = useContext(NavigationContext);\n  if (!value) {\n    throw new Error(\n      \"[rshono] useNavigation() must be called inside a 'use client' component rendered by a page. In a server component, read the URL from getRequestContext() instead.\",\n    );\n  }\n  return value;\n}\n"]}
+{"version":3,"file":"navigation.js","sourceRoot":"","sources":["../../src/runtime/navigation.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,OAAO,EAAE,oBAAoB,EAAkB,MAAM,OAAO,CAAC;AAyDjG,MAAM,IAAI,GAAG,GAAG,EAAE,GAAE,CAAC,CAAC;AAEtB,MAAM,aAAa,GAAqB,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAEhI;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAAmB,aAAa,CAAC,CAAC;AAE5E,MAAM,iBAAiB,GAAG,aAAa,CAAyB,IAAI,CAAC,CAAC;AAEtE;;;;;;GAMG;AACH,SAAS,eAAe,CAAC,aAAyB;IAChD,MAAM,CAAC,gBAAgB,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC;IACrD,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC;AACvE,CAAC;AAED,iDAAiD;AACjD,MAAM,QAAQ,GAAG,GAAW,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,cAAc,GAAG,GAAW,EAAE,CAAC,EAAE,CAAC;AAExC;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAyE;IAC9H,MAAM,MAAM,GAAG,UAAU,CAAC,aAAa,CAAC,CAAC;IACzC,2GAA2G;IAC3G,yGAAyG;IACzG,MAAM,IAAI,GAAG,oBAAoB,CAAC,eAAe,EAAE,QAAQ,EAAE,cAAc,CAAC,CAAC;IAC7E,MAAM,KAAK,GAAG,OAAO,CAAkB,GAAG,EAAE;QAC1C,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1B,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;QAChB,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjC,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAEjC,OAAO,KAAC,iBAAiB,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YAAG,QAAQ,GAA8B,CAAC;AAC3F,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,KAAK,GAAG,UAAU,CAAC,iBAAiB,CAAC,CAAC;IAC5C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,mKAAmK,CACpK,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC","sourcesContent":["'use client';\n\nimport { createContext, useContext, useMemo, useSyncExternalStore, type ReactNode } from 'react';\n\n/**\n * Imperative navigation actions, reached as `useNavigation().router`.\n *\n * Every action is a **soft** navigation: the page's flight payload is fetched and applied in place, so\n * client component state outside the changed subtree survives. Off-site hrefs — and a traversal that leaves\n * the app — fall back to a full load.\n *\n * Soft navigation is the browser's\n * {@link https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API | Navigation API}; where that is\n * missing, every action below is still correct and simply performs a real browser load.\n *\n * @example\n * ```tsx\n * const { router } = useNavigation();\n * router.push('/dashboard');    // navigate, new history entry\n * router.replace('/login');     // navigate, no new entry\n * router.back();                // one entry back, as the browser's button does\n * router.forward();             // one entry forward\n * router.refresh();             // re-run this route's server components\n * ```\n */\nexport interface NavigationRouter {\n  /** Navigates to `href` and pushes a new history entry. */\n  push(href: string): void;\n  /** Navigates to `href`, replacing the current history entry instead of adding one. */\n  replace(href: string): void;\n  /** Steps one entry back in the browser's session history. Nothing to go back to is a no-op. */\n  back(): void;\n  /** Steps one entry forward in the browser's session history. A no-op on the newest entry. */\n  forward(): void;\n  /** Re-fetches the current route from the server, re-running its server components. */\n  refresh(): void;\n  /** `true` while a soft navigation is in flight — use it to disable controls or show a spinner. */\n  pending: boolean;\n}\n\n/** The current location plus the {@link NavigationRouter}, as returned by {@link useNavigation}. */\nexport interface NavigationState {\n  /**\n   * The full current {@link URL}. A fresh instance per navigation, so mutating it affects nothing else\n   * — it is not written back to the address bar.\n   *\n   * The path, query and origin travel in the page payload, but the fragment cannot: a browser leaves `#…`\n   * out of the request line, so the server renders every page without one. `url.hash` is therefore read\n   * from the browser after hydration and follows `hashchange` — an in-page link, Back/Forward between\n   * anchors of one document, or opening the document at one. Nothing else about the URL is affected; see\n   * {@link useNavigation} for the `render: 'static'` case.\n   */\n  url: URL;\n  /** Matched route params for the current page, e.g. `{ id: '42' }` for `/profile/:id`. */\n  params: Record<string, string>;\n  /** Imperative navigation actions and the `pending` flag. */\n  router: NavigationRouter;\n}\n\nconst noop = () => {};\n\nconst defaultRouter: NavigationRouter = { push: noop, replace: noop, back: noop, forward: noop, refresh: noop, pending: false };\n\n/**\n * Carries the live {@link NavigationRouter} from the hydration runtime down to {@link RouterProvider}.\n *\n * @internal\n */\nexport const RouterContext = createContext<NavigationRouter>(defaultRouter);\n\nconst NavigationContext = createContext<NavigationState | null>(null);\n\n/**\n * The browser's fragment navigation: the one part of the address a payload can never carry, and the one part\n * that can move without a page data request. `hashchange` is every way it moves within a document — an\n * in-page link, Back/Forward between anchors of one page, opening the document at `#section` covered by the\n * post-hydration check `useSyncExternalStore` makes for a changed snapshot. A cross-page `#anchor` commits a\n * payload instead; the re-render that follows reads the fragment then.\n */\nfunction subscribeToHash(onStoreChange: () => void): () => void {\n  window.addEventListener('hashchange', onStoreChange);\n  return () => window.removeEventListener('hashchange', onStoreChange);\n}\n\n/** The live fragment, `#…` included, or `''`. */\nconst readHash = (): string => window.location.hash;\n\n/**\n * What the fragment reads as while the server snapshot is in use — server render and hydration. The server\n * never saw one, so the payload's URL has none; answering with the live fragment here would render markup\n * the server did not and fail hydration. The empty string is exactly what the payload carries, and the\n * post-hydration re-render that `useSyncExternalStore` performs for a changed snapshot is where the\n * browser's own arrives.\n */\nconst readServerHash = (): string => '';\n\n/**\n * Publishes the per-render location and params for {@link useNavigation} to read. The RSC entry wraps\n * every page in one.\n *\n * @internal\n */\nexport function RouterProvider({ href, params, children }: { href: string; params: Record<string, string>; children: ReactNode }) {\n  const router = useContext(RouterContext);\n  // `href` is the payload's URL — see `subscribeToHash` — so the browser's fragment is applied on top of it.\n  // This is the only client-side part of `url`; path, query and origin stay exactly what the payload said.\n  const hash = useSyncExternalStore(subscribeToHash, readHash, readServerHash);\n  const value = useMemo<NavigationState>(() => {\n    const url = new URL(href);\n    url.hash = hash;\n    return { url, params, router };\n  }, [href, hash, params, router]);\n\n  return <NavigationContext.Provider value={value}>{children}</NavigationContext.Provider>;\n}\n\n/**\n * Reactive access to the current URL and programmatic navigation, in one hook. Call it from a\n * `'use client'` component.\n *\n * `url` and `params` are computed on the server and travel in the flight payload, so they are correct\n * during SSR — no hydration flicker — and update on every navigation. `router` holds the imperative\n * actions plus a `pending` flag, `true` while a soft navigation is in flight.\n *\n * The fragment is the exception the payload cannot cover: a browser never sends `#…` to the server, so\n * `url.hash` is read from the address bar after hydration and kept in sync on `hashchange` — an in-page\n * link, Back/Forward between anchors, or opening the document at `#section` — with no request either way.\n * Everything before the `#` remains what the payload carried.\n *\n * **On a `render: 'static'` route `url` is frozen at build time**, origin included and query empty. The\n * payload is one prerendered set of bytes and this reads the `href` in it, so it is the page's own\n * `PageProps.url` — the same value, not a live one, `url.hash` aside. A page whose output depends on the\n * query wants `render: 'dynamic'`; a component that only needs it after hydration can read\n * `location.search` in an effect.\n *\n * Hooks can't run in a server component; read the same data there from `getRequestContext()`.\n *\n * @example\n * ```tsx\n * 'use client';\n * import { useNavigation } from '@rshono/core/client';\n *\n * export function NextPage() {\n *   const { url, router } = useNavigation();\n *   const page = Number(url.searchParams.get('page') ?? '1');\n *   return (\n *     <button disabled={router.pending} onClick={() => router.push(`${url.pathname}?page=${page + 1}`)}>\n *       Next {router.pending ? '…' : ''}\n *     </button>\n *   );\n * }\n * ```\n *\n * @returns The current {@link NavigationState}: `url` and `params`, plus `router`\n * ({@link NavigationRouter}) with `push` / `replace` / `back` / `forward` / `refresh` / `pending`.\n * @throws If called outside a page's React tree, where there is no navigation\n *   context to read.\n *\n * @see {@link https://www.rshono.com/docs/api#rshonocoreclient | Docs — `@rshono/core/client`}\n * @see {@link https://www.rshono.com/docs/pages#client-components | Docs — client components}\n */\nexport function useNavigation(): NavigationState {\n  const value = useContext(NavigationContext);\n  if (!value) {\n    throw new Error(\n      \"[rshono] useNavigation() must be called inside a 'use client' component rendered by a page. In a server component, read the URL from getRequestContext() instead.\",\n    );\n  }\n  return value;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rshono/core",
-  "version": "1.0.0-rc.23",
+  "version": "1.0.0-rc.24",
   "description": "Minimalist web framework — Hono + Rspack + React Server Components",
   "author": "Lasse <lasse@lassetange.com> (https://www.lassetange.com)",
   "license": "MIT",
@@ -59,10 +59,10 @@
   },
   "devDependencies": {
     "@playwright/test": "^1.63.0",
-    "@types/node": "^26.5.1",
+    "@types/node": "^26.6.3",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.5",
-    "hono": "^4.13.7",
+    "hono": "^4.13.10",
     "react": "19.2.8",
     "react-dom": "19.2.8",
     "typescript": "^7.0.2"