@rangojs/router 0.0.0-experimental.f3c21dba → 0.0.0-experimental.f4a8e8de

package/dist/types.backup/router/router-options.d.ts

@@ -0,0 +1,738 @@
+import type { ComponentType, ReactNode } from "react";
+import type { SegmentCacheStore } from "../cache/types.js";
+import type { ErrorBoundaryHandler, NotFoundBoundaryHandler, OnErrorCallback } from "../types";
+import type { NonceProvider } from "../rsc/types.js";
+import type { ShellCaptureDebug } from "../rsc/shell-capture.js";
+import type { ExecutionContext } from "../server/request-context.js";
+import type { UrlPatterns } from "../urls.js";
+import type { UrlBuilder } from "../urls/pattern-types.js";
+import type { NamedRouteEntry } from "./content-negotiation.js";
+import type { TelemetrySink } from "./telemetry.js";
+import type { RouterTracingConfig } from "./tracing.js";
+import type { RouterTimeouts, OnTimeoutCallback } from "./timeout.js";
+/**
+ * SSR stream mode returned by resolveStreaming.
+ *
+ * - `"stream"` — start flushing HTML as soon as the shell is ready
+ *   (default React SSR behavior via `renderToReadableStream`).
+ * - `"allReady"` — wait for every Suspense boundary to resolve before
+ *   sending any bytes (equivalent to awaiting `stream.allReady`).
+ */
+export type SSRStreamMode = "stream" | "allReady";
+/**
+ * Context passed to the resolveStreaming callback.
+ */
+export interface ResolveStreamingContext<TEnv = unknown> {
+    request: Request;
+    env: TEnv;
+    url: URL;
+}
+/**
+ * SSR configuration options.
+ */
+export interface SSROptions<TEnv = unknown> {
+    /**
+     * Determine whether an HTML response should stream progressively or
+     * wait for full readiness before flushing.
+     *
+     * Called once per HTML request, before the HTML response is produced.
+     * Does NOT apply to RSC responses (`__rsc`, partial navigation, prefetch).
+     *
+     * Return `"stream"` (default) for progressive streaming or `"allReady"`
+     * to buffer the complete HTML before sending.
+     *
+     * @example Bot detection
+     * ```ts
+     * createRouter({
+     *   ssr: {
+     *     resolveStreaming: async ({ request, env }) => {
+     *       const bot = await detectBot(request, env);
+     *       return bot.isBot && !bot.supportsStreaming ? "allReady" : "stream";
+     *     },
+     *   },
+     * });
+     * ```
+     */
+    resolveStreaming?: (context: ResolveStreamingContext<TEnv>) => SSRStreamMode | Promise<SSRStreamMode>;
+}
+/**
+ * Props passed to the root layout component
+ */
+export interface RootLayoutProps {
+    children: ReactNode;
+}
+/**
+ * Router configuration options
+ */
+export interface RangoOptions<TEnv = any> {
+    /**
+     * Unique identifier for this router instance.
+     * Used to namespace static output files and route maps.
+     * Auto-generated if not provided.
+     */
+    id?: string;
+    /**
+     * Injected by the Vite transform at compile time.
+     * Hash of filename + line number for stable cross-environment ID.
+     * @internal
+     */
+    $$id?: string;
+    /**
+     * Injected by the Vite transform at compile time.
+     * Absolute path of the source file that defines this router,
+     * relative to project root. Eliminates runtime stack trace parsing.
+     * @internal
+     */
+    $$sourceFile?: string;
+    /**
+     * URL prefix applied to all routes registered with this router.
+     *
+     * Useful when the app is served under a sub-path (e.g. `/admin` or `/v2`).
+     * All `path()` patterns are automatically prefixed and `reverse()` returns
+     * full paths including the basename. Route names are NOT prefixed.
+     *
+     * @example
+     * ```typescript
+     * const router = createRouter({
+     *   basename: "/admin",
+     * }).routes(({ path }) => [
+     *   path("/", Dashboard, { name: "home" }),       // matches /admin
+     *   path("/users", Users, { name: "users" }),     // matches /admin/users
+     * ]);
+     *
+     * router.reverse("home");   // "/admin"
+     * router.reverse("users");  // "/admin/users"
+     * ```
+     */
+    basename?: string;
+    /**
+     * Enable performance metrics collection
+     * When enabled, metrics are output to console and available via Server-Timing header
+     */
+    debugPerformance?: boolean;
+    /**
+     * DEVELOPMENT/TEST ONLY. Emit an `X-Rango-Cache` response header describing
+     * the cache status of the matched route, for use by testing primitives such
+     * as `assertCacheStatus`.
+     *
+     * Defaults to `false`. When neither this option nor the
+     * `RANGO_TEST_SIGNALS=1` environment flag is set, NO header is emitted and
+     * router output is byte-identical to the default.
+     *
+     * The header encodes per-segment (v1: coarse route-level) status keyed by the
+     * route NAME, e.g. `X-Rango-Cache: product.detail=hit`. Do NOT enable in
+     * production — it exposes internal cache decisions.
+     */
+    debugCacheSignal?: boolean;
+    /**
+     * Debug sink for the PPR shell-capture pipeline (routes with the `ppr` path
+     * option). `true` logs one structured line per capture attempt/skip to
+     * console (visible via `wrangler tail`); a function receives each
+     * `ShellCaptureDebugEvent` (outcome per attempt, snapshot bytes,
+     * write-barrier wait, backoff state) for programmatic capture. Off by
+     * default; the events also mirror into the dev Server-Timing surface when
+     * `debugPerformance` is on. Intended for validating capture behavior on a
+     * real deployment, not steady-state production.
+     */
+    debugShellCapture?: ShellCaptureDebug;
+    /**
+     * Document component that wraps the entire application.
+     *
+     * This component provides the HTML structure for your app and wraps
+     * both normal route content AND error states, preventing the app shell
+     * from unmounting during errors (avoids FOUC).
+     *
+     * Must be a client component ("use client") that accepts { children }.
+     *
+     * If not provided, a default document with basic HTML structure is used:
+     * `<html><head><meta charset/viewport></head><body>{children}</body></html>`
+     *
+     * @example
+     * ```typescript
+     * // components/Document.tsx
+     * "use client";
+     * export function Document({ children }: { children: ReactNode }) {
+     *   return (
+     *     <html lang="en">
+     *       <head>
+     *         <link rel="stylesheet" href="/styles.css" />
+     *       </head>
+     *       <body>
+     *         <nav>...</nav>
+     *         {children}
+     *       </body>
+     *     </html>
+     *   );
+     * }
+     *
+     * // router.tsx
+     * const router = createRouter<AppEnv>({
+     *   document: Document,
+     * });
+     * ```
+     */
+    document?: ComponentType<RootLayoutProps>;
+    /**
+     * Default error boundary fallback used when no error boundary is defined in the route tree
+     * If not provided, errors will propagate and crash the request
+     */
+    defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler;
+    /**
+     * Default not-found boundary fallback used when no notFoundBoundary is defined in the route tree
+     * If not provided, DataNotFoundError will be treated as a regular error
+     */
+    defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler;
+    /**
+     * Component to render when no route matches the requested URL.
+     *
+     * This is rendered within your document/app shell with a 404 status code.
+     * Use this for a custom 404 page that maintains your app's look and feel.
+     *
+     * If not provided, a default "Page not found" component is rendered.
+     *
+     * Can be a static ReactNode or a function receiving the pathname.
+     *
+     * @example
+     * ```typescript
+     * // Simple static component
+     * const router = createRouter<AppEnv>({
+     *   document: Document,
+     *   notFound: <NotFound404 />,
+     * });
+     *
+     * // Dynamic component with pathname
+     * const router = createRouter<AppEnv>({
+     *   document: Document,
+     *   notFound: ({ pathname }) => (
+     *     <div>
+     *       <h1>404 - Not Found</h1>
+     *       <p>No page exists at {pathname}</p>
+     *       <a href="/">Go home</a>
+     *     </div>
+     *   ),
+     * });
+     * ```
+     */
+    notFound?: ReactNode | ((props: {
+        pathname: string;
+    }) => ReactNode);
+    /**
+     * Callback invoked when an error occurs during request handling.
+     *
+     * This callback is for notification/logging purposes - it cannot modify
+     * the error handling flow. Use errorBoundary() in route definitions to
+     * customize error UI.
+     *
+     * The callback receives comprehensive context about the error including:
+     * - The error itself
+     * - Phase where it occurred (routing, middleware, loader, handler, etc.)
+     * - Request info (URL, method, params)
+     * - Route info (routeKey, segmentId)
+     * - Environment/bindings
+     * - Duration from request start
+     *
+     * @example
+     * ```typescript
+     * const router = createRouter<AppEnv>({
+     *   onError: (context) => {
+     *     // Send to error tracking service
+     *     Sentry.captureException(context.error, {
+     *       tags: {
+     *         phase: context.phase,
+     *         route: context.routeKey,
+     *       },
+     *       extra: {
+     *         url: context.url.toString(),
+     *         params: context.params,
+     *         duration: context.duration,
+     *       },
+     *     });
+     *   },
+     * });
+     * ```
+     */
+    onError?: OnErrorCallback<TEnv>;
+    /**
+     * Cache store for segment caching.
+     *
+     * When provided, enables route-level caching via cache() boundaries.
+     * The store handles persistence (memory, KV, Redis, etc.).
+     *
+     * Can be a static config or a function receiving env for runtime bindings.
+     *
+     * @example Static config
+     * ```typescript
+     * import { MemorySegmentCacheStore } from "@rangojs/router/cache";
+     *
+     * const router = createRouter({
+     *   cache: {
+     *     store: new MemorySegmentCacheStore({ defaults: { ttl: 60 } }),
+     *   },
+     * });
+     * ```
+     *
+     * @example Dynamic config with env (e.g., Cloudflare Workers with ExecutionContext)
+     * ```typescript
+     * const router = createRouter<AppBindings>({
+     *   cache: (_env, ctx) => ({
+     *     store: new CFCacheStore({
+     *       defaults: { ttl: 60 },
+     *       ctx: ctx!, // ExecutionContext for non-blocking writes
+     *     }),
+     *   }),
+     * });
+     * ```
+     */
+    cache?: {
+        store: SegmentCacheStore;
+        enabled?: boolean;
+    } | ((env: TEnv, ctx?: ExecutionContext) => {
+        store: SegmentCacheStore;
+        enabled?: boolean;
+    });
+    /**
+     * Named cache profiles for "use cache" directive.
+     * Profile names map to TTL/SWR configuration.
+     *
+     * - `"use cache"` (no name) resolves to the `default` profile.
+     * - `"use cache: short"` resolves to the `short` profile.
+     *
+     * @example
+     * ```typescript
+     * createRouter({
+     *   cacheProfiles: {
+     *     default: { ttl: 900, swr: 1800 },
+     *     short:   { ttl: 60, swr: 120 },
+     *     long:    { ttl: 3600, swr: 7200 },
+     *     products: { ttl: 300, swr: 600, tags: ['products'] },
+     *   },
+     * });
+     * ```
+     */
+    cacheProfiles?: Record<string, import("../cache/profile-registry.js").CacheProfile>;
+    /**
+     * Theme configuration for automatic theme management.
+     *
+     * When provided, enables:
+     * - ctx.theme and ctx.setTheme() in route handlers
+     * - useTheme() hook for client components
+     * - FOUC prevention via inline script in MetaTags
+     * - Automatic ThemeProvider wrapping in NavigationProvider
+     *
+     * @example
+     * ```typescript
+     * const router = createRouter<AppEnv>({
+     *   theme: {
+     *     defaultTheme: "system",
+     *     themes: ["light", "dark"],
+     *   }
+     * });
+     *
+     * // In route handler:
+     * route("settings", (ctx) => {
+     *   const theme = ctx.theme;     // "light" | "dark" | "system"
+     *   ctx.setTheme("dark");        // Sets cookie
+     *   return <SettingsPage />;
+     * });
+     *
+     * // In client component:
+     * import { useTheme } from "@rangojs/router/theme";
+     *
+     * function ThemeToggle() {
+     *   const { theme, setTheme, themes } = useTheme();
+     *   return <select value={theme} onChange={e => setTheme(e.target.value)}>
+     *     {themes.map(t => <option key={t}>{t}</option>)}
+     *   </select>;
+     * }
+     * ```
+     *
+     * Use `theme: true` to enable with all defaults.
+     */
+    theme?: import("../theme/types.js").ThemeConfig | true;
+    /**
+     * Default for whether the router wraps `transition()` segments in its own
+     * React `<ViewTransition>` boundary (experimental React only).
+     *
+     * - "auto" (default): every route/layout that opts in via `transition()`
+     *   gets a router-owned cross-fade.
+     * - false: the router never places its own boundary. Routes that use
+     *   `transition()` still drive navigation through startTransition (so loaders
+     *   hold instead of flashing a skeleton) and still let consumer-placed
+     *   `<ViewTransition>` elements animate — the router just contributes no
+     *   cross-fade of its own. This is the "router triggers, you place the
+     *   transitions" model.
+     *
+     * A per-segment `transition({ viewTransition })` overrides this default.
+     *
+     * @example
+     * ```typescript
+     * // App-wide: drive + hold, but never auto-wrap. Place <ViewTransition>
+     * // yourself in components where you want a morph.
+     * const router = createRouter<AppEnv>({ viewTransition: false });
+     * ```
+     */
+    viewTransition?: "auto" | false;
+    /**
+     * URL patterns to register with the router.
+     *
+     * Accepts either a `UrlPatterns` object from `urls()` or a builder function
+     * directly (urls() is called implicitly).
+     *
+     * @example
+     * ```typescript
+     * // With urls()
+     * createRouter<AppEnv>({
+     *   document: Document,
+     *   urls: urlpatterns,
+     * });
+     *
+     * // With builder function
+     * createRouter<AppEnv>({
+     *   document: Document,
+     *   urls: ({ path }) => [
+     *     path("/", HomePage, { name: "home" }),
+     *     path("/about", AboutPage, { name: "about" }),
+     *   ],
+     * });
+     * ```
+     */
+    urls?: UrlPatterns<TEnv, any> | UrlBuilder<TEnv>;
+    /**
+     * Injected by the Vite transform at compile time.
+     * Static import of NamedRoutes from the generated named-routes file.
+     * Used to seed reverse() with the full named route map.
+     * @internal
+     */
+    $$routeNames?: Record<string, NamedRouteEntry>;
+    /**
+     * Nonce provider for Content Security Policy (CSP).
+     *
+     * Can be:
+     * - A function that returns a nonce string
+     * - A function that returns `true` to auto-generate a nonce
+     * - Undefined to disable nonce (default)
+     *
+     * The nonce will be applied to inline scripts injected by the RSC payload.
+     * It's also available to middleware via the typed `nonce` token:
+     * `import { nonce } from "@rangojs/router"; ctx.get(nonce)`
+     *
+     * @example Auto-generate nonce
+     * ```tsx
+     * createRouter({
+     *   nonce: () => true,
+     * });
+     * ```
+     *
+     * @example Custom nonce from request context
+     * ```tsx
+     * createRouter({
+     *   nonce: (request, env) => env.nonce,
+     * });
+     * ```
+     *
+     * @example Access nonce in middleware
+     * ```tsx
+     * import { nonce } from "@rangojs/router";
+     *
+     * const cspMiddleware: Middleware = async (ctx, next) => {
+     *   const value = ctx.get(nonce); // string | undefined
+     *   await next();
+     * };
+     * ```
+     */
+    nonce?: NonceProvider<TEnv>;
+    /**
+     * RSC version string included in metadata.
+     * The browser sends this back on partial requests to detect version mismatches.
+     *
+     * Defaults to the auto-generated VERSION from `@rangojs/router:version` virtual module.
+     * Only set this if you need a custom versioning strategy.
+     *
+     * @default VERSION from @rangojs/router:version
+     */
+    version?: string;
+    /**
+     * TTL (in seconds) for the in-memory prefetch cache and the
+     * Cache-Control header on prefetch responses.
+     *
+     * Controls how long prefetch responses are kept in the client-side
+     * in-memory cache and sets `Cache-Control: private, max-age=<ttl>`
+     * on server responses for CDN/edge caching.
+     *
+     * The cache is automatically invalidated on server actions regardless
+     * of TTL, so this is primarily a staleness safety net.
+     *
+     * Set to `false` to disable prefetch caching entirely.
+     *
+     * @default 300 (5 minutes)
+     */
+    prefetchCacheTTL?: number | false;
+    /**
+     * Maximum number of decoded prefetch payloads the client keeps in its
+     * in-memory prefetch cache. When the cache is full the oldest entry is
+     * evicted (FIFO) to make room for a new prefetch.
+     *
+     * Each entry retains a fully decoded RSC payload (and the route's client
+     * chunks pulled in while decoding), so this is the lever on client-side
+     * prefetch memory: a higher value warms more routes at the cost of more
+     * retained payloads. Staleness is bounded separately by `prefetchCacheTTL`;
+     * this bounds the entry COUNT.
+     *
+     * Values below 1 (or non-finite) fall back to the default. To turn
+     * prefetching off entirely, set `prefetchCacheTTL: false` instead.
+     *
+     * @default 100
+     */
+    prefetchCacheSize?: number;
+    /**
+     * Maximum number of speculative prefetch requests (viewport/render strategy)
+     * the client runs concurrently. Hover prefetches bypass this queue and fire
+     * immediately; this caps only the background, idle-gated queue so prefetches
+     * never saturate the browser's connection pool.
+     *
+     * Values below 1 (or non-finite) fall back to the default.
+     *
+     * @default 2
+     */
+    prefetchConcurrency?: number;
+    /**
+     * Prefix for the rango state cookie name. The resolved name is
+     * `{prefix}_{routerId}`; the prefix is sanitized to cookie-name-safe
+     * characters (`[A-Za-z0-9-]`) and an empty result falls back to the default.
+     *
+     * The rango state cookie keys the client's prefetch / HTTP caches. Overriding
+     * the prefix lets you align it with cookie-naming policies or consent-manager
+     * classification lists, or avoid colliding with an existing `rango-state`
+     * cookie. It is not a full-name override: the `_{routerId}` suffix is what
+     * keeps sibling apps on one origin from clobbering each other's state.
+     *
+     * @default "rango-state"
+     */
+    stateCookiePrefix?: string;
+    /**
+     * Enable connection warmup to keep TCP+TLS alive after idle periods.
+     *
+     * When enabled, the client sends a HEAD request after the user returns
+     * from an idle period (60s+), prewarming the TLS connection before
+     * the next navigation.
+     *
+     * @default true
+     */
+    warmup?: boolean;
+    /**
+     * Wrap the hydrated client tree in `React.StrictMode`.
+     *
+     * The Rango browser entry hydrates the app inside `<React.StrictMode>` by
+     * default. StrictMode double-invokes render and (in development) mounts,
+     * unmounts, then remounts every effect to surface impure renders and missing
+     * effect cleanup. Production builds treat StrictMode as a no-op, so this flag
+     * only changes development behavior in a normal app.
+     *
+     * Set to `false` to hydrate without the StrictMode wrapper. The main reason to
+     * opt out is to isolate StrictMode's intentional double-render/double-effect
+     * from genuine re-renders when measuring client-hook stability — with
+     * StrictMode off, render counts are exact in development too.
+     *
+     * The value is resolved server-side at router creation and shipped to the
+     * client in the initial payload metadata; the browser entry reads it once at
+     * hydration. Changing it does not affect the SSR HTML (StrictMode emits no
+     * DOM), so toggling it never causes a hydration mismatch.
+     *
+     * @default true
+     */
+    strictMode?: boolean;
+    /**
+     * Shorthand timeout (ms) applied to both action execution and render start.
+     * Does NOT apply to streamIdleMs.
+     * Overridden by individual values in `timeouts`.
+     *
+     * @example
+     * ```typescript
+     * createRouter({ timeout: 10_000 });
+     * ```
+     */
+    timeout?: number;
+    /**
+     * Structured timeout configuration per phase.
+     * Values here override the `timeout` shorthand.
+     *
+     * @example
+     * ```typescript
+     * createRouter({
+     *   timeouts: {
+     *     actionMs: 10_000,
+     *     renderStartMs: 8_000,
+     *   },
+     * });
+     * ```
+     */
+    timeouts?: RouterTimeouts;
+    /**
+     * Custom handler invoked when a timeout occurs.
+     * Receives context about which phase timed out and must return a Response.
+     * If not provided, returns a plain 504 with "Request timed out" body
+     * and X-Rango-Timeout-Phase header.
+     *
+     * If the callback throws, the default 504 response is used as fallback.
+     *
+     * @example
+     * ```typescript
+     * createRouter({
+     *   timeout: 10_000,
+     *   onTimeout: (ctx) => {
+     *     return new Response(
+     *       JSON.stringify({ error: "timeout", phase: ctx.phase }),
+     *       { status: 504, headers: { "Content-Type": "application/json" } },
+     *     );
+     *   },
+     * });
+     * ```
+     */
+    onTimeout?: OnTimeoutCallback<TEnv>;
+    /**
+     * Telemetry sink for structured, discrete lifecycle EVENTS: request
+     * start/end/error, loader start/end/error, handler errors, cache decisions,
+     * revalidation decisions, timeouts, origin rejections.
+     *
+     * This is the EVENT surface. Phase-duration SPANS (request/middleware/action/
+     * handler/loader/render/ssr timing wired into a tracing backend) come from the
+     * separate `tracing` option below — a sink does not emit them, because async-context nesting
+     * cannot be faithfully reconstructed from after-the-fact start/end events.
+     *
+     * No-op when not configured (zero overhead).
+     *
+     * @example Console logging
+     * ```typescript
+     * import { createConsoleSink } from "@rangojs/router";
+     *
+     * const router = createRouter({
+     *   telemetry: createConsoleSink(),
+     * });
+     * ```
+     *
+     * @example OpenTelemetry — pair the event sink with the tracing slot
+     * ```typescript
+     * import { createOTelTracing, createOTelSink } from "@rangojs/router";
+     * import { trace } from "@opentelemetry/api";
+     *
+     * const tracer = trace.getTracer("my-app");
+     * const router = createRouter({
+     *   tracing: createOTelTracing(tracer), // phase spans
+     *   telemetry: createOTelSink(tracer), // discrete-fact events
+     * });
+     * ```
+     *
+     * @example Custom sink
+     * ```typescript
+     * const router = createRouter({
+     *   telemetry: {
+     *     emit(event) {
+     *       myTracer.record(event);
+     *     },
+     *   },
+     * });
+     * ```
+     */
+    telemetry?: TelemetrySink;
+    /**
+     * Span tracing for the router's performance phases (request, middleware, action,
+     * loaders, render, ssr). Connects the same phases shown in the
+     * `debugPerformance` timeline to the host platform's tracing system. This is
+     * the SPAN surface (the `telemetry` option above is the event surface).
+     *
+     * Two factories produce a config, both for this slot:
+     * - `createOTelTracing(tracer)` from `@rangojs/router` — any platform with an
+     *   OpenTelemetry SDK (including Node). Bridges the phases onto
+     *   `tracer.startActiveSpan`.
+     * - `createCloudflareTracing()` from `@rangojs/router/cloudflare` — Cloudflare
+     *   Workers native custom spans, alongside the automatic KV/D1/fetch spans.
+     *
+     * When tracing is unset — or off-platform (no OTel SDK / no Cloudflare tracing
+     * destination) — every span call falls through to the work directly, so the
+     * request behaves exactly as if tracing were off.
+     *
+     * @example OpenTelemetry
+     * ```typescript
+     * import { createOTelTracing } from "@rangojs/router";
+     * import { trace } from "@opentelemetry/api";
+     *
+     * const router = createRouter({
+     *   tracing: createOTelTracing(trace.getTracer("my-app")),
+     * });
+     * ```
+     *
+     * @example Cloudflare
+     * ```typescript
+     * import { createCloudflareTracing } from "@rangojs/router/cloudflare";
+     *
+     * const router = createRouter({
+     *   tracing: createCloudflareTracing({ spans: { ssr: false } }),
+     * });
+     * ```
+     */
+    tracing?: RouterTracingConfig;
+    /**
+     * SSR configuration options.
+     *
+     * @example
+     * ```typescript
+     * createRouter({
+     *   ssr: {
+     *     resolveStreaming: async ({ request, env }) => {
+     *       const bot = await detectBot(request, env);
+     *       return bot.isBot ? "allReady" : "stream";
+     *     },
+     *   },
+     * });
+     * ```
+     */
+    ssr?: SSROptions<TEnv>;
+    /**
+     * Cross-origin request protection for server actions, loader fetches,
+     * and progressive enhancement form submissions.
+     *
+     * When enabled, the router validates that the request's Origin header
+     * (or Referer fallback) matches the Host before executing actions,
+     * loaders, or PE submissions. Requests without Origin/Referer are
+     * allowed (same-origin navigations, non-browser clients).
+     *
+     * The built-in check compares Origin against the Host header and
+     * url.protocol. It does NOT trust X-Forwarded-Host/Proto headers
+     * (they are client-controllable without a trusted proxy). On standard
+     * deployments (Cloudflare Workers, Node behind nginx/caddy) the Host
+     * header is already set to the public-facing host by the platform or
+     * proxy. For non-standard proxy setups where Host differs from the
+     * public origin, use a custom function that reads the appropriate
+     * forwarded headers from your trusted proxy.
+     *
+     * - `true` (default) -- enable built-in origin validation
+     * - `false` -- disable
+     * - function -- full custom control with access to env, phase,
+     *   and the built-in check via `ctx.defaultCheck()`
+     *
+     * The callback receives `OriginCheckContext` with `request`, `url`,
+     * `env`, `routerId`, `phase` ("action" | "loader" | "pe-form"),
+     * and `defaultCheck()`. Return `true` to allow, `false` for default
+     * 403 rejection, or a `Response` for custom rejection.
+     *
+     * @default true
+     *
+     * @example Trusted proxy with X-Forwarded-Host
+     * ```ts
+     * createRouter({
+     *   originCheck({ request, url, env, defaultCheck }) {
+     *     if (env.TRUST_PROXY) {
+     *       const origin = request.headers.get("origin");
+     *       if (!origin) return true;
+     *       if (origin === "null") return false;
+     *       const host = request.headers.get("x-forwarded-host")
+     *         ?? request.headers.get("host") ?? url.host;
+     *       return origin.toLowerCase() === `${url.protocol}//${host}`.toLowerCase();
+     *     }
+     *     return defaultCheck();
+     *   },
+     * });
+     * ```
+     */
+    originCheck?: import("../rsc/origin-guard.js").OriginCheckConfig<TEnv>;
+}