@rangojs/router 0.0.0-experimental.7dc955ec → 0.0.0-experimental.7f5e6b80

package/src/prerender.ts

@@ -33,10 +33,13 @@ import type {
   ExtractParams,
 } from "./types.js";
 import type { Handle } from "./handle.js";
+import type { HandlePush } from "./defer.js";
 import type { ContextVar } from "./context-var.js";
 import type { ReverseFunction } from "./reverse.js";
 import type { DefaultReverseRouteMap } from "./types/global-namespace.js";
+import type { UseItems, HandlerUseItem } from "./route-types.js";
 import { isCachedFunction } from "./cache/taint.js";
+import { isUnderTestRunner } from "./runtime-env.js";
 
 // -- Named route resolution types -------------------------------------------
 
@@ -68,9 +71,9 @@ type BuildReverseFunction = [DefaultReverseRouteMap] extends [
  * Default route map for Prerender named route resolution.
  * Uses GeneratedRouteMap (from gen file) to avoid circular dependencies.
  */
-type DefaultPrerenderRouteMap = keyof RSCRouter.GeneratedRouteMap extends never
+type DefaultPrerenderRouteMap = keyof Rango.GeneratedRouteMap extends never
   ? {}
-  : RSCRouter.GeneratedRouteMap;
+  : Rango.GeneratedRouteMap;
 
 /** Extract params from a route map entry (string pattern or { path } object). */
 type ExtractParamsFromEntry<TEntry> = TEntry extends string
@@ -105,13 +108,6 @@ type ResolvePrerenderParams<
 // -- Types ------------------------------------------------------------------
 
 export interface PrerenderOptions {
-  /**
-   * Keep handler in server bundle for live fallback (default: false).
-   * false: handler replaced with stub, source-only APIs excluded from bundle.
-   * true: handler stays in bundle, unknown params render live at request time.
-   */
-  passthrough?: boolean;
-
   /**
    * Maximum number of param sets to render in parallel (default: 1).
    * Only applies to dynamic Prerender handlers with getParams().
@@ -131,8 +127,8 @@ export interface PrerenderOptions {
 
 /**
  * Context passed to Prerender() handlers at build time.
- * Has a synthetic URL from getParams, params, and pathname.
- * No request, env, headers, cookies.
+ * Has a synthetic URL from getParams, params, pathname, and optionally env.
+ * No request, headers, cookies.
  */
 export interface BuildContext<TParams> {
   /** Params extracted from the route pattern (populated from getParams). */
@@ -141,6 +137,23 @@ export interface BuildContext<TParams> {
   /** True during build-time pre-rendering, false during passthrough live render. */
   build: true;
 
+  /**
+   * True when running in Vite dev mode (on-demand prerender), false during
+   * production `vite build`. Use this to branch on runtime mode without
+   * changing build semantics.
+   */
+  dev: boolean;
+
+  /**
+   * Build-time environment bindings (KV, D1, etc.) supplied by the Vite plugin.
+   * Only available when `buildEnv` is configured in rango() options.
+   * Throws with a clear error if not configured.
+   *
+   * This is NOT the live request env — it is shared across all prerender
+   * invocations for the build.
+   */
+  env: DefaultEnv;
+
   /** Read a variable set by getParams or a parent handler. */
   get: {
     <T>(contextVar: ContextVar<T>): T | undefined;
@@ -153,8 +166,14 @@ export interface BuildContext<TParams> {
     (key: string, value: any): void;
   };
 
-  /** Push handle data (frozen into pre-rendered output at build time). */
-  use: <T>(handle: Handle<T>) => (data: T) => void;
+  /**
+   * Push handle data (frozen into pre-rendered output at build time). Returns
+   * the full push function, including `.defer()` — a deferred slot resolved by
+   * a deep async component during the prerender render is awaited before the
+   * artifact is baked (resolve-by-default), so the baked output holds the
+   * resolved value.
+   */
+  use: <T>(handle: Handle<T>) => HandlePush<T>;
 
   /** Synthetic URL built from pattern + params (no real request). */
   url: URL;
@@ -173,8 +192,8 @@ export interface BuildContext<TParams> {
 
   /**
    * Signal that this param set should not produce a local prerender artifact.
-   * At runtime the handler runs live instead. Only valid on routes declared
-   * with `{ passthrough: true }`.
+   * At runtime the live handler runs instead. Only valid on routes wrapped
+   * with `Passthrough()`.
    */
   passthrough: () => PrerenderPassthroughResult;
 }
@@ -187,6 +206,17 @@ export interface StaticBuildContext {
   /** Always true for Static handlers at build time. */
   build: true;
 
+  /**
+   * True when running in Vite dev mode, false during production build.
+   */
+  dev: boolean;
+
+  /**
+   * Build-time environment bindings supplied by the Vite plugin.
+   * Only available when `buildEnv` is configured in rango() options.
+   */
+  env: DefaultEnv;
+
   /** Read a variable (available for type consistency with BuildContext). */
   get: {
     <T>(contextVar: ContextVar<T>): T | undefined;
@@ -199,8 +229,14 @@ export interface StaticBuildContext {
     (key: string, value: any): void;
   };
 
-  /** Push handle data (frozen into pre-rendered output at build time). */
-  use: <T>(handle: Handle<T>) => (data: T) => void;
+  /**
+   * Push handle data (frozen into pre-rendered output at build time). Returns
+   * the full push function, including `.defer()` — a deferred slot resolved by
+   * a deep async component during the prerender render is awaited before the
+   * artifact is baked (resolve-by-default), so the baked output holds the
+   * resolved value.
+   */
+  use: <T>(handle: Handle<T>) => HandlePush<T>;
 
   /** URL generation by route name. */
   reverse: BuildReverseFunction;
@@ -214,6 +250,17 @@ export interface GetParamsContext {
   /** Always true during build-time getParams execution. */
   build: true;
 
+  /**
+   * True when running in Vite dev mode, false during production build.
+   */
+  dev: boolean;
+
+  /**
+   * Build-time environment bindings supplied by the Vite plugin.
+   * Only available when `buildEnv` is configured in rango() options.
+   */
+  env: DefaultEnv;
+
   /** Set a variable that will be available to each handler invocation via ctx.get(). */
   set: {
     <T>(contextVar: ContextVar<T>, value: T): void;
@@ -224,23 +271,6 @@ export interface GetParamsContext {
   reverse: BuildReverseFunction;
 }
 
-/**
- * Context type for passthrough Prerender handlers.
- *
- * When `passthrough: true`, the handler runs both at build time and at request
- * time. The context is a full `HandlerContext` with `build: boolean`:
- * - `ctx.build === true`: build-time, env/request/res throw at runtime
- * - `ctx.build === false`: live request, full context available
- *
- * For `passthrough: false` (default), handlers receive `BuildContext` only.
- */
-export type PrerenderPassthroughContext<
-  TParams = {},
-  TEnv = DefaultEnv,
-> = HandlerContext<TParams, TEnv> & {
-  passthrough: () => PrerenderPassthroughResult;
-};
-
 export interface PrerenderHandlerDefinition<
   TParams extends Record<string, any> = any,
 > {
@@ -253,8 +283,15 @@ export interface PrerenderHandlerDefinition<
   getParams?: (ctx: GetParamsContext) => Promise<TParams[]> | TParams[];
   /** Pre-render options. */
   options?: PrerenderOptions;
+  /** Composable default DSL items merged when the handler is mounted. */
+  use?: () => UseItems<HandlerUseItem>;
 }
 
+// Process-stable fallback id counter (mirrors createHandle / createLoader). Only
+// assigned in a bare unit test where the Vite plugin did not inject an id; never
+// fires in a real build (the plugin always injects).
+let runtimePrerenderIdCounter = 0;
+
 // -- Overloads --------------------------------------------------------------
 //
 // T accepts: named route string (global or .local) OR explicit param object.
@@ -263,7 +300,7 @@ export interface PrerenderHandlerDefinition<
 // Explicit params work as before:
 //   Prerender<{ slug: string }> → params = { slug: string }
 
-// Overload 1: Static handler, no passthrough (build-time only)
+// Overload 1: Static handler (build-time only)
 export function Prerender<
   T extends
     | keyof DefaultPrerenderRouteMap
@@ -273,34 +310,15 @@ export function Prerender<
 >(
   handler: (
     ctx: BuildContext<ResolvePrerenderParams<T, TRouteMap>>,
-  ) => ReactNode | Promise<ReactNode>,
-  options?: PrerenderOptions & { passthrough?: false },
-  __injectedId?: string,
-): PrerenderHandlerDefinition<ResolvePrerenderParams<T, TRouteMap>>;
-
-// Overload 2: Static handler, passthrough (build + live — full HandlerContext)
-export function Prerender<
-  T extends
-    | keyof DefaultPrerenderRouteMap
-    | `.${keyof TRouteMap & string}`
-    | Record<string, any> = {},
-  TRouteMap extends {} = DefaultPrerenderRouteMap,
-  TEnv = DefaultEnv,
->(
-  handler: (
-    ctx: PrerenderPassthroughContext<
-      ResolvePrerenderParams<T, TRouteMap>,
-      TEnv
-    >,
   ) =>
     | ReactNode
     | PrerenderPassthroughResult
     | Promise<ReactNode | PrerenderPassthroughResult>,
-  options: PrerenderOptions & { passthrough: true },
+  options?: PrerenderOptions,
   __injectedId?: string,
 ): PrerenderHandlerDefinition<ResolvePrerenderParams<T, TRouteMap>>;
 
-// Overload 3: Dynamic handler, no passthrough (build-time only)
+// Overload 2: Dynamic handler (build-time only)
 export function Prerender<
   T extends
     | keyof DefaultPrerenderRouteMap
@@ -315,35 +333,11 @@ export function Prerender<
     | ResolvePrerenderParams<T, TRouteMap>[],
   handler: (
     ctx: BuildContext<ResolvePrerenderParams<T, TRouteMap>>,
-  ) => ReactNode | Promise<ReactNode>,
-  options?: PrerenderOptions & { passthrough?: false },
-  __injectedId?: string,
-): PrerenderHandlerDefinition<ResolvePrerenderParams<T, TRouteMap>>;
-
-// Overload 4: Dynamic handler, passthrough (build + live — full HandlerContext)
-export function Prerender<
-  T extends
-    | keyof DefaultPrerenderRouteMap
-    | `.${keyof TRouteMap & string}`
-    | Record<string, any>,
-  TRouteMap extends {} = DefaultPrerenderRouteMap,
-  TEnv = DefaultEnv,
->(
-  getParams: (
-    ctx: GetParamsContext,
-  ) =>
-    | Promise<ResolvePrerenderParams<T, TRouteMap>[]>
-    | ResolvePrerenderParams<T, TRouteMap>[],
-  handler: (
-    ctx: PrerenderPassthroughContext<
-      ResolvePrerenderParams<T, TRouteMap>,
-      TEnv
-    >,
   ) =>
     | ReactNode
     | PrerenderPassthroughResult
     | Promise<ReactNode | PrerenderPassthroughResult>,
-  options: PrerenderOptions & { passthrough: true },
+  options?: PrerenderOptions,
   __injectedId?: string,
 ): PrerenderHandlerDefinition<ResolvePrerenderParams<T, TRouteMap>>;
 
@@ -401,12 +395,27 @@ export function Prerender<TParams extends Record<string, any>>(
     );
   }
 
-  if (!id) {
+  // Throw unless under a test runner. The plugin always injects $$id for a
+  // supported `export const` Prerender on every build, so a missing id means
+  // either no plugin (a bare test — fall back below) or an UNSUPPORTED shape the
+  // plugin silently skipped (dev OR a real build — fail loud; a synthetic id
+  // would degrade to a silent prerender miss). The message is already small (no
+  // stack-parsing diagnostic), so it ships as-is. isUnderTestRunner() is
+  // runtime-safe — never a bare `process.env` access.
+  if (!id && !isUnderTestRunner()) {
     throw new Error(
-      "[rsc-router] Prerender: missing $$id. " +
-        "Ensure the exposeInternalIds Vite plugin is configured.",
+      "[rango] Prerender: missing $$id. Use `export const X = Prerender(...)` " +
+        "and ensure the exposeInternalIds Vite plugin is configured.",
     );
   }
+  // Under vitest with no plugin id: assign a process-stable runtime id so a
+  // whole-app router with Prerender routes constructs in a bare test (for
+  // dispatch / assertGeneratedRoutesMatch). Never reached in a real build (the
+  // throw above fires there); prerender storage/lookup keys on routeName +
+  // paramHash, never $$id (mirrors createHandle / createLoader).
+  if (!id) {
+    id = `__rango_runtime_prerender_${runtimePrerenderIdCounter++}`;
+  }
 
   return {
     __brand: "prerenderHandler" as const,
@@ -422,7 +431,7 @@ export function Prerender<TParams extends Record<string, any>>(
 /**
  * Sentinel returned by `ctx.passthrough()` to signal that a specific param set
  * should not produce a local prerender artifact. The build skips writing the
- * entry; at runtime the handler runs live (requires `{ passthrough: true }`).
+ * entry; at runtime the Passthrough live handler runs instead.
  */
 export const PRERENDER_PASSTHROUGH: Readonly<{
   __brand: "prerenderPassthrough";
@@ -446,7 +455,41 @@ export function isPrerenderPassthrough(
   );
 }
 
-// -- Type guard -------------------------------------------------------------
+/**
+ * Detect whether any resolved segment carries the passthrough sentinel.
+ *
+ * A build handler signals passthrough by returning `ctx.passthrough()` (the
+ * PRERENDER_PASSTHROUGH sentinel), which lands on the segment's `component`.
+ * But when the route declares `loading()`, the handler result is deferred
+ * upstream (segment-resolution/fresh.ts), so `component` is a thenable resolving
+ * to the sentinel rather than the sentinel itself — a synchronous
+ * `isPrerenderPassthrough(component)` on the Promise returns false and the build
+ * bakes a corrupt artifact instead of deferring. Resolve thenables first.
+ *
+ * Rejections are swallowed here: a throwing build handler resurfaces during
+ * segment serialization, preserving the prior error-handling behavior.
+ */
+export async function detectPrerenderPassthrough(
+  segments: ReadonlyArray<{ component: unknown }>,
+): Promise<boolean> {
+  for (const seg of segments) {
+    let component: unknown = seg.component;
+    if (
+      component &&
+      typeof (component as { then?: unknown }).then === "function"
+    ) {
+      try {
+        component = await component;
+      } catch {
+        continue;
+      }
+    }
+    if (isPrerenderPassthrough(component)) return true;
+  }
+  return false;
+}
+
+// -- Type guards ------------------------------------------------------------
 
 /**
  * Type guard to check if a value is a PrerenderHandlerDefinition.
@@ -461,3 +504,89 @@ export function isPrerenderHandler(
     (value as { __brand: unknown }).__brand === "prerenderHandler"
   );
 }
+
+// -- Passthrough wrapper ----------------------------------------------------
+
+/**
+ * A prerender route with a live fallback handler for unknown params at runtime.
+ *
+ * Wraps a `Prerender(...)` definition with a separate handler that runs at
+ * request time for params not covered by `getParams()`.
+ *
+ * - Build time: `prerenderDef` provides getParams + build handler.
+ * - Runtime: `liveHandler` runs for unknown params with full HandlerContext.
+ *
+ * @example
+ * ```ts
+ * const BlogPrerender = Prerender(
+ *   async () => [{ slug: "getting-started" }, { slug: "api-reference" }],
+ *   async (ctx) => <BlogPost slug={ctx.params.slug} />,
+ * );
+ *
+ * // In route definition:
+ * path("/blog/:slug", Passthrough(BlogPrerender, async (ctx) => {
+ *   const post = await ctx.env.DB.get(ctx.params.slug);
+ *   return <BlogPost slug={ctx.params.slug} post={post} />;
+ * }))
+ * ```
+ */
+export interface PassthroughHandlerDefinition<
+  TParams extends Record<string, any> = any,
+  TEnv = DefaultEnv,
+> {
+  readonly __brand: "passthroughHandler";
+  /** The underlying prerender definition (build-time rendering). */
+  prerenderDef: PrerenderHandlerDefinition<TParams>;
+  /** Live handler for runtime fallback on unknown params. */
+  liveHandler: (
+    ctx: HandlerContext<TParams, TEnv>,
+  ) => ReactNode | Promise<ReactNode> | Response | Promise<Response>;
+  /** Composable default DSL items merged when the handler is mounted. */
+  use?: () => UseItems<HandlerUseItem>;
+}
+
+export function Passthrough<
+  TParams extends Record<string, any>,
+  TEnv = DefaultEnv,
+>(
+  prerenderDef: PrerenderHandlerDefinition<TParams>,
+  liveHandler: (
+    ctx: HandlerContext<TParams, TEnv>,
+  ) => ReactNode | Promise<ReactNode> | Response | Promise<Response>,
+): PassthroughHandlerDefinition<TParams, TEnv>;
+
+// Implementation
+export function Passthrough<
+  TParams extends Record<string, any>,
+  TEnv = DefaultEnv,
+>(
+  prerenderDef: PrerenderHandlerDefinition<TParams>,
+  liveHandler: (
+    ctx: HandlerContext<TParams, TEnv>,
+  ) => ReactNode | Promise<ReactNode> | Response | Promise<Response>,
+): PassthroughHandlerDefinition<TParams, TEnv> {
+  if (!isPrerenderHandler(prerenderDef)) {
+    throw new Error(
+      "[rango] Passthrough: first argument must be a Prerender() definition.",
+    );
+  }
+  return {
+    __brand: "passthroughHandler" as const,
+    prerenderDef,
+    liveHandler,
+  };
+}
+
+/**
+ * Type guard to check if a value is a PassthroughHandlerDefinition.
+ */
+export function isPassthroughHandler(
+  value: unknown,
+): value is PassthroughHandlerDefinition {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "__brand" in value &&
+    (value as { __brand: unknown }).__brand === "passthroughHandler"
+  );
+}

package/src/redirect-origin.ts

@@ -0,0 +1,114 @@
+/**
+ * Runtime-neutral same-origin redirect rule.
+ *
+ * Shared by the client redirect guard (`browser/validate-redirect-origin.ts`,
+ * which validates redirect targets the client JS is about to navigate to) and
+ * the server outgoing-redirect guard (`rsc/redirect-guard.ts`, which validates
+ * every browser-followed `Location` header before it leaves the handler). Kept
+ * at the `src/` root so both layers import the ONE rule and cannot drift -- a
+ * cross-origin target blocked on the JS/fetch path is blocked identically on the
+ * no-JS (PE) and full-page document paths.
+ */
+
+/**
+ * Resolve a redirect target against the current origin.
+ *
+ * Returns the canonical (normalized) same-origin href -- which also collapses
+ * protocol-relative (`//evil.com`) and other ambiguous forms -- or `null` when
+ * the target resolves to a different origin or is unparseable. Pure: no logging,
+ * no side effects.
+ */
+export function resolveSameOriginRedirect(
+  url: string,
+  currentOrigin: string,
+): string | null {
+  try {
+    const target = new URL(url, currentOrigin);
+    if (target.origin !== currentOrigin) {
+      return null;
+    }
+    return target.href;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Validate an explicit off-origin redirect target (`redirect(url, { external:
+ * true })`).
+ *
+ * `external` opts out of the same-origin rule, but NOT out of scheme safety:
+ * only `http:`/`https:` targets are allowed. A redirect ultimately reaches the
+ * browser via `window.location.assign()` on the SPA/action client paths, so a
+ * forged or mistaken `redirect("javascript:...", { external: true })` would be a
+ * scriptable navigation if the scheme were not checked here. Returns the
+ * normalized href for an http(s) target (same- or cross-origin), or `null`
+ * otherwise. Pure: no logging, no side effects.
+ */
+export function resolveExternalRedirect(
+  url: string,
+  currentOrigin: string,
+): string | null {
+  try {
+    const target = new URL(url, currentOrigin);
+    if (target.protocol !== "http:" && target.protocol !== "https:") {
+      return null;
+    }
+    return target.href;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The safe same-origin landing for a blocked redirect.
+ *
+ * Every guard that neutralizes a cross-origin/unsafe redirect target sends the
+ * browser here instead: the app's basename root, or `"/"` when unset. Kept
+ * beside the resolvers so the "where does a blocked redirect go" answer lives
+ * in ONE place -- the server 3xx guard (`rsc/redirect-guard.ts`) and the
+ * shell-HIT degradation path (`rsc/rsc-rendering.ts`) must agree, or a blocked
+ * redirect lands differently depending on which exit it took.
+ */
+export function safeSameOriginLanding(basename: string | undefined): string {
+  return basename && basename !== "/" ? basename : "/";
+}
+
+/**
+ * Out-of-band brand for `redirect(url, { external: true })`.
+ *
+ * The external opt-in MUST be settable only by app code calling `redirect(...,
+ * { external: true })`, never by an attacker. An earlier design carried the
+ * opt-in as a wire header (`x-rango-redirect-external`), but a wire header is
+ * forgeable: a proxy-style response route that copies an attacker-controlled
+ * upstream response's headers would let `302 Location: https://evil` plus that
+ * header bypass the same-origin guard without app code ever opting in. So the
+ * opt-in is now an out-of-band brand on the Response object itself, tracked in a
+ * `WeakSet` that cannot cross the wire. `redirect()` brands the Response; the
+ * small set of internal redirect-rebuild paths (middleware `mergeResponse`,
+ * `carryOverRedirectHeaders`, the response-route rewrap) transfer the brand onto
+ * the rebuilt Response; the guard and the SPA intercept read it. An upstream
+ * Response an app proxies is never branded, so its forged header is inert.
+ *
+ * Fail-closed: if a rebuild path ever drops the brand, the redirect is
+ * neutralized to the app root rather than allowed off-host.
+ */
+const externalRedirects = new WeakSet<Response>();
+
+/** Brand a Response as an explicit `{ external: true }` redirect (out-of-band). */
+export function markExternalRedirect(response: Response): void {
+  externalRedirects.add(response);
+}
+
+/** Read the out-of-band `{ external: true }` brand off a Response. */
+export function isExternalRedirect(response: Response): boolean {
+  return externalRedirects.has(response);
+}
+
+/**
+ * Reserved internal header name. No longer a trust signal -- the external
+ * opt-in is the out-of-band brand above. It is kept only so the redirect-rebuild
+ * paths and the guard can defensively strip any value (e.g. one forged by a
+ * proxied upstream) and guarantee it never reaches the browser.
+ */
+export const EXTERNAL_REDIRECT_MARKER: string = "x-rango-redirect-external";

package/src/regex-escape.ts

@@ -0,0 +1,8 @@
+/**
+ * Escape a string for literal use inside a RegExp. Single source of truth for
+ * the router runtime (matching) and the vite build (transform/scan); a pure,
+ * dependency-free leaf so both environments can share it.
+ */
+export function escapeRegExp(input: string): string {
+  return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/render-error-thrower.tsx

@@ -0,0 +1,20 @@
+"use client";
+
+import type { ReactNode } from "react";
+
+interface RenderErrorThrowerProps {
+  error: unknown;
+}
+
+/**
+ * Client component that throws the given error during render, so the nearest
+ * error boundary catches it. Errors thrown during render are caught by error
+ * boundaries; async errors (rejected promises) are not -- which is why the
+ * navigation bridge funnels processing failures through this component instead
+ * of letting them surface as uncaught rejections.
+ */
+export function RenderErrorThrower({
+  error,
+}: RenderErrorThrowerProps): ReactNode {
+  throw error;
+}

package/src/response-utils.ts

@@ -0,0 +1,62 @@
+/**
+ * Runtime-neutral Response shape utilities.
+ *
+ * Kept at the src/ root so both `router/` and `rsc/` can depend on it
+ * without creating a cross-layer import cycle.
+ */
+
+/**
+ * True when a Response represents a WebSocket upgrade handoff and must not
+ * be reconstructed or mutated:
+ *
+ * - Status 101 (Switching Protocols) is outside the standard Response
+ *   constructor's 200–599 range, so `new Response(body, { status: 101 })`
+ *   throws RangeError on Node/undici and any spec-compliant runtime.
+ * - Cloudflare's workerd attaches a non-standard `webSocket` property on
+ *   the upgrade Response (e.g. from `acceptWebSocket`/`handleWebSocketUpgrade`
+ *   or the `agents` library's `routeAgentRequest`). That property is dropped
+ *   by a `new Response(...)` copy, breaking the upgrade even on workerd
+ *   where the status range is relaxed.
+ *
+ * Callers should short-circuit header/body merges for these responses.
+ */
+export function isWebSocketUpgradeResponse(response: Response): boolean {
+  return (
+    response.status === 101 ||
+    (response as unknown as { webSocket?: unknown }).webSocket != null
+  );
+}
+
+/**
+ * Append `Accept` to a response's `Vary` header without duplicating it.
+ *
+ * Content-negotiated responses already carry `Vary: Accept` from the
+ * upstream layer (response-route-handler's callHandlerWithVary, or
+ * handleRscRendering baking `accept` into its vary list). The negotiated
+ * post-append in the handler would otherwise emit `Vary: Accept, Accept`,
+ * a redundant token some proxies/CDNs treat as a distinct cache key.
+ * Token match is case-insensitive (HTTP field tokens are case-insensitive)
+ * and whitespace-tolerant.
+ */
+export function appendVaryAccept(response: Response): void {
+  const existing = response.headers.get("Vary");
+  if (!existing) {
+    response.headers.set("Vary", "Accept");
+    return;
+  }
+  const hasAccept = existing
+    .split(",")
+    .some((token) => token.trim().toLowerCase() === "accept");
+  if (!hasAccept) {
+    response.headers.append("Vary", "Accept");
+  }
+}
+
+// Location truthiness (not presence) so an empty `Location: ""` is not a redirect.
+export function isRedirectResponse(response: Response): boolean {
+  return (
+    response.status >= 300 &&
+    response.status < 400 &&
+    Boolean(response.headers.get("Location"))
+  );
+}