@rshono/core 1.0.0-rc.2 → 1.0.0-rc.21

package/dist/runtime/navigation.d.ts

@@ -2,48 +2,59 @@ import { type ReactNode } from 'react';
 /**
  * Imperative navigation actions, reached as `useNavigation().router`.
  *
- * `push` / `replace` / `refresh` are **soft** navigations: the new page's flight
- * payload is fetched and applied in place, so client component state outside the
- * changed subtree survives. Off-site or non-HTTP hrefs fall back to a full load.
+ * Every action is a **soft** navigation: the page's flight payload is fetched and applied in place, so
+ * client component state outside the changed subtree survives. Off-site hrefs — and a traversal that leaves
+ * the app — fall back to a full load.
+ *
+ * Soft navigation is the browser's
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API | Navigation API}; where that is
+ * missing, every action below is still correct and simply performs a real browser load.
+ *
+ * @example
+ * ```tsx
+ * const { router } = useNavigation();
+ * router.push('/dashboard');    // navigate, new history entry
+ * router.replace('/login');     // navigate, no new entry
+ * router.back();                // one entry back, as the browser's button does
+ * router.forward();             // one entry forward
+ * router.refresh();             // re-run this route's server components
+ * ```
  */
-export interface Router {
+export interface NavigationRouter {
     /** Navigates to `href` and pushes a new history entry. */
     push(href: string): void;
     /** Navigates to `href`, replacing the current history entry instead of adding one. */
     replace(href: string): void;
-    /** Goes back one history entry — `history.back()`. */
+    /** Steps one entry back in the browser's session history. Nothing to go back to is a no-op. */
     back(): void;
-    /** Goes forward one history entry — `history.forward()`. */
+    /** Steps one entry forward in the browser's session history. A no-op on the newest entry. */
     forward(): void;
     /** Re-fetches the current route from the server, re-running its server components. */
     refresh(): void;
     /** `true` while a soft navigation is in flight — use it to disable controls or show a spinner. */
     pending: boolean;
 }
-/** The current location plus the {@link Router}, as returned by {@link useNavigation}. */
-export interface Navigation {
+/** The current location plus the {@link NavigationRouter}, as returned by {@link useNavigation}. */
+export interface NavigationState {
     /**
-     * The full current {@link URL} — read `url.pathname`, `url.searchParams` and the
-     * rest off it. A fresh instance per navigation, so mutating it affects nothing
-     * else; it is not written back to the address bar either.
+     * 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.
      */
     url: URL;
     /** Matched route params for the current page, e.g. `{ id: '42' }` for `/profile/:id`. */
     params: Record<string, string>;
     /** Imperative navigation actions and the `pending` flag. */
-    router: Router;
+    router: NavigationRouter;
 }
 /**
- * Carries the live {@link Router} implementation from the hydration runtime down
- * to {@link RouterProvider}. Framework internal — read the router through
- * {@link useNavigation} instead.
+ * Carries the live {@link NavigationRouter} from the hydration runtime down to {@link RouterProvider}.
  *
  * @internal
  */
-export declare const RouterContext: import("react").Context<Router>;
+export declare const RouterContext: import("react").Context<NavigationRouter>;
 /**
- * Publishes the per-render location and params so {@link useNavigation} can read
- * them. Framework internal — the RSC entry wraps every page in one.
+ * Publishes the per-render location and params for {@link useNavigation} to read. The RSC entry wraps
+ * every page in one.
  *
  * @internal
  */
@@ -53,16 +64,20 @@ export declare function RouterProvider({ href, params, children }: {
     children: ReactNode;
 }): import("react").JSX.Element;
 /**
- * Reactive access to the current URL and programmatic navigation, in one hook.
+ * Reactive access to the current URL and programmatic navigation, in one hook. Call it from a
+ * `'use client'` component.
+ *
+ * `url` and `params` are computed on the server and travel in the flight payload, so they are correct
+ * 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.
  *
- * Call it from a `'use client'` component. The location fields (`url` and
- * `params`) are computed on the server and travel in the flight payload, so they
- * are correct during SSR — no hydration flicker — and update automatically on
- * every navigation. The `router` sub-object holds the imperative actions plus a
- * `pending` flag that is `true` while a client navigation is in flight.
+ * **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.
  *
- * Hooks can't run in a server component; read the same URL data there from
- * `getContext()` (`@rshono/core/server`) instead.
+ * Hooks can't run in a server component; read the same data there from `getRequestContext()`.
  *
  * @example
  * ```tsx
@@ -80,35 +95,12 @@ export declare function RouterProvider({ href, params, children }: {
  * }
  * ```
  *
- * @returns The current {@link Navigation}: `url` and `params`, plus `router`
- * ({@link Router}) with `push` / `replace` / `back` / `forward` / `refresh` /
- * `pending`.
+ * @returns The current {@link NavigationState}: `url` and `params`, plus `router`
+ * ({@link NavigationRouter}) with `push` / `replace` / `back` / `forward` / `refresh` / `pending`.
  * @throws If called outside a page's React tree, where there is no navigation
  *   context to read.
- */
-export declare function useNavigation(): Navigation;
-export interface NavigationProgressProps {
-    /** Bar color. Defaults to a neutral blue. */
-    color?: string;
-    /** Bar height in pixels. Defaults to `3`. */
-    height?: number;
-}
-/**
- * An opt-in top progress bar that appears while a client navigation is in
- * flight (driven by {@link Router.pending}). Drop one instance in your root
- * layout; it renders nothing on the server and stays invisible until the first
- * soft navigation, so there's no hydration flicker.
- *
- * @example
- * ```tsx
- * import { NavigationProgress } from '@rshono/core/client';
  *
- * // in your layout, once:
- * <body>
- *   <NavigationProgress />
- *   {children}
- * </body>
- * ```
+ * @see {@link https://www.rshono.com/docs/api#rshonocoreclient | Docs — `@rshono/core/client`}
+ * @see {@link https://www.rshono.com/docs/pages#client-components | Docs — client components}
  */
-export declare function NavigationProgress({ color, height }?: NavigationProgressProps): ReactNode;
-//# sourceMappingURL=navigation.d.ts.map
+export declare function useNavigation(): NavigationState;

package/dist/runtime/navigation.js

@@ -1,20 +1,18 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useContext, useEffect, useMemo, useState } from 'react';
+import { createContext, useContext, useMemo } from 'react';
 const noop = () => { };
 const defaultRouter = { push: noop, replace: noop, back: noop, forward: noop, refresh: noop, pending: false };
 /**
- * Carries the live {@link Router} implementation from the hydration runtime down
- * to {@link RouterProvider}. Framework internal — read the router through
- * {@link useNavigation} instead.
+ * Carries the live {@link NavigationRouter} from the hydration runtime down to {@link RouterProvider}.
  *
  * @internal
  */
 export const RouterContext = createContext(defaultRouter);
 const NavigationContext = createContext(null);
 /**
- * Publishes the per-render location and params so {@link useNavigation} can read
- * them. Framework internal — the RSC entry wraps every page in one.
+ * Publishes the per-render location and params for {@link useNavigation} to read. The RSC entry wraps
+ * every page in one.
  *
  * @internal
  */
@@ -24,16 +22,20 @@ export function RouterProvider({ href, params, children }) {
     return _jsx(NavigationContext.Provider, { value: value, children: children });
 }
 /**
- * Reactive access to the current URL and programmatic navigation, in one hook.
+ * Reactive access to the current URL and programmatic navigation, in one hook. Call it from a
+ * `'use client'` component.
  *
- * Call it from a `'use client'` component. The location fields (`url` and
- * `params`) are computed on the server and travel in the flight payload, so they
- * are correct during SSR — no hydration flicker — and update automatically on
- * every navigation. The `router` sub-object holds the imperative actions plus a
- * `pending` flag that is `true` while a client navigation is in flight.
+ * `url` and `params` are computed on the server and travel in the flight payload, so they are correct
+ * 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.
  *
- * Hooks can't run in a server component; read the same URL data there from
- * `getContext()` (`@rshono/core/server`) instead.
+ * **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.
+ *
+ * Hooks can't run in a server component; read the same data there from `getRequestContext()`.
  *
  * @example
  * ```tsx
@@ -51,62 +53,19 @@ export function RouterProvider({ href, params, children }) {
  * }
  * ```
  *
- * @returns The current {@link Navigation}: `url` and `params`, plus `router`
- * ({@link Router}) with `push` / `replace` / `back` / `forward` / `refresh` /
- * `pending`.
+ * @returns The current {@link NavigationState}: `url` and `params`, plus `router`
+ * ({@link NavigationRouter}) with `push` / `replace` / `back` / `forward` / `refresh` / `pending`.
  * @throws If called outside a page's React tree, where there is no navigation
  *   context to read.
+ *
+ * @see {@link https://www.rshono.com/docs/api#rshonocoreclient | Docs — `@rshono/core/client`}
+ * @see {@link https://www.rshono.com/docs/pages#client-components | Docs — client components}
  */
 export function useNavigation() {
     const value = useContext(NavigationContext);
     if (!value) {
-        throw new Error("[rshono] useNavigation() must be called inside a 'use client' component rendered by a page. In a server component, read the URL from getContext() instead.");
+        throw new Error("[rshono] useNavigation() must be called inside a 'use client' component rendered by a page. In a server component, read the URL from getRequestContext() instead.");
     }
     return value;
 }
-/**
- * An opt-in top progress bar that appears while a client navigation is in
- * flight (driven by {@link Router.pending}). Drop one instance in your root
- * layout; it renders nothing on the server and stays invisible until the first
- * soft navigation, so there's no hydration flicker.
- *
- * @example
- * ```tsx
- * import { NavigationProgress } from '@rshono/core/client';
- *
- * // in your layout, once:
- * <body>
- *   <NavigationProgress />
- *   {children}
- * </body>
- * ```
- */
-export function NavigationProgress({ color = '#3b82f6', height = 3 } = {}) {
-    const { router } = useNavigation();
-    const [bar, setBar] = useState({ width: 0, opacity: 0 });
-    useEffect(() => {
-        if (router.pending) {
-            // Jump in, then creep toward — but never reach — the end while we wait.
-            setBar({ width: 15, opacity: 1 });
-            const ramp = setTimeout(() => setBar({ width: 85, opacity: 1 }), 80);
-            return () => clearTimeout(ramp);
-        }
-        // Done: snap to full, then fade out. (No-op if it was never shown.)
-        setBar((b) => (b.opacity === 0 ? b : { width: 100, opacity: 1 }));
-        const hide = setTimeout(() => setBar({ width: 0, opacity: 0 }), 220);
-        return () => clearTimeout(hide);
-    }, [router.pending]);
-    return (_jsx("div", { "data-rshono-progress": "", "aria-hidden": "true", style: {
-            position: 'fixed',
-            top: 0,
-            left: 0,
-            height,
-            width: `${bar.width}%`,
-            opacity: bar.opacity,
-            background: color,
-            zIndex: 2147483647,
-            pointerEvents: 'none',
-            transition: 'width 200ms ease-out, opacity 200ms ease-out',
-        } }));
-}
 //# sourceMappingURL=navigation.js.map

package/dist/runtime/navigation.js.map

@@ -1 +1 @@
-{"version":3,"file":"navigation.js","sourceRoot":"","sources":["../../src/runtime/navigation.tsx"],"names":[],"mappings":"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","sourcesContent":["'use client';\n\nimport { createContext, useContext, useEffect, useMemo, useState, type ReactNode } from 'react';\n\n/**\n * Imperative navigation actions, reached as `useNavigation().router`.\n *\n * `push` / `replace` / `refresh` are **soft** navigations: the new page's flight\n * payload is fetched and applied in place, so client component state outside the\n * changed subtree survives. Off-site or non-HTTP hrefs fall back to a full load.\n */\nexport interface Router {\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  /** Goes back one history entry — `history.back()`. */\n  back(): void;\n  /** Goes forward one history entry — `history.forward()`. */\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 Router}, as returned by {@link useNavigation}. */\nexport interface Navigation {\n  /**\n   * The full current {@link URL} — read `url.pathname`, `url.searchParams` and the\n   * rest off it. A fresh instance per navigation, so mutating it affects nothing\n   * else; it is not written back to the address bar either.\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: Router;\n}\n\nconst noop = () => {};\n\nconst defaultRouter: Router = { push: noop, replace: noop, back: noop, forward: noop, refresh: noop, pending: false };\n\n/**\n * Carries the live {@link Router} implementation from the hydration runtime down\n * to {@link RouterProvider}. Framework internal — read the router through\n * {@link useNavigation} instead.\n *\n * @internal\n */\nexport const RouterContext = createContext<Router>(defaultRouter);\n\nconst NavigationContext = createContext<Navigation | null>(null);\n\n/**\n * Publishes the per-render location and params so {@link useNavigation} can read\n * them. Framework internal — the RSC entry wraps 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<Navigation>(() => ({ 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.\n *\n * Call it from a `'use client'` component. The location fields (`url` and\n * `params`) are computed on the server and travel in the flight payload, so they\n * are correct during SSR — no hydration flicker — and update automatically on\n * every navigation. The `router` sub-object holds the imperative actions plus a\n * `pending` flag that is `true` while a client navigation is in flight.\n *\n * Hooks can't run in a server component; read the same URL data there from\n * `getContext()` (`@rshono/core/server`) instead.\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 Navigation}: `url` and `params`, plus `router`\n * ({@link Router}) with `push` / `replace` / `back` / `forward` / `refresh` /\n * `pending`.\n * @throws If called outside a page's React tree, where there is no navigation\n *   context to read.\n */\nexport function useNavigation(): Navigation {\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 getContext() instead.\",\n    );\n  }\n  return value;\n}\n\nexport interface NavigationProgressProps {\n  /** Bar color. Defaults to a neutral blue. */\n  color?: string;\n  /** Bar height in pixels. Defaults to `3`. */\n  height?: number;\n}\n\n/**\n * An opt-in top progress bar that appears while a client navigation is in\n * flight (driven by {@link Router.pending}). Drop one instance in your root\n * layout; it renders nothing on the server and stays invisible until the first\n * soft navigation, so there's no hydration flicker.\n *\n * @example\n * ```tsx\n * import { NavigationProgress } from '@rshono/core/client';\n *\n * // in your layout, once:\n * <body>\n *   <NavigationProgress />\n *   {children}\n * </body>\n * ```\n */\nexport function NavigationProgress({ color = '#3b82f6', height = 3 }: NavigationProgressProps = {}): ReactNode {\n  const { router } = useNavigation();\n  const [bar, setBar] = useState({ width: 0, opacity: 0 });\n\n  useEffect(() => {\n    if (router.pending) {\n      // Jump in, then creep toward — but never reach — the end while we wait.\n      setBar({ width: 15, opacity: 1 });\n      const ramp = setTimeout(() => setBar({ width: 85, opacity: 1 }), 80);\n      return () => clearTimeout(ramp);\n    }\n    // Done: snap to full, then fade out. (No-op if it was never shown.)\n    setBar((b) => (b.opacity === 0 ? b : { width: 100, opacity: 1 }));\n    const hide = setTimeout(() => setBar({ width: 0, opacity: 0 }), 220);\n    return () => clearTimeout(hide);\n  }, [router.pending]);\n\n  return (\n    <div\n      data-rshono-progress=\"\"\n      aria-hidden=\"true\"\n      style={{\n        position: 'fixed',\n        top: 0,\n        left: 0,\n        height,\n        width: `${bar.width}%`,\n        opacity: bar.opacity,\n        background: color,\n        zIndex: 2147483647,\n        pointerEvents: 'none',\n        transition: 'width 200ms ease-out, opacity 200ms ease-out',\n      }}\n    />\n  );\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,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"]}

package/dist/runtime/request.d.ts

@@ -1,10 +1,9 @@
 /**
- * The four distinct shapes an incoming render request can take, modeled as a
- * discriminated union so illegal combinations (e.g. an action id on a GET) are
- * unrepresentable and every consumer dispatches exhaustively on `kind`.
+ * The four shapes an incoming render request can take, as a discriminated union so that illegal
+ * combinations — an action id on a GET — are unrepresentable.
  *
  * - `document` — a normal navigation; respond with a full SSR HTML document.
- * - `rsc` — a soft-navigation flight fetch (`Accept: text/x-component`).
+ * - `rsc` — a soft-navigation flight fetch (`RSC: 1`).
  * - `form-action` — a progressive-enhancement `<form>` POST (no JavaScript).
  * - `rsc-action` — a client-initiated server-action call carrying an action id.
  */
@@ -18,18 +17,53 @@ export type RenderRequest = {
     kind: 'rsc-action';
     actionId: string;
 };
-/** Builds the `Request` the client sends to ask a page for its flight payload, optionally carrying a server action. */
+/**
+ * Builds the `Request` the client sends to ask a page for its flight payload, optionally carrying a server
+ * action.
+ *
+ * `signal` is for a navigation, which a later one supersedes — an action is never abandoned that way, so its
+ * caller passes none.
+ */
 export declare function createRscRequest(urlString: string, action?: {
     id: string;
     body: BodyInit;
-}): Request;
+}, signal?: AbortSignal): Request;
+/**
+ * Whether a POST arrived in a shape a browser `<form>` could have produced: one of the three `enctype`
+ * values, and no header of its own to need a preflight for.
+ *
+ * The framework's cross-site refusal runs on this rather than on the {@link RenderRequest} classification,
+ * because what makes a form post forgeable from another site is its shape and not what happens to be in the
+ * body. Keyed the other way, `text/plain` — the one enctype React never writes — was classified `document`
+ * and never reached the refusal, while the README promised that a page route refuses *every* cross-site form
+ * post. No action could run through it, since `decodeAction` is only called for the two above; what it cost
+ * was a forced authenticated page render, and a claim about the boundary that was not true as written.
+ *
+ * `x-rsc-action` excludes the client-initiated shape, which needs no check of its own: that header is not
+ * CORS-safelisted, so a cross-origin caller needs a preflight the framework never answers.
+ *
+ * **The same test {@link parseRenderRequest} makes**, and it has to be: this decides what is *refused* and
+ * that decides what is *decoded*, so a header the two read differently is a request that takes the form path
+ * without passing the form check. A present-but-empty `x-rsc-action` was exactly that — `has` said "the
+ * client-initiated shape, already covered" while `get` was falsy, so the request fell through to
+ * `form-action` and ran the action it carried with the cross-site refusal skipped. Not reachable from a
+ * browser, since an empty header is still a header and still needs the preflight; refused anyway, because a
+ * predicate that fails open on a shape nothing produces today is one bad day from being wrong.
+ */
+export declare function isBrowserFormPost(request: Request): boolean;
 export declare function parseRenderRequest(request: Request): RenderRequest;
 /** Whether the client asked for a flight payload. For GET paths that only need the boolean, without parsing. */
-export declare function acceptsRsc(request: Request): boolean;
+export declare function asksForRsc(request: Request): boolean;
+/** The header a response has to `Vary` on, since one page URL answers as either representation. */
+export declare const RSC_VARY_HEADER = "RSC";
 /** True when the response should be a flight payload rather than an HTML document. */
 export declare function wantsRsc(renderRequest: RenderRequest): boolean;
+/**
+ * {@link wantsRsc} straight off the request, for the error and control-signal paths — reached from Hono's
+ * `onError` / `notFound`, so they have no parsed {@link RenderRequest} to hand.
+ */
+export declare function requestWantsRsc(request: Request): boolean;
 /** True when the request carries a server action to run before rendering. */
 export declare function isActionRequest(renderRequest: RenderRequest): renderRequest is Extract<RenderRequest, {
     kind: 'form-action' | 'rsc-action';
 }>;
-//# sourceMappingURL=request.d.ts.map

package/dist/runtime/request.js

@@ -1,18 +1,86 @@
+/**
+ * The header that names the server action a client-initiated call wants to run, and so the header that
+ * decides which of the two action branches a POST takes.
+ *
+ * That choice is a security boundary, not just a dispatch detail. It is deliberately *not* a CORS-safelisted
+ * header: a page on another origin cannot send one without a successful preflight, and the framework answers
+ * no preflight, so the `rsc-action` branch is unreachable cross-origin and carries no origin check of its
+ * own. The `form-action` branch is the forgeable one — a form post needs no preflight — and that is the one
+ * `refusesCrossSiteForm` stands in front of. See `SECURITY.md`.
+ */
 const HEADER_ACTION_ID = 'x-rsc-action';
-const RSC_CONTENT_TYPE = 'text/x-component';
-/** Builds the `Request` the client sends to ask a page for its flight payload, optionally carrying a server action. */
-export function createRscRequest(urlString, action) {
+/**
+ * The header that asks a page URL for its flight payload rather than its HTML document, and the value it
+ * carries. One URL answers as either, so this is what the response `Vary`s on.
+ *
+ * A header of its own rather than `Accept: text/x-component`, which is what this used to be. Content
+ * negotiation was the more standards-shaped mechanism and it cost too much: a prerendered page is served
+ * `public, max-age=300`, and `Vary: Accept` on a publicly cacheable response is close to a cache-disabling
+ * header — real browsers send long `Accept` strings that differ by vendor and version, so a CDN keyed on it
+ * stores a copy per variant of the same bytes, and some shared caches decline to store a `Vary` they consider
+ * high-cardinality at all. This one has exactly two states.
+ */
+const HEADER_RSC = 'rsc';
+const HEADER_RSC_VALUE = '1';
+/**
+ * Builds the `Request` the client sends to ask a page for its flight payload, optionally carrying a server
+ * action.
+ *
+ * `signal` is for a navigation, which a later one supersedes — an action is never abandoned that way, so its
+ * caller passes none.
+ */
+export function createRscRequest(urlString, action, signal) {
     const url = new URL(urlString, location.origin);
-    const headers = new Headers({ Accept: RSC_CONTENT_TYPE });
+    const headers = new Headers({ [HEADER_RSC]: HEADER_RSC_VALUE });
     if (action)
         headers.set(HEADER_ACTION_ID, action.id);
     return new Request(url, {
         method: action ? 'POST' : 'GET',
         headers,
         body: action?.body,
+        signal,
     });
 }
+/**
+ * The two content types React writes a form action as, and so the two a POST must carry to be *decoded* as
+ * one.
+ *
+ * Deliberately narrower than the set {@link isBrowserFormPost} refuses on. `decodeAction` reaches the body
+ * through `request.formData()`, which throws on a `text/plain` one — so classifying that enctype as a
+ * `form-action` would turn every same-origin `text/plain` POST into a 400 where the page used to render.
+ * What the framework decodes and what it refuses are two different questions.
+ */
 const FORM_CONTENT_TYPES = /^(?:multipart\/form-data|application\/x-www-form-urlencoded)/i;
+/** The third `enctype` a browser `<form>` can send, which React never writes and this never decodes. */
+const PLAIN_TEXT_ENCTYPE = /^text\/plain/i;
+/**
+ * Whether a POST arrived in a shape a browser `<form>` could have produced: one of the three `enctype`
+ * values, and no header of its own to need a preflight for.
+ *
+ * The framework's cross-site refusal runs on this rather than on the {@link RenderRequest} classification,
+ * because what makes a form post forgeable from another site is its shape and not what happens to be in the
+ * body. Keyed the other way, `text/plain` — the one enctype React never writes — was classified `document`
+ * and never reached the refusal, while the README promised that a page route refuses *every* cross-site form
+ * post. No action could run through it, since `decodeAction` is only called for the two above; what it cost
+ * was a forced authenticated page render, and a claim about the boundary that was not true as written.
+ *
+ * `x-rsc-action` excludes the client-initiated shape, which needs no check of its own: that header is not
+ * CORS-safelisted, so a cross-origin caller needs a preflight the framework never answers.
+ *
+ * **The same test {@link parseRenderRequest} makes**, and it has to be: this decides what is *refused* and
+ * that decides what is *decoded*, so a header the two read differently is a request that takes the form path
+ * without passing the form check. A present-but-empty `x-rsc-action` was exactly that — `has` said "the
+ * client-initiated shape, already covered" while `get` was falsy, so the request fell through to
+ * `form-action` and ran the action it carried with the cross-site refusal skipped. Not reachable from a
+ * browser, since an empty header is still a header and still needs the preflight; refused anyway, because a
+ * predicate that fails open on a shape nothing produces today is one bad day from being wrong.
+ */
+export function isBrowserFormPost(request) {
+    if (request.method !== 'POST' || request.headers.get(HEADER_ACTION_ID))
+        return false;
+    const contentType = request.headers.get('content-type') ?? '';
+    return FORM_CONTENT_TYPES.test(contentType) || PLAIN_TEXT_ENCTYPE.test(contentType);
+}
 export function parseRenderRequest(request) {
     if (request.method === 'POST') {
         const actionId = request.headers.get(HEADER_ACTION_ID);
@@ -22,16 +90,25 @@ export function parseRenderRequest(request) {
             return { kind: 'form-action' };
         return { kind: 'document' };
     }
-    return { kind: acceptsRsc(request) ? 'rsc' : 'document' };
+    return { kind: asksForRsc(request) ? 'rsc' : 'document' };
 }
 /** Whether the client asked for a flight payload. For GET paths that only need the boolean, without parsing. */
-export function acceptsRsc(request) {
-    return request.headers.get('accept')?.includes(RSC_CONTENT_TYPE) ?? false;
+export function asksForRsc(request) {
+    return request.headers.get(HEADER_RSC) === HEADER_RSC_VALUE;
 }
+/** The header a response has to `Vary` on, since one page URL answers as either representation. */
+export const RSC_VARY_HEADER = 'RSC';
 /** True when the response should be a flight payload rather than an HTML document. */
 export function wantsRsc(renderRequest) {
     return renderRequest.kind === 'rsc' || renderRequest.kind === 'rsc-action';
 }
+/**
+ * {@link wantsRsc} straight off the request, for the error and control-signal paths — reached from Hono's
+ * `onError` / `notFound`, so they have no parsed {@link RenderRequest} to hand.
+ */
+export function requestWantsRsc(request) {
+    return wantsRsc(parseRenderRequest(request));
+}
 /** True when the request carries a server action to run before rendering. */
 export function isActionRequest(renderRequest) {
     return renderRequest.kind === 'form-action' || renderRequest.kind === 'rsc-action';

package/dist/runtime/request.js.map

@@ -1 +1 @@
-{"version":3,"file":"request.js","sourceRoot":"","sources":["../../src/runtime/request.ts"],"names":[],"mappings":"AAAA,MAAM,gBAAgB,GAAG,cAAc,CAAC;AACxC,MAAM,gBAAgB,GAAG,kBAAkB,CAAC;AAc5C,uHAAuH;AACvH,MAAM,UAAU,gBAAgB,CAAC,SAAiB,EAAE,MAAuC;IACzF,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChD,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;IAC1D,IAAI,MAAM;QAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IACrD,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE;QACtB,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK;QAC/B,OAAO;QACP,IAAI,EAAE,MAAM,EAAE,IAAI;KACnB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,kBAAkB,GAAG,+DAA+D,CAAC;AAE3F,MAAM,UAAU,kBAAkB,CAAC,OAAgB;IACjD,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAC9B,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;QACvD,IAAI,QAAQ;YAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC;QACtD,IAAI,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;YAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;QACvG,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;IAC9B,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;AAC5D,CAAC;AAED,gHAAgH;AAChH,MAAM,UAAU,UAAU,CAAC,OAAgB;IACzC,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,gBAAgB,CAAC,IAAI,KAAK,CAAC;AAC5E,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,QAAQ,CAAC,aAA4B;IACnD,OAAO,aAAa,CAAC,IAAI,KAAK,KAAK,IAAI,aAAa,CAAC,IAAI,KAAK,YAAY,CAAC;AAC7E,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,eAAe,CAAC,aAA4B;IAC1D,OAAO,aAAa,CAAC,IAAI,KAAK,aAAa,IAAI,aAAa,CAAC,IAAI,KAAK,YAAY,CAAC;AACrF,CAAC","sourcesContent":["const HEADER_ACTION_ID = 'x-rsc-action';\nconst RSC_CONTENT_TYPE = 'text/x-component';\n\n/**\n * The four distinct shapes an incoming render request can take, modeled as a\n * discriminated union so illegal combinations (e.g. an action id on a GET) are\n * unrepresentable and every consumer dispatches exhaustively on `kind`.\n *\n * - `document` — a normal navigation; respond with a full SSR HTML document.\n * - `rsc` — a soft-navigation flight fetch (`Accept: text/x-component`).\n * - `form-action` — a progressive-enhancement `<form>` POST (no JavaScript).\n * - `rsc-action` — a client-initiated server-action call carrying an action id.\n */\nexport type RenderRequest = { kind: 'document' } | { kind: 'rsc' } | { kind: 'form-action' } | { kind: 'rsc-action'; actionId: string };\n\n/** Builds the `Request` the client sends to ask a page for its flight payload, optionally carrying a server action. */\nexport function createRscRequest(urlString: string, action?: { id: string; body: BodyInit }): Request {\n  const url = new URL(urlString, location.origin);\n  const headers = new Headers({ Accept: RSC_CONTENT_TYPE });\n  if (action) headers.set(HEADER_ACTION_ID, action.id);\n  return new Request(url, {\n    method: action ? 'POST' : 'GET',\n    headers,\n    body: action?.body,\n  });\n}\n\nconst FORM_CONTENT_TYPES = /^(?:multipart\\/form-data|application\\/x-www-form-urlencoded)/i;\n\nexport function parseRenderRequest(request: Request): RenderRequest {\n  if (request.method === 'POST') {\n    const actionId = request.headers.get(HEADER_ACTION_ID);\n    if (actionId) return { kind: 'rsc-action', actionId };\n    if (FORM_CONTENT_TYPES.test(request.headers.get('content-type') ?? '')) return { kind: 'form-action' };\n    return { kind: 'document' };\n  }\n  return { kind: acceptsRsc(request) ? 'rsc' : 'document' };\n}\n\n/** Whether the client asked for a flight payload. For GET paths that only need the boolean, without parsing. */\nexport function acceptsRsc(request: Request): boolean {\n  return request.headers.get('accept')?.includes(RSC_CONTENT_TYPE) ?? false;\n}\n\n/** True when the response should be a flight payload rather than an HTML document. */\nexport function wantsRsc(renderRequest: RenderRequest): boolean {\n  return renderRequest.kind === 'rsc' || renderRequest.kind === 'rsc-action';\n}\n\n/** True when the request carries a server action to run before rendering. */\nexport function isActionRequest(renderRequest: RenderRequest): renderRequest is Extract<RenderRequest, { kind: 'form-action' | 'rsc-action' }> {\n  return renderRequest.kind === 'form-action' || renderRequest.kind === 'rsc-action';\n}\n"]}
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../../src/runtime/request.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,gBAAgB,GAAG,cAAc,CAAC;AAExC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,GAAG,KAAK,CAAC;AACzB,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAa7B;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAiB,EAAE,MAAuC,EAAE,MAAoB;IAC/G,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChD,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,EAAE,gBAAgB,EAAE,CAAC,CAAC;IAChE,IAAI,MAAM;QAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IACrD,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE;QACtB,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK;QAC/B,OAAO;QACP,IAAI,EAAE,MAAM,EAAE,IAAI;QAClB,MAAM;KACP,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,kBAAkB,GAAG,+DAA+D,CAAC;AAE3F,wGAAwG;AACxG,MAAM,kBAAkB,GAAG,eAAe,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAgB;IAChD,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;QAAE,OAAO,KAAK,CAAC;IACrF,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;IAC9D,OAAO,kBAAkB,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,kBAAkB,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;AACtF,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,OAAgB;IACjD,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAC9B,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;QACvD,IAAI,QAAQ;YAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC;QACtD,IAAI,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;YAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;QACvG,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;IAC9B,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;AAC5D,CAAC;AAED,gHAAgH;AAChH,MAAM,UAAU,UAAU,CAAC,OAAgB;IACzC,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,gBAAgB,CAAC;AAC9D,CAAC;AAED,mGAAmG;AACnG,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,CAAC;AAErC,sFAAsF;AACtF,MAAM,UAAU,QAAQ,CAAC,aAA4B;IACnD,OAAO,aAAa,CAAC,IAAI,KAAK,KAAK,IAAI,aAAa,CAAC,IAAI,KAAK,YAAY,CAAC;AAC7E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,OAAO,QAAQ,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,eAAe,CAAC,aAA4B;IAC1D,OAAO,aAAa,CAAC,IAAI,KAAK,aAAa,IAAI,aAAa,CAAC,IAAI,KAAK,YAAY,CAAC;AACrF,CAAC","sourcesContent":["/**\n * The header that names the server action a client-initiated call wants to run, and so the header that\n * decides which of the two action branches a POST takes.\n *\n * That choice is a security boundary, not just a dispatch detail. It is deliberately *not* a CORS-safelisted\n * header: a page on another origin cannot send one without a successful preflight, and the framework answers\n * no preflight, so the `rsc-action` branch is unreachable cross-origin and carries no origin check of its\n * own. The `form-action` branch is the forgeable one — a form post needs no preflight — and that is the one\n * `refusesCrossSiteForm` stands in front of. See `SECURITY.md`.\n */\nconst HEADER_ACTION_ID = 'x-rsc-action';\n\n/**\n * The header that asks a page URL for its flight payload rather than its HTML document, and the value it\n * carries. One URL answers as either, so this is what the response `Vary`s on.\n *\n * A header of its own rather than `Accept: text/x-component`, which is what this used to be. Content\n * negotiation was the more standards-shaped mechanism and it cost too much: a prerendered page is served\n * `public, max-age=300`, and `Vary: Accept` on a publicly cacheable response is close to a cache-disabling\n * header — real browsers send long `Accept` strings that differ by vendor and version, so a CDN keyed on it\n * stores a copy per variant of the same bytes, and some shared caches decline to store a `Vary` they consider\n * high-cardinality at all. This one has exactly two states.\n */\nconst HEADER_RSC = 'rsc';\nconst HEADER_RSC_VALUE = '1';\n\n/**\n * The four shapes an incoming render request can take, as a discriminated union so that illegal\n * combinations — an action id on a GET — are unrepresentable.\n *\n * - `document` — a normal navigation; respond with a full SSR HTML document.\n * - `rsc` — a soft-navigation flight fetch (`RSC: 1`).\n * - `form-action` — a progressive-enhancement `<form>` POST (no JavaScript).\n * - `rsc-action` — a client-initiated server-action call carrying an action id.\n */\nexport type RenderRequest = { kind: 'document' } | { kind: 'rsc' } | { kind: 'form-action' } | { kind: 'rsc-action'; actionId: string };\n\n/**\n * Builds the `Request` the client sends to ask a page for its flight payload, optionally carrying a server\n * action.\n *\n * `signal` is for a navigation, which a later one supersedes — an action is never abandoned that way, so its\n * caller passes none.\n */\nexport function createRscRequest(urlString: string, action?: { id: string; body: BodyInit }, signal?: AbortSignal): Request {\n  const url = new URL(urlString, location.origin);\n  const headers = new Headers({ [HEADER_RSC]: HEADER_RSC_VALUE });\n  if (action) headers.set(HEADER_ACTION_ID, action.id);\n  return new Request(url, {\n    method: action ? 'POST' : 'GET',\n    headers,\n    body: action?.body,\n    signal,\n  });\n}\n\n/**\n * The two content types React writes a form action as, and so the two a POST must carry to be *decoded* as\n * one.\n *\n * Deliberately narrower than the set {@link isBrowserFormPost} refuses on. `decodeAction` reaches the body\n * through `request.formData()`, which throws on a `text/plain` one — so classifying that enctype as a\n * `form-action` would turn every same-origin `text/plain` POST into a 400 where the page used to render.\n * What the framework decodes and what it refuses are two different questions.\n */\nconst FORM_CONTENT_TYPES = /^(?:multipart\\/form-data|application\\/x-www-form-urlencoded)/i;\n\n/** The third `enctype` a browser `<form>` can send, which React never writes and this never decodes. */\nconst PLAIN_TEXT_ENCTYPE = /^text\\/plain/i;\n\n/**\n * Whether a POST arrived in a shape a browser `<form>` could have produced: one of the three `enctype`\n * values, and no header of its own to need a preflight for.\n *\n * The framework's cross-site refusal runs on this rather than on the {@link RenderRequest} classification,\n * because what makes a form post forgeable from another site is its shape and not what happens to be in the\n * body. Keyed the other way, `text/plain` — the one enctype React never writes — was classified `document`\n * and never reached the refusal, while the README promised that a page route refuses *every* cross-site form\n * post. No action could run through it, since `decodeAction` is only called for the two above; what it cost\n * was a forced authenticated page render, and a claim about the boundary that was not true as written.\n *\n * `x-rsc-action` excludes the client-initiated shape, which needs no check of its own: that header is not\n * CORS-safelisted, so a cross-origin caller needs a preflight the framework never answers.\n *\n * **The same test {@link parseRenderRequest} makes**, and it has to be: this decides what is *refused* and\n * that decides what is *decoded*, so a header the two read differently is a request that takes the form path\n * without passing the form check. A present-but-empty `x-rsc-action` was exactly that — `has` said \"the\n * client-initiated shape, already covered\" while `get` was falsy, so the request fell through to\n * `form-action` and ran the action it carried with the cross-site refusal skipped. Not reachable from a\n * browser, since an empty header is still a header and still needs the preflight; refused anyway, because a\n * predicate that fails open on a shape nothing produces today is one bad day from being wrong.\n */\nexport function isBrowserFormPost(request: Request): boolean {\n  if (request.method !== 'POST' || request.headers.get(HEADER_ACTION_ID)) return false;\n  const contentType = request.headers.get('content-type') ?? '';\n  return FORM_CONTENT_TYPES.test(contentType) || PLAIN_TEXT_ENCTYPE.test(contentType);\n}\n\nexport function parseRenderRequest(request: Request): RenderRequest {\n  if (request.method === 'POST') {\n    const actionId = request.headers.get(HEADER_ACTION_ID);\n    if (actionId) return { kind: 'rsc-action', actionId };\n    if (FORM_CONTENT_TYPES.test(request.headers.get('content-type') ?? '')) return { kind: 'form-action' };\n    return { kind: 'document' };\n  }\n  return { kind: asksForRsc(request) ? 'rsc' : 'document' };\n}\n\n/** Whether the client asked for a flight payload. For GET paths that only need the boolean, without parsing. */\nexport function asksForRsc(request: Request): boolean {\n  return request.headers.get(HEADER_RSC) === HEADER_RSC_VALUE;\n}\n\n/** The header a response has to `Vary` on, since one page URL answers as either representation. */\nexport const RSC_VARY_HEADER = 'RSC';\n\n/** True when the response should be a flight payload rather than an HTML document. */\nexport function wantsRsc(renderRequest: RenderRequest): boolean {\n  return renderRequest.kind === 'rsc' || renderRequest.kind === 'rsc-action';\n}\n\n/**\n * {@link wantsRsc} straight off the request, for the error and control-signal paths — reached from Hono's\n * `onError` / `notFound`, so they have no parsed {@link RenderRequest} to hand.\n */\nexport function requestWantsRsc(request: Request): boolean {\n  return wantsRsc(parseRenderRequest(request));\n}\n\n/** True when the request carries a server action to run before rendering. */\nexport function isActionRequest(renderRequest: RenderRequest): renderRequest is Extract<RenderRequest, { kind: 'form-action' | 'rsc-action' }> {\n  return renderRequest.kind === 'form-action' || renderRequest.kind === 'rsc-action';\n}\n"]}

package/dist/runtime/server.d.ts

@@ -1,24 +1,26 @@
 /**
- * `@rshono/core/server` — the request-scoped surface, for use inside server components
- * and `'use server'` action modules: {@link getContext} for the URL, cookies,
- * params, env and middleware variables, the {@link redirect} and {@link notFound}
- * control-flow helpers, and {@link onServerError} for reporting the errors the
- * framework catches.
+ * `@rshono/core/server` — the request-scoped surface, for server components and `'use server'` action
+ * modules: `getRequestContext()` for the URL, cookies, params, env and middleware variables, the
+ * `redirect()` and `notFound()` control-flow helpers, and `onServerError()` for reporting the errors
+ * the framework catches. Plus `publicUrl(c)` for middleware, which is handed Hono's `c` rather than a
+ * request context.
  *
- * Server-only. Importing this from a `'use client'` module is a mistake — those
- * run in the browser (and are SSR'd without a bound context). Read what you need
- * on the server and pass it down as props, or use `useNavigation()` from
- * `@rshono/core/client` for URL data.
+ * Server-only: a `'use client'` module runs in the browser, with no bound context. Read what you need
+ * on the server and pass it down as props, or use `useNavigation()` from `@rshono/core/client`.
  *
- * A barrel rather than `./context.js` itself, which is where all of this is
- * implemented: that module also exports the plumbing the framework's own entry
- * points need (`runWithContext`, `readParams`, `publicUrl`, `reportServerError`),
- * and pointing the `./server` subpath straight at it published every one of them —
- * `@internal` in the docs, but present in a consumer's autocomplete and pinned by
- * semver all the same. They stay reachable by relative import, which is the only
- * way the framework itself ever reaches them.
+ * @example
+ * ```ts
+ * 'use server';
+ * import { getRequestContext, redirect } from '@rshono/core/server';
+ *
+ * export async function logout() {
+ *   getRequestContext().cookies.delete('session', { path: '/' });
+ *   redirect('/');
+ * }
+ * ```
+ *
+ * @see {@link https://www.rshono.com/docs/api#rshonocoreserver | Docs — `@rshono/core/server`}
  *
  * @packageDocumentation
  */
-export { getContext, notFound, onServerError, redirect, type Ctx, type EnvVars, type RedirectStatus, type ServerErrorContext, type ServerErrorHandler, type ServerErrorSource, } from './context.js';
-//# sourceMappingURL=server.d.ts.map
+export { getRequestContext, notFound, onServerError, publicUrl, redirect, type EnvVars, type RedirectStatus, type RequestContext, type ServerErrorContext, type ServerErrorHandler, type ServerErrorSource, } from './context.js';