@rshono/core 1.0.0-rc.1 → 1.0.0-rc.10

package/dist/runtime/flight-inject.js

@@ -0,0 +1,221 @@
+/**
+ * Carrying the flight payload inside the HTML document, so the browser hydrates from bytes it
+ * already has rather than fetching the page a second time.
+ *
+ * The wire format is `rsc-html-stream`'s — a run of
+ * `<script>(self.__FLIGHT_DATA||=[]).push("…")</script>` tags — but the implementation is
+ * first-party, because that package's `injectRSCPayload` tests each HTML chunk for the document
+ * trailer with `endsWith`. React's byte writer packs its output into 2 kB views and splits any write
+ * that straddles one, so `</body></html>` can arrive as two chunks; upstream then fails to hold it
+ * back, and the document ends up with two trailers and the payload script after the first of them.
+ * A page's byte layout is deterministic, so that is not an intermittent fault — an unlucky page is
+ * malformed on every request. `test/unit.test.mjs` pins the split-trailer cases.
+ *
+ * The reader for this format is `readFlightPayload` in `entry.client.tsx`.
+ */
+const encoder = new TextEncoder();
+/** What React closes an `<html>` document with, and what this module re-emits after the last payload script. */
+const TRAILER = '</body></html>';
+const TRAILER_BYTES = encoder.encode(TRAILER);
+const hasSetImmediate = typeof setImmediate === 'function';
+const schedule = hasSetImmediate ? setImmediate : (fn) => setTimeout(fn, 0);
+const unschedule = (handle) => {
+    if (hasSetImmediate)
+        clearImmediate(handle);
+    else
+        clearTimeout(handle);
+};
+/**
+ * Escapes the two sequences that would end a `<script>` element early.
+ *
+ * Guarded by an `includes('<')` because a flight payload usually has no `<` in it at all, and the
+ * scan is far cheaper than two regex passes over 30 kB. `</script` becomes `</\script` rather than
+ * `<\/script`, which would break the valid JS `0</script/` (a regexp literal).
+ */
+function escapeScript(script) {
+    return script.includes('<') ? script.replace(/<!--/g, '<\\!--').replace(/<\/(script)/gi, '</\\$1') : script;
+}
+/**
+ * The bytes of `chunk` as a latin1 string, which is the form `btoa` takes.
+ *
+ * Sliced rather than `String.fromCharCode(...chunk)`, which passes one argument per byte and
+ * overflows the call stack on a chunk of any size. The slice width is a stack-safety choice, not a
+ * tuned one — this is only reached for a chunk that split a multi-byte character.
+ */
+function latin1(chunk) {
+    let out = '';
+    for (let at = 0; at < chunk.length; at += 8192)
+        out += String.fromCharCode(...chunk.subarray(at, at + 8192));
+    return out;
+}
+/** Whether `buffer`'s first `length` bytes end with the document trailer. */
+function endsWithTrailer(buffer, length) {
+    if (length < TRAILER_BYTES.length)
+        return false;
+    const from = length - TRAILER_BYTES.length;
+    for (let i = 0; i < TRAILER_BYTES.length; i++) {
+        if (buffer[from + i] !== TRAILER_BYTES[i])
+            return false;
+    }
+    return true;
+}
+export function injectFlightPayload(rscStream, options = {}) {
+    const { nonce, onDone } = options;
+    const scriptOpen = `<script${nonce ? ` nonce="${nonce}"` : ''}>(self.__FLIGHT_DATA||=[]).push(`;
+    const scriptClose = ')</script>';
+    const { promise: flightWritten, resolve: flightDone } = Promise.withResolvers();
+    let startedFlight = false;
+    const batch = [];
+    let boundary = null;
+    /**
+     * Set once the consumer has gone away, so nothing downstream tries to enqueue into a readable that
+     * can no longer take it.
+     *
+     * It cannot simply be the `cancel` hook that sets this. Per the Streams standard, cancelling the
+     * readable *after* the close algorithm has started returns the pending finish promise without
+     * running the transformer's `cancel` at all — and `flush` awaiting the whole flight payload is
+     * precisely that window. So a failed enqueue is also treated as the signal, wherever one happens.
+     */
+    let cancelled = false;
+    /** Held so {@link cancelled} can release the teed RSC branch rather than leaving it to be pumped. */
+    let flightReader = null;
+    /**
+     * Emits the HTML buffered since the last boundary, holding back the document trailer for
+     * {@link TransformStream.flush} to re-emit after the payload scripts.
+     *
+     * The batch is joined before the trailer is looked for, so a trailer React split across two views
+     * is still found — that is the whole reason this module is not `rsc-html-stream/server`. React
+     * writes its final flush in one synchronous run, so every chunk of the trailer lands in the same
+     * batch; a trailer split *across* batches is not a shape React produces.
+     */
+    function emitBatch(controller) {
+        boundary = null;
+        let total = 0;
+        for (const chunk of batch)
+            total += chunk.byteLength;
+        if (total === 0) {
+            batch.length = 0;
+            return;
+        }
+        const joined = new Uint8Array(total);
+        let at = 0;
+        for (const chunk of batch) {
+            joined.set(chunk, at);
+            at += chunk.byteLength;
+        }
+        batch.length = 0;
+        const end = endsWithTrailer(joined, total) ? total - TRAILER_BYTES.length : total;
+        if (end > 0)
+            controller.enqueue(joined.subarray(0, end));
+    }
+    async function writeFlight(controller) {
+        const reader = (flightReader = rscStream.getReader());
+        // `fatal`, so a chunk that split a multi-byte character throws rather than emitting U+FFFD and
+        // corrupting the payload — the catch below falls back to a byte-exact encoding for it.
+        const decoder = new TextDecoder('utf-8', { fatal: true });
+        const push = (literal) => controller.enqueue(encoder.encode(scriptOpen + literal + scriptClose));
+        for (;;) {
+            if (cancelled)
+                return;
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            // Only the *decode* is guarded. Wrapping the `push` in the same `try` conflated a split
+            // multi-byte character with a controller nobody is reading any more, and answered the second by
+            // re-encoding the chunk and enqueueing it again — which throws in turn, out of the catch.
+            let literal;
+            try {
+                literal = escapeScript(JSON.stringify(decoder.decode(value, { stream: true })));
+            }
+            catch {
+                literal = `Uint8Array.from(atob(${JSON.stringify(btoa(latin1(value)))}), m => m.codePointAt(0))`;
+            }
+            if (cancelled)
+                return;
+            // A failed enqueue means the consumer is gone. Stop pumping and release the RSC branch, so
+            // `flush` unparks now rather than whenever the flight payload would have ended on its own.
+            try {
+                push(literal);
+            }
+            catch {
+                cancelled = true;
+                reader.cancel().catch(() => { });
+                return;
+            }
+        }
+        if (cancelled)
+            return;
+        const remaining = decoder.decode();
+        if (remaining.length)
+            push(escapeScript(JSON.stringify(remaining)));
+    }
+    const transformer = {
+        transform(chunk, controller) {
+            batch.push(chunk);
+            if (boundary)
+                return;
+            // A macrotask, not a microtask: React writes a whole flush into its stream in one synchronous
+            // run, but `pipeThrough` delivers those chunks to us one microtask at a time. Only a task
+            // boundary guarantees the flush has arrived in full — a script injected between two of its
+            // chunks would land inside a tag.
+            boundary = schedule(() => {
+                try {
+                    emitBatch(controller);
+                }
+                catch (error) {
+                    controller.error(error);
+                    flightDone();
+                    return;
+                }
+                if (!startedFlight) {
+                    startedFlight = true;
+                    writeFlight(controller)
+                        .catch((error) => controller.error(error))
+                        .then(flightDone);
+                }
+            });
+        },
+        async flush(controller) {
+            await flightWritten;
+            // That await spans the entire flight payload, and the consumer can go away inside it — a
+            // browser's stop button, a navigation away, a proxy timeout. `cancel` below is *not* what tells
+            // us so (see `cancelled`), which leaves the enqueue throwing `ERR_INVALID_STATE` as the only
+            // signal. Unguarded it rejects `flush`, and nothing owns that rejection: it surfaces as an
+            // unhandled one and, where the host does not swallow it, takes the process down.
+            try {
+                if (boundary) {
+                    unschedule(boundary);
+                    emitBatch(controller);
+                }
+                if (!cancelled)
+                    controller.enqueue(encoder.encode(TRAILER));
+            }
+            catch {
+                // Nowhere left to put the trailer. A response the client abandoned is not a fault.
+                cancelled = true;
+                flightReader?.cancel().catch(() => { });
+            }
+            finally {
+                // Unconditional, and the reason this is a `finally`: `onDone` is what releases the abort
+                // forwarder in `renderComponent`, so it has to run however the response ended.
+                onDone?.();
+            }
+        },
+        cancel(reason) {
+            cancelled = true;
+            if (boundary) {
+                unschedule(boundary);
+                boundary = null;
+            }
+            batch.length = 0;
+            // Without this the teed RSC branch keeps being pumped for a response nobody will read, and the
+            // tee's other half buffers every chunk waiting for this one to catch up.
+            flightReader?.cancel(reason).catch(() => { });
+            // Unparks `flush` if it is waiting on a payload that will now never arrive.
+            flightDone();
+            onDone?.();
+        },
+    };
+    return new TransformStream(transformer);
+}
+//# sourceMappingURL=flight-inject.js.map

package/dist/runtime/flight-inject.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flight-inject.js","sourceRoot":"","sources":["../../src/runtime/flight-inject.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Carrying the flight payload inside the HTML document, so the browser hydrates from bytes it\n * already has rather than fetching the page a second time.\n *\n * The wire format is `rsc-html-stream`'s — a run of\n * `<script>(self.__FLIGHT_DATA||=[]).push(\"…\")</script>` tags — but the implementation is\n * first-party, because that package's `injectRSCPayload` tests each HTML chunk for the document\n * trailer with `endsWith`. React's byte writer packs its output into 2 kB views and splits any write\n * that straddles one, so `</body></html>` can arrive as two chunks; upstream then fails to hold it\n * back, and the document ends up with two trailers and the payload script after the first of them.\n * A page's byte layout is deterministic, so that is not an intermittent fault — an unlucky page is\n * malformed on every request. `test/unit.test.mjs` pins the split-trailer cases.\n *\n * The reader for this format is `readFlightPayload` in `entry.client.tsx`.\n */\n\n/**\n * {@link Transformer} plus the `cancel` hook the Streams standard added for a cancelled readable side.\n *\n * Node calls it (verified on 22.x) but the bundled lib types have not caught up, so it is declared\n * here rather than reached for with an `any`. It matters because `cancel` is the only notification\n * that a response ended *without* finishing, and both users of it release a listener that would\n * otherwise outlive the request.\n */\nexport type CancellableTransformer<I, O> = Transformer<I, O> & { cancel?: (reason?: unknown) => void };\n\nconst encoder = new TextEncoder();\n\n/** What React closes an `<html>` document with, and what this module re-emits after the last payload script. */\nconst TRAILER = '</body></html>';\nconst TRAILER_BYTES = encoder.encode(TRAILER);\n\n/**\n * A macrotask boundary. `setImmediate` where there is one (Node, Bun, Deno's node compat), which is\n * the current turn's check phase rather than a timer; `setTimeout` is the portable fallback that\n * every other runtime has. A Node timer has a 1ms floor and every HTML flush would pay it — worth\n * the two lines: uncontended time-to-last-byte on a 30 kB payload, 4.7ms → 3.0ms.\n */\ntype TaskHandle = ReturnType<typeof setTimeout> | ReturnType<typeof setImmediate>;\nconst hasSetImmediate = typeof setImmediate === 'function';\nconst schedule: (fn: () => void) => TaskHandle = hasSetImmediate ? setImmediate : (fn) => setTimeout(fn, 0);\nconst unschedule = (handle: TaskHandle): void => {\n  if (hasSetImmediate) clearImmediate(handle as ReturnType<typeof setImmediate>);\n  else clearTimeout(handle as ReturnType<typeof setTimeout>);\n};\n\n/**\n * Escapes the two sequences that would end a `<script>` element early.\n *\n * Guarded by an `includes('<')` because a flight payload usually has no `<` in it at all, and the\n * scan is far cheaper than two regex passes over 30 kB. `</script` becomes `</\\script` rather than\n * `<\\/script`, which would break the valid JS `0</script/` (a regexp literal).\n */\nfunction escapeScript(script: string): string {\n  return script.includes('<') ? script.replace(/<!--/g, '<\\\\!--').replace(/<\\/(script)/gi, '</\\\\$1') : script;\n}\n\n/**\n * The bytes of `chunk` as a latin1 string, which is the form `btoa` takes.\n *\n * Sliced rather than `String.fromCharCode(...chunk)`, which passes one argument per byte and\n * overflows the call stack on a chunk of any size. The slice width is a stack-safety choice, not a\n * tuned one — this is only reached for a chunk that split a multi-byte character.\n */\nfunction latin1(chunk: Uint8Array): string {\n  let out = '';\n  for (let at = 0; at < chunk.length; at += 8192) out += String.fromCharCode(...chunk.subarray(at, at + 8192));\n  return out;\n}\n\n/** Whether `buffer`'s first `length` bytes end with the document trailer. */\nfunction endsWithTrailer(buffer: Uint8Array, length: number): boolean {\n  if (length < TRAILER_BYTES.length) return false;\n  const from = length - TRAILER_BYTES.length;\n  for (let i = 0; i < TRAILER_BYTES.length; i++) {\n    if (buffer[from + i] !== TRAILER_BYTES[i]) return false;\n  }\n  return true;\n}\n\nexport function injectFlightPayload(\n  rscStream: ReadableStream<Uint8Array>,\n  options: { nonce?: string; onDone?: () => void } = {},\n): TransformStream<Uint8Array, Uint8Array> {\n  const { nonce, onDone } = options;\n  const scriptOpen = `<script${nonce ? ` nonce=\"${nonce}\"` : ''}>(self.__FLIGHT_DATA||=[]).push(`;\n  const scriptClose = ')</script>';\n\n  const { promise: flightWritten, resolve: flightDone } = Promise.withResolvers<void>();\n  let startedFlight = false;\n\n  const batch: Uint8Array[] = [];\n  let boundary: TaskHandle | null = null;\n\n  /**\n   * Set once the consumer has gone away, so nothing downstream tries to enqueue into a readable that\n   * can no longer take it.\n   *\n   * It cannot simply be the `cancel` hook that sets this. Per the Streams standard, cancelling the\n   * readable *after* the close algorithm has started returns the pending finish promise without\n   * running the transformer's `cancel` at all — and `flush` awaiting the whole flight payload is\n   * precisely that window. So a failed enqueue is also treated as the signal, wherever one happens.\n   */\n  let cancelled = false;\n  /** Held so {@link cancelled} can release the teed RSC branch rather than leaving it to be pumped. */\n  let flightReader: ReadableStreamDefaultReader<Uint8Array> | null = null;\n\n  /**\n   * Emits the HTML buffered since the last boundary, holding back the document trailer for\n   * {@link TransformStream.flush} to re-emit after the payload scripts.\n   *\n   * The batch is joined before the trailer is looked for, so a trailer React split across two views\n   * is still found — that is the whole reason this module is not `rsc-html-stream/server`. React\n   * writes its final flush in one synchronous run, so every chunk of the trailer lands in the same\n   * batch; a trailer split *across* batches is not a shape React produces.\n   */\n  function emitBatch(controller: TransformStreamDefaultController<Uint8Array>): void {\n    boundary = null;\n    let total = 0;\n    for (const chunk of batch) total += chunk.byteLength;\n    if (total === 0) {\n      batch.length = 0;\n      return;\n    }\n\n    const joined = new Uint8Array(total);\n    let at = 0;\n    for (const chunk of batch) {\n      joined.set(chunk, at);\n      at += chunk.byteLength;\n    }\n    batch.length = 0;\n\n    const end = endsWithTrailer(joined, total) ? total - TRAILER_BYTES.length : total;\n    if (end > 0) controller.enqueue(joined.subarray(0, end));\n  }\n\n  async function writeFlight(controller: TransformStreamDefaultController<Uint8Array>): Promise<void> {\n    const reader = (flightReader = rscStream.getReader());\n    // `fatal`, so a chunk that split a multi-byte character throws rather than emitting U+FFFD and\n    // corrupting the payload — the catch below falls back to a byte-exact encoding for it.\n    const decoder = new TextDecoder('utf-8', { fatal: true });\n    const push = (literal: string) => controller.enqueue(encoder.encode(scriptOpen + literal + scriptClose));\n    for (;;) {\n      if (cancelled) return;\n      const { done, value } = await reader.read();\n      if (done) break;\n      // Only the *decode* is guarded. Wrapping the `push` in the same `try` conflated a split\n      // multi-byte character with a controller nobody is reading any more, and answered the second by\n      // re-encoding the chunk and enqueueing it again — which throws in turn, out of the catch.\n      let literal: string;\n      try {\n        literal = escapeScript(JSON.stringify(decoder.decode(value, { stream: true })));\n      } catch {\n        literal = `Uint8Array.from(atob(${JSON.stringify(btoa(latin1(value)))}), m => m.codePointAt(0))`;\n      }\n      if (cancelled) return;\n      // A failed enqueue means the consumer is gone. Stop pumping and release the RSC branch, so\n      // `flush` unparks now rather than whenever the flight payload would have ended on its own.\n      try {\n        push(literal);\n      } catch {\n        cancelled = true;\n        reader.cancel().catch(() => {});\n        return;\n      }\n    }\n    if (cancelled) return;\n    const remaining = decoder.decode();\n    if (remaining.length) push(escapeScript(JSON.stringify(remaining)));\n  }\n\n  const transformer: CancellableTransformer<Uint8Array, Uint8Array> = {\n    transform(chunk, controller) {\n      batch.push(chunk);\n      if (boundary) return;\n      // A macrotask, not a microtask: React writes a whole flush into its stream in one synchronous\n      // run, but `pipeThrough` delivers those chunks to us one microtask at a time. Only a task\n      // boundary guarantees the flush has arrived in full — a script injected between two of its\n      // chunks would land inside a tag.\n      boundary = schedule(() => {\n        try {\n          emitBatch(controller);\n        } catch (error) {\n          controller.error(error);\n          flightDone();\n          return;\n        }\n        if (!startedFlight) {\n          startedFlight = true;\n          writeFlight(controller)\n            .catch((error) => controller.error(error))\n            .then(flightDone);\n        }\n      });\n    },\n    async flush(controller) {\n      await flightWritten;\n      // That await spans the entire flight payload, and the consumer can go away inside it — a\n      // browser's stop button, a navigation away, a proxy timeout. `cancel` below is *not* what tells\n      // us so (see `cancelled`), which leaves the enqueue throwing `ERR_INVALID_STATE` as the only\n      // signal. Unguarded it rejects `flush`, and nothing owns that rejection: it surfaces as an\n      // unhandled one and, where the host does not swallow it, takes the process down.\n      try {\n        if (boundary) {\n          unschedule(boundary);\n          emitBatch(controller);\n        }\n        if (!cancelled) controller.enqueue(encoder.encode(TRAILER));\n      } catch {\n        // Nowhere left to put the trailer. A response the client abandoned is not a fault.\n        cancelled = true;\n        flightReader?.cancel().catch(() => {});\n      } finally {\n        // Unconditional, and the reason this is a `finally`: `onDone` is what releases the abort\n        // forwarder in `renderComponent`, so it has to run however the response ended.\n        onDone?.();\n      }\n    },\n    cancel(reason) {\n      cancelled = true;\n      if (boundary) {\n        unschedule(boundary);\n        boundary = null;\n      }\n      batch.length = 0;\n      // Without this the teed RSC branch keeps being pumped for a response nobody will read, and the\n      // tee's other half buffers every chunk waiting for this one to catch up.\n      flightReader?.cancel(reason).catch(() => {});\n      // Unparks `flush` if it is waiting on a payload that will now never arrive.\n      flightDone();\n      onDone?.();\n    },\n  };\n  return new TransformStream<Uint8Array, Uint8Array>(transformer);\n}\n"]}

package/dist/runtime/navigation.d.ts

@@ -5,23 +5,27 @@ import { type ReactNode } from 'react';
  * `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.
+ *
+ * @example
+ * ```tsx
+ * const { router } = useNavigation();
+ * router.push('/dashboard');    // navigate, new history entry
+ * router.replace('/login');     // navigate, no new entry
+ * 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()`. */
-    back(): void;
-    /** Goes forward one history entry — `history.forward()`. */
-    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
@@ -31,16 +35,16 @@ export interface Navigation {
     /** 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
+ * Carries the live {@link NavigationRouter} implementation from the hydration runtime down
  * to {@link RouterProvider}. Framework internal — read the router through
  * {@link useNavigation} instead.
  *
  * @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.
@@ -62,7 +66,7 @@ export declare function RouterProvider({ href, params, children }: {
  * `pending` flag that is `true` while a client navigation is in flight.
  *
  * Hooks can't run in a server component; read the same URL data there from
- * `getContext()` (`@rshono/core/server`) instead.
+ * `getRequestContext()` (`@rshono/core/server`) instead.
  *
  * @example
  * ```tsx
@@ -80,35 +84,13 @@ 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` / `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;
+export declare function useNavigation(): NavigationState;
 //# sourceMappingURL=navigation.d.ts.map

package/dist/runtime/navigation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/runtime/navigation.tsx"],"names":[],"mappings":"AAEA,OAAO,EAA2D,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAEhG;;;;;;GAMG;AACH,MAAM,WAAW,MAAM;IACrB,0DAA0D;IAC1D,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,sFAAsF;IACtF,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,sDAAsD;IACtD,IAAI,IAAI,IAAI,CAAC;IACb,4DAA4D;IAC5D,OAAO,IAAI,IAAI,CAAC;IAChB,sFAAsF;IACtF,OAAO,IAAI,IAAI,CAAC;IAChB,kGAAkG;IAClG,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,0FAA0F;AAC1F,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,GAAG,EAAE,GAAG,CAAC;IACT,yFAAyF;IACzF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;CAChB;AAMD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,iCAAuC,CAAC;AAIlE;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,QAAQ,EAAE,SAAS,CAAA;CAAE,+BAK/H;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAQ1C;AAED,MAAM,WAAW,uBAAuB;IACtC,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,KAAiB,EAAE,MAAU,EAAE,GAAE,uBAA4B,GAAG,SAAS,CAmC7G"}
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/runtime/navigation.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAsC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAE3E;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,sFAAsF;IACtF,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,sFAAsF;IACtF,OAAO,IAAI,IAAI,CAAC;IAChB,kGAAkG;IAClG,OAAO,EAAE,OAAO,CAAC;CAClB;AAKD,oGAAoG;AACpG,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,GAAG,EAAE,GAAG,CAAC;IACT,yFAAyF;IACzF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,4DAA4D;IAC5D,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAMD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,2CAAiD,CAAC;AAI5E;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,QAAQ,EAAE,SAAS,CAAA;CAAE,+BAK/H;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,aAAa,IAAI,eAAe,CAQ/C"}

package/dist/runtime/navigation.js

@@ -1,10 +1,10 @@
 '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 };
+const defaultRouter = { push: noop, replace: noop, refresh: noop, pending: false };
 /**
- * Carries the live {@link Router} implementation from the hydration runtime down
+ * Carries the live {@link NavigationRouter} implementation from the hydration runtime down
  * to {@link RouterProvider}. Framework internal — read the router through
  * {@link useNavigation} instead.
  *
@@ -33,7 +33,7 @@ export function RouterProvider({ href, params, children }) {
  * `pending` flag that is `true` while a client navigation is in flight.
  *
  * Hooks can't run in a server component; read the same URL data there from
- * `getContext()` (`@rshono/core/server`) instead.
+ * `getRequestContext()` (`@rshono/core/server`) instead.
  *
  * @example
  * ```tsx
@@ -51,62 +51,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` / `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;AA6C3E,MAAM,IAAI,GAAG,GAAG,EAAE,GAAE,CAAC,CAAC;AAEtB,MAAM,aAAa,GAAqB,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAErG;;;;;;GAMG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;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 * `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 *\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.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  /** 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// No `back()` / `forward()` — `history.back()` and `history.forward()` need no framework, and the\n// traversal is picked up by the runtime's `popstate` listener either way.\n\n/** The current location plus the {@link NavigationRouter}, as returned by {@link useNavigation}. */\nexport interface NavigationState {\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: NavigationRouter;\n}\n\nconst noop = () => {};\n\nconst defaultRouter: NavigationRouter = { push: noop, replace: noop, refresh: noop, pending: false };\n\n/**\n * Carries the live {@link NavigationRouter} 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<NavigationRouter>(defaultRouter);\n\nconst NavigationContext = createContext<NavigationState | 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<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.\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 * `getRequestContext()` (`@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 NavigationState}: `url` and `params`, plus `router`\n * ({@link NavigationRouter}) with `push` / `replace` / `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

@@ -28,6 +28,12 @@ export declare function parseRenderRequest(request: Request): RenderRequest;
 export declare function acceptsRsc(request: Request): boolean;
 /** 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 that have no
+ * parsed {@link RenderRequest} to hand — they are reached from Hono's `onError` / `notFound` rather
+ * than from the render.
+ */
+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';

package/dist/runtime/request.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/runtime/request.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAExI,uHAAuH;AACvH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG,OAAO,CASpG;AAID,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,CAQlE;AAED,gHAAgH;AAChH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAEpD;AAED,sFAAsF;AACtF,wBAAgB,QAAQ,CAAC,aAAa,EAAE,aAAa,GAAG,OAAO,CAE9D;AAED,6EAA6E;AAC7E,wBAAgB,eAAe,CAAC,aAAa,EAAE,aAAa,GAAG,aAAa,IAAI,OAAO,CAAC,aAAa,EAAE;IAAE,IAAI,EAAE,aAAa,GAAG,YAAY,CAAA;CAAE,CAAC,CAE7I"}
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/runtime/request.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAExI,uHAAuH;AACvH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG,OAAO,CASpG;AAID,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,CAQlE;AAED,gHAAgH;AAChH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAEpD;AAED,sFAAsF;AACtF,wBAAgB,QAAQ,CAAC,aAAa,EAAE,aAAa,GAAG,OAAO,CAE9D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAEzD;AAED,6EAA6E;AAC7E,wBAAgB,eAAe,CAAC,aAAa,EAAE,aAAa,GAAG,aAAa,IAAI,OAAO,CAAC,aAAa,EAAE;IAAE,IAAI,EAAE,aAAa,GAAG,YAAY,CAAA;CAAE,CAAC,CAE7I"}

package/dist/runtime/request.js

@@ -32,6 +32,14 @@ export function acceptsRsc(request) {
 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 that have no
+ * parsed {@link RenderRequest} to hand — they are reached from Hono's `onError` / `notFound` rather
+ * than from the render.
+ */
+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,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;;;;GAIG;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":["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/**\n * {@link wantsRsc} straight off the request, for the error and control-signal paths that have no\n * parsed {@link RenderRequest} to hand — they are reached from Hono's `onError` / `notFound` rather\n * than from the render.\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,19 @@
 /**
  * `@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.
+ * 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 in `src/server.ts`, 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.
  *
- * 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.
+ * @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';
+export { getRequestContext, notFound, onServerError, publicUrl, redirect, type EnvVars, type RedirectStatus, type RequestContext, type ServerErrorContext, type ServerErrorHandler, type ServerErrorSource, } from './context.js';
 //# sourceMappingURL=server.d.ts.map

package/dist/runtime/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/runtime/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EACL,UAAU,EACV,QAAQ,EACR,aAAa,EACb,QAAQ,EAGR,KAAK,GAAG,EACR,KAAK,OAAO,EACZ,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,GACvB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/runtime/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,OAAO,EACL,iBAAiB,EACjB,QAAQ,EACR,aAAa,EAIb,SAAS,EACT,QAAQ,EACR,KAAK,OAAO,EACZ,KAAK,cAAc,EAGnB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,GACvB,MAAM,cAAc,CAAC"}