@qwik.dev/router 2.0.0-beta.36 → 2.0.0-beta.38

package/lib/index.d.ts

@@ -1,13 +1,16 @@
 /// <reference path="./modules.d.ts" />
 
-import type { AsyncSignal } from '@qwik.dev/core';
+import type { AbortMessage } from '@qwik.dev/router/middleware/request-handler';
 import { Component } from '@qwik.dev/core';
+import type { ComputedSignal } from '@qwik.dev/core';
 import { Cookie } from '@qwik.dev/router/middleware/request-handler';
 import { CookieOptions } from '@qwik.dev/router/middleware/request-handler';
 import { CookieValue } from '@qwik.dev/router/middleware/request-handler';
 import { DeferReturn } from '@qwik.dev/router/middleware/request-handler';
 import type { EnvGetter } from '@qwik.dev/router/middleware/request-handler';
+import { InternalRequest } from '@qwik.dev/router/middleware/request-handler';
 import { JSXOutput } from '@qwik.dev/core';
+import { NoSerialize } from '@qwik.dev/core';
 import { QRL } from '@qwik.dev/core';
 import { QRLEventHandlerMulti } from '@qwik.dev/core';
 import { QwikIntrinsicElements } from '@qwik.dev/core';
@@ -22,6 +25,7 @@ import { RequestEventLoader } from '@qwik.dev/router/middleware/request-handler'
 import { RequestHandler } from '@qwik.dev/router/middleware/request-handler';
 import type { ResolveSyncValue } from '@qwik.dev/router/middleware/request-handler';
 import type { SerializationStrategy } from '@qwik.dev/core/internal';
+import type { ServerError } from '@qwik.dev/router/middleware/request-handler';
 import type { Signal } from '@qwik.dev/core';
 import type * as v from 'valibot';
 import type { ValueOrPromise } from '@qwik.dev/core';
@@ -36,51 +40,53 @@ export declare type Action<RETURN, INPUT = Record<string, unknown>, OPTIONAL ext
      * component$(). Like all `use-` functions and methods, it can only be invoked within a
      * `component$()`.
      */
-    (): ActionStore<RETURN, INPUT, OPTIONAL>;
+    (): ActionStore<ExcludeControlFlow<RETURN>, INPUT, OPTIONAL>;
 };
 
 /** @public */
 export declare type ActionConstructor = {
-    <OBJ extends Record<string, any> | void | null, VALIDATOR extends TypedDataValidator, REST extends [DataValidator, ...DataValidator[]]>(actionQrl: (data: GetValidatorOutputType<VALIDATOR>, event: RequestEventAction) => ValueOrPromise<OBJ>, options: {
-        readonly id?: string;
+    <OBJ extends Record<string, any> | void | null, VALIDATOR extends TypedDataValidator, REST extends [DataValidator, ...DataValidator[]]>(actionQrl: (data: GetValidatorOutputType<VALIDATOR>, event: RequestEventAction) => ValueOrPromise<OBJ>, options: ActionOptions & {
         readonly validation: [VALIDATOR, ...REST];
     }): Action<StrictUnion<OBJ | FailReturn<ValidatorErrorType<GetValidatorInputType<VALIDATOR>>> | FailReturn<FailOfRest<REST>>>, GetValidatorInputType<VALIDATOR>, false>;
-    <OBJ extends Record<string, any> | void | null, VALIDATOR extends TypedDataValidator>(actionQrl: (data: GetValidatorOutputType<VALIDATOR>, event: RequestEventAction) => ValueOrPromise<OBJ>, options: {
-        readonly id?: string;
+    <OBJ extends Record<string, any> | void | null, VALIDATOR extends TypedDataValidator>(actionQrl: (data: GetValidatorOutputType<VALIDATOR>, event: RequestEventAction) => ValueOrPromise<OBJ>, options: ActionOptions & {
         readonly validation: [VALIDATOR];
     }): Action<StrictUnion<OBJ | FailReturn<ValidatorErrorType<GetValidatorInputType<VALIDATOR>>>>, GetValidatorInputType<VALIDATOR>, false>;
-    <OBJ extends Record<string, any> | void | null, REST extends [DataValidator, ...DataValidator[]]>(actionQrl: (data: JSONObject, event: RequestEventAction) => ValueOrPromise<OBJ>, options: {
-        readonly id?: string;
+    <OBJ extends Record<string, any> | void | null, REST extends [DataValidator, ...DataValidator[]]>(actionQrl: (data: JSONObject, event: RequestEventAction) => ValueOrPromise<OBJ>, options: ActionOptions & {
         readonly validation: REST;
     }): Action<StrictUnion<OBJ | FailReturn<FailOfRest<REST>>>>;
     <OBJ extends Record<string, any> | void | null, VALIDATOR extends TypedDataValidator, REST extends [DataValidator, ...DataValidator[]]>(actionQrl: (data: GetValidatorOutputType<VALIDATOR>, event: RequestEventAction) => ValueOrPromise<OBJ>, options: VALIDATOR, ...rest: REST): Action<StrictUnion<OBJ | FailReturn<ValidatorErrorType<GetValidatorInputType<VALIDATOR>>> | FailReturn<FailOfRest<REST>>>, GetValidatorInputType<VALIDATOR>, false>;
     <OBJ extends Record<string, any> | void | null, VALIDATOR extends TypedDataValidator>(actionQrl: (data: GetValidatorOutputType<VALIDATOR>, event: RequestEventAction) => ValueOrPromise<OBJ>, options: VALIDATOR): Action<StrictUnion<OBJ | FailReturn<ValidatorErrorType<GetValidatorInputType<VALIDATOR>>>>, GetValidatorInputType<VALIDATOR>, false>;
     <OBJ extends Record<string, any> | void | null, REST extends [DataValidator, ...DataValidator[]]>(actionQrl: (form: JSONObject, event: RequestEventAction) => ValueOrPromise<OBJ>, ...rest: REST): Action<StrictUnion<OBJ | FailReturn<FailOfRest<REST>>>>;
-    <OBJ>(actionQrl: (form: JSONObject, event: RequestEventAction) => ValueOrPromise<OBJ>, options?: {
-        readonly id?: string;
-    }): Action<StrictUnion<OBJ>>;
+    <OBJ>(actionQrl: (form: JSONObject, event: RequestEventAction) => ValueOrPromise<OBJ>, options?: ActionOptions): Action<StrictUnion<OBJ>>;
 };
 
 /** @public */
 declare type ActionConstructorQRL = {
-    <OBJ extends Record<string, any> | void | null, VALIDATOR extends TypedDataValidator, REST extends [DataValidator, ...DataValidator[]]>(actionQrl: QRL<(data: GetValidatorOutputType<VALIDATOR>, event: RequestEventAction) => ValueOrPromise<OBJ>>, options: {
-        readonly id?: string;
+    <OBJ extends Record<string, any> | void | null, VALIDATOR extends TypedDataValidator, REST extends [DataValidator, ...DataValidator[]]>(actionQrl: QRL<(data: GetValidatorOutputType<VALIDATOR>, event: RequestEventAction) => ValueOrPromise<OBJ>>, options: ActionOptions & {
         readonly validation: [VALIDATOR, ...REST];
     }): Action<StrictUnion<OBJ | FailReturn<ValidatorErrorType<GetValidatorInputType<VALIDATOR>>> | FailReturn<FailOfRest<REST>>>, GetValidatorInputType<VALIDATOR>, false>;
-    <OBJ extends Record<string, any> | void | null, VALIDATOR extends TypedDataValidator>(actionQrl: QRL<(data: GetValidatorOutputType<VALIDATOR>, event: RequestEventAction) => ValueOrPromise<OBJ>>, options: {
-        readonly id?: string;
+    <OBJ extends Record<string, any> | void | null, VALIDATOR extends TypedDataValidator>(actionQrl: QRL<(data: GetValidatorOutputType<VALIDATOR>, event: RequestEventAction) => ValueOrPromise<OBJ>>, options: ActionOptions & {
         readonly validation: [VALIDATOR];
     }): Action<StrictUnion<OBJ | FailReturn<ValidatorErrorType<GetValidatorInputType<VALIDATOR>>>>, GetValidatorInputType<VALIDATOR>, false>;
-    <OBJ extends Record<string, any> | void | null, REST extends [DataValidator, ...DataValidator[]]>(actionQrl: QRL<(data: JSONObject, event: RequestEventAction) => ValueOrPromise<OBJ>>, options: {
-        readonly id?: string;
+    <OBJ extends Record<string, any> | void | null, REST extends [DataValidator, ...DataValidator[]]>(actionQrl: QRL<(data: JSONObject, event: RequestEventAction) => ValueOrPromise<OBJ>>, options: ActionOptions & {
         readonly validation: REST;
     }): Action<StrictUnion<OBJ | FailReturn<FailOfRest<REST>>>>;
     <OBJ extends Record<string, any> | void | null, VALIDATOR extends TypedDataValidator, REST extends [DataValidator, ...DataValidator[]]>(actionQrl: QRL<(data: GetValidatorOutputType<VALIDATOR>, event: RequestEventAction) => ValueOrPromise<OBJ>>, options: VALIDATOR, ...rest: REST): Action<StrictUnion<OBJ | FailReturn<ValidatorErrorType<GetValidatorInputType<VALIDATOR>>> | FailReturn<FailOfRest<REST>>>, GetValidatorInputType<VALIDATOR>, false>;
     <OBJ extends Record<string, any> | void | null, VALIDATOR extends TypedDataValidator>(actionQrl: QRL<(data: GetValidatorOutputType<VALIDATOR>, event: RequestEventAction) => ValueOrPromise<OBJ>>, options: VALIDATOR): Action<StrictUnion<OBJ | FailReturn<ValidatorErrorType<GetValidatorInputType<VALIDATOR>>>>, GetValidatorInputType<VALIDATOR>, false>;
     <OBJ extends Record<string, any> | void | null, REST extends [DataValidator, ...DataValidator[]]>(actionQrl: QRL<(form: JSONObject, event: RequestEventAction) => ValueOrPromise<OBJ>>, ...rest: REST): Action<StrictUnion<OBJ | FailReturn<FailOfRest<REST>>>>;
-    <OBJ>(actionQrl: QRL<(form: JSONObject, event: RequestEventAction) => ValueOrPromise<OBJ>>, options?: {
-        readonly id?: string;
-    }): Action<StrictUnion<OBJ>>;
+    <OBJ>(actionQrl: QRL<(form: JSONObject, event: RequestEventAction) => ValueOrPromise<OBJ>>, options?: ActionOptions): Action<StrictUnion<OBJ>>;
+};
+
+/** @public */
+export declare type ActionOptions = {
+    readonly id?: string;
+    readonly validation?: DataValidator[];
+    /**
+     * Route loaders to invalidate after this action completes. The loader hooks' hashes are sent to
+     * the client so it knows which loaders to re-fetch. If omitted, ALL route loaders are invalidated
+     * (unless `strictLoaders` is enabled globally in the Vite plugin).
+     */
+    readonly invalidate?: Loader_2<any>[];
 };
 
 /** @public */
@@ -162,15 +168,25 @@ export declare type ActionStore<RETURN, INPUT, OPTIONAL extends boolean = true>
 declare type AnchorAttributes = QwikIntrinsicElements['a'];
 
 /**
- * The cacheKey export type. When exported from a page module alongside eTag, enables in-memory SSR
- * caching.
+ * Cache key function. Used by `routeConfig.cacheKey` (SSR HTML cache) and by `routeLoader$`'s
+ * `cacheKey` option (per-loader JSON cache).
+ *
+ * - `true`: use the surface's default key.
  *
- * - `true`: use the default cache key `status|eTag|pathname`
- * - Function: receives status, eTag, and pathname; returns a cache key string or null (no cache)
+ *   - SSR default: `${status}|${eTag}|${pathname}` when an eTag is set, otherwise
+ *       `${status}|${pathname}`.
+ *   - Loader default: `${pathname}|${filteredSearch}|${loaderId}|${eTag}` when an eTag is set,
+ *       otherwise `${pathname}|${filteredSearch}|${loaderId}`.
+ * - Function: receives the request event and the normalized, unquoted eTag (or an empty string when
+ *   none was provided). Return the cache key string, or `null` or `''` to skip caching for this
+ *   request. Loader callbacks receive the loader-scoped request event, with `url`, `query`, and
+ *   `request.url` filtered by the loader's `search` allowlist.
+ *
+ * Note: valid cacheKeys are non-empty strings.
  *
  * @public
  */
-export declare type CacheKeyFn = true | ((status: number, eTag: string, pathname: string) => string | null);
+export declare type CacheKeyFn = true | ((requestEv: RequestEvent, eTag: string) => string | null);
 
 /** @public */
 export declare interface ContentHeading {
@@ -189,7 +205,18 @@ export declare interface ContentMenu {
 declare type ContentModule = PageModule | LayoutModule;
 
 /**
- * The eTag export type: a static string or a function receiving DocumentHeadProps.
+ * The eTag export type for routeConfig.
+ *
+ * - `string` — static ETag value.
+ * - `(props: DocumentHeadProps) => string | null` — compute the ETag from route context (params, URL,
+ *   loaded data via `resolveValue`, etc.). Return `null` to skip eTag for this request.
+ *
+ * Qwik normalizes eTag values by stripping weak-form `W/` prefixes, quotes, and forbidden chars,
+ * then sends a strong `ETag` header. Values that normalize to an empty string are treated as
+ * absent.
+ *
+ * When set (and a value is produced), the server includes an `ETag` header and returns `304` if
+ * `If-None-Match` matches.
  *
  * @public
  */
@@ -357,10 +384,10 @@ declare type EndpointModuleLoader = () => ValueOrPromise<RouteModule>;
 declare interface EndpointResponse {
     status: number;
     statusMessage?: string;
-    loaders: Record<string, unknown>;
-    loadersSerializationStrategy: Map<string, SerializationStrategy>;
     formData?: FormData;
     action?: string;
+    actionResult?: unknown;
+    loaderHashes?: string[];
 }
 
 /** @public */
@@ -371,6 +398,14 @@ declare interface ErrorBoundaryProps {
     fallback$?: QRL<(error: any) => any>;
 }
 
+/**
+ * Drops control-flow signals (`ev.redirect()`, `ev.error()`, etc.) from a loader/action return
+ * type: those are thrown, not surfaced as data. `ev.fail()` is plain data and is kept.
+ *
+ * @public
+ */
+export declare type ExcludeControlFlow<T> = Exclude<T, AbortMessage | ServerError>;
+
 declare type Failed = {
     failed: true;
 };
@@ -411,6 +446,14 @@ export declare interface FormSubmitSuccessDetail<T> {
     value: T;
 }
 
+/**
+ * Returns the current RequestEvent if possible. Only usable on the server, and only during request
+ * processing.
+ *
+ * @public
+ */
+export declare const getRequestEvent: (thisArg?: unknown) => RequestEvent | undefined;
+
 /** @public */
 export declare type GetValidatorInputType<VALIDATOR extends TypedDataValidator> = VALIDATOR extends ValibotDataValidator<infer TYPE> ? v.InferInput<TYPE> : VALIDATOR extends ZodDataValidator<infer TYPE> ? z_2.input<TYPE> : never;
 
@@ -433,6 +476,8 @@ export declare type HttpErrorProps = {
     message: string;
 };
 
+export { InternalRequest }
+
 declare type IsAny<Type> = 0 extends 1 & Type ? true : false;
 
 /** @public */
@@ -457,8 +502,8 @@ export declare const Link: Component<LinkProps>;
 /** @public */
 export declare interface LinkProps extends AnchorAttributes {
     /**
-     * @deprecated Use `prefetchBundle` and `prefetchData` instead for more granular control over what
-     *   is prefetched and when. This prop will be removed in a future major version.
+     * @deprecated Use `prefetchBundles` and `prefetchData` instead for more granular control over
+     *   what is prefetched and when. This prop will be removed in a future major version.
      *
      *   Legacy prefetch control for this **`Link`**.
      *
@@ -476,7 +521,7 @@ export declare interface LinkProps extends AnchorAttributes {
      *
      * Prefetching will not occur if the user has the **data saver** setting enabled.
      */
-    prefetchBundle?: PrefetchStrategy;
+    prefetchBundles?: PrefetchStrategy;
     /**
      * Controls when Qwik should prefetch and cache route data for this **`Link`** target, including
      * invoking any **`routeLoader$`**, **`onGet`**, etc.
@@ -509,8 +554,12 @@ declare interface LoadedRoute {
     $routeBundleNames$?: string[] | undefined;
     /** Whether this route is a not-found (404) route */
     $notFound$?: boolean;
-    /** The error module loader (nearest _E ancestor), for rendering ServerErrors */
-    $errorLoader$?: ContentModuleLoader;
+    /** The nearest _E (error.tsx) boundary's chain to render on a thrown ServerError (in its layouts). */
+    $errorLoader$?: ModuleLoader[];
+    /** Merged array of routeLoader$ hashes from all matched nodes (layouts + page) */
+    $loaders$?: string[];
+    /** Runtime-only mapping of routeLoader$ hashes to the matched pathname used for q-loader fetches */
+    $loaderPaths$?: Record<string, string>;
 }
 
 /** @public */
@@ -519,7 +568,7 @@ declare type Loader_2<RETURN> = {
      * Returns the `Signal` containing the data returned by the `loader$` function. Like all `use-`
      * functions and methods, it can only be invoked within a `component$()`.
      */
-    (): LoaderSignal<RETURN>;
+    (): LoaderSignal<ExcludeControlFlow<RETURN>>;
 };
 export { Loader_2 as Loader }
 
@@ -537,13 +586,98 @@ declare type LoaderConstructorQRL = {
 
 /** @public */
 declare type LoaderOptions = {
+    /**
+     * Explicit loader id, overriding the QRL hash. Pass a distinct value (e.g. `fn.getHash()`) when
+     * loaders share a wrapper QRL.
+     */
     readonly id?: string;
     readonly validation?: DataValidator[];
     readonly serializationStrategy?: SerializationStrategy;
+    /**
+     * Time in milliseconds after which the loader data is considered stale. The server derives
+     * `Cache-Control: max-age` seconds from this value on loader responses.
+     *
+     * On the client, the loader's ComputedSignal `expires` is set to this value. If `poll` is true,
+     * the signal auto-refetches when expired. If `poll` is false (default), the data is marked stale
+     * but not auto-refetched.
+     */
+    readonly expires?: number;
+    /**
+     * When true AND `expires` is set, the loader data is automatically refetched when it expires
+     * (polling behavior). When false (default), expired data is marked stale but not auto-refetched.
+     */
+    readonly poll?: boolean;
+    /**
+     * Enable ETag-based caching for this loader's JSON responses.
+     *
+     * - `string` — static ETag value; if `If-None-Match` matches, the loader is skipped entirely
+     * - `(ev: RequestEvent) => string | null` — compute the ETag from the request context (params, URL,
+     *   headers, etc.); if `If-None-Match` matches, the loader is skipped entirely. Return null to
+     *   skip eTag for this request.
+     *
+     * Qwik normalizes eTag values by stripping weak-form `W/` prefixes, quotes, and forbidden chars,
+     * then sends a strong `ETag` header. Values that normalize to an empty string are treated as
+     * absent.
+     *
+     * When set, the server includes an `ETag` header on `q-loader-*.json` responses and returns `304`
+     * if the client sends a matching `If-None-Match` header.
+     *
+     * For auto-computed eTags, use `cacheKey` instead — on cache write the eTag is hashed from the
+     * serialized response and stored alongside it, so subsequent hits get the same eTag.
+     */
+    readonly eTag?: string | ((ev: RequestEvent) => string | null);
+    /**
+     * Enable in-memory server-side caching of this loader's serialized JSON response.
+     *
+     * - `true` — use the default key `${pathname}|${filteredSearch}|${loaderId}` (suffixed with
+     *   `|${eTag}` when an eTag is set).
+     * - Function `(requestEv, eTag) => string | null` — return a custom key, or `null` to skip caching
+     *   this request.
+     *
+     * On cache miss the loader runs, the serialized response is stored alongside its eTag (computed
+     * from the data when no `eTag` option is set), and the response is sent. On cache hit the stored
+     * `{ eTag, data }` pair is served directly — `If-None-Match` is checked against the stored eTag
+     * and a `304` is returned when it matches.
+     */
+    readonly cacheKey?: CacheKeyFn;
+    /**
+     * Allowlist of URL search parameter names that this loader depends on.
+     *
+     * When set, the loader only re-fetches when the listed search params change — other param changes
+     * are ignored. Only the listed params are sent in the loader JSON request URL. During SSR and
+     * loader JSON requests, the loader receives a request event with `url`, `query`, and
+     * `request.url` filtered to the same params.
+     *
+     * When not set, the `qwikRouter()` plugin option `strictLoaders` determines the behavior. If
+     * `strictLoaders` is `true` (this is the default), no search params are sent and changes do not
+     * trigger a re-fetch. If `strictLoaders` is `false`, all search params are sent and any change
+     * triggers a re-fetch.
+     */
+    readonly search?: string[];
+    /**
+     * When true (default), the previous value is kept while the loader re-fetches after navigation,
+     * so components see stale data until the new response arrives.
+     *
+     * When false, the value is cleared on re-fetch, causing reads to suspend (show a loading
+     * boundary). This is useful when showing old data during navigation would be confusing.
+     */
+    readonly allowStale?: boolean;
+    /**
+     * When true (default), the loader is awaited before SSR renders, so its redirect or error can
+     * short-circuit the response and its value is ready for synchronous reads (e.g. in the head).
+     *
+     * When false, the loader runs in the background without blocking SSR: rendering starts
+     * immediately and reading its `.value` suspends until it resolves. A background loader cannot
+     * redirect or error the initial SSR response; treat it as a separate request.
+     *
+     * Setting `false` is experimental and requires adding `experimental: ["blockSSR"]` to your
+     * qwikVite plugin options.
+     */
+    readonly blockSSR?: boolean;
 };
 
 /** @public */
-export declare type LoaderSignal<TYPE> = (TYPE extends () => ValueOrPromise<infer VALIDATOR> ? Signal<ValueOrPromise<VALIDATOR>> : Signal<TYPE>) & Pick<AsyncSignal, 'promise' | 'loading' | 'error'>;
+export declare type LoaderSignal<TYPE> = (TYPE extends () => ValueOrPromise<infer VALIDATOR> ? Signal<ValueOrPromise<VALIDATOR>> : Signal<TYPE>) & Pick<ComputedSignal<any>, 'promise' | 'pending' | 'error' | 'loading'>;
 
 declare interface MenuModule {
     readonly default: ContentMenu;
@@ -673,6 +807,8 @@ export declare interface QwikRouterEnvData {
     params: PathParams;
     response: EndpointResponse;
     loadedRoute: LoadedRoute;
+    routeLoaderCtx: RouteLoaderCtx;
+    loaderValues: Record<string, unknown>;
 }
 
 /** @public */
@@ -739,9 +875,9 @@ export declare const QwikRouterMockProvider: Component<QwikRouterMockProps>;
 /** @public */
 export declare interface QwikRouterProps {
     /**
-     * Enable the ViewTransition API
+     * Enable the ViewTransition API on SPA navigation. Opt-in: set to `true` to enable.
      *
-     * Default: `true`
+     * Default: `false`
      *
      * @see https://github.com/WICG/view-transitions/blob/main/explainer.md
      * @see https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API
@@ -783,10 +919,30 @@ export declare type ResolvedDocumentHead<FrontMatter extends Record<string, any>
     readonly manifestHash: string;
 };
 
-/** @public */
+/**
+ * Define a route action that handles form submissions or programmatic invocations.
+ *
+ * Actions run on the server when submitted from the client. The result is returned as an
+ * `ActionStore` with `.value` for success data and `.error` for errors (including validation errors
+ * from `zod$`/`valibot$` where `.fieldErrors` etc. are accessible directly on `.error`).
+ *
+ * By default, after an action completes, ALL current route loaders are invalidated on the client
+ * and re-fetched as needed (so that the browser cache is correct). This can be controlled with:
+ *
+ * - `invalidate: [loader1, loader2]`: Only invalidate specific loaders. The client re-fetches them
+ *   individually. Other loaders keep their current data.
+ * - `invalidate: []`: No loaders are invalidated. The action response only contains the action
+ *   result. Use this when the action doesn't affect any loader data.
+ *
+ * The `strictLoaders` Vite plugin option applies `invalidate: []` globally for all actions that
+ * don't specify an explicit `invalidate` option.
+ *
+ * @public
+ */
 export declare const routeAction$: ActionConstructor;
 
-/* Excluded from this release type: routeActionQrl */
+/** @public */
+export declare const routeActionQrl: ActionConstructorQRL;
 
 declare type RouteActionResolver = {
     status: number;
@@ -843,10 +999,13 @@ export declare interface RouteData {
     _G?: string;
     /** The JS bundle names for this route (SSR only) */
     _B?: string[];
-    /** The not-found (404) module loader for this subtree */
-    _4?: ContentModuleLoader;
-    /** The error page module loader for this subtree (error.tsx, takes precedence over _4) */
-    _E?: ContentModuleLoader;
+    /**
+     * Not-found (404) boundary: single loader (runtime prepends layouts) or override chain
+     * (`404@layout`/`!`).
+     */
+    _4?: ContentModuleLoader | ModuleLoader[];
+    /** Error (error.tsx) boundary, same single-or-override-chain shape as `_4`. */
+    _E?: ContentModuleLoader | ModuleLoader[];
     /** The parameter name when this node is reached via `_W` or `_A` from the parent */
     _P?: string;
     /** Prefix for infix params (e.g. "pre" for `pre[slug]post`) — only on `_W` nodes */
@@ -857,13 +1016,61 @@ export declare interface RouteData {
     _M?: RouteData[];
     /** Menu loader for this subtree (from menu.md). Runtime uses nearest ancestor during traversal. */
     _N?: MenuModuleLoader;
+    /** Array of routeLoader$ hashes for this node's loaders */
+    _R?: string[];
     /** Child route segments (any key not starting with `_`) */
     [part: string]: RouteData | RouteData[] | ModuleLoader[] | ContentModuleLoader | MenuModuleLoader | string[] | string | undefined;
 }
 
-/** @public */
+/**
+ * Define a route loader that fetches data before the route renders.
+ *
+ * Route loaders run on the server during SSR and return data as a `ComputedSignal`. On the client,
+ * loaders automatically re-fetch when the route changes (SPA navigation). Each loader gets its own
+ * JSON endpoint (`q-loader-{id}.{hash}.json`), so only the loaders present on the target route are
+ * fetched.
+ *
+ * **Important:** Route loader data uses Qwik's custom serialization format, not standard JSON. This
+ * means the data supports features like circular references, Dates, and other non-JSON types, but
+ * it cannot be consumed by external clients expecting plain JSON.
+ *
+ * ## Options
+ *
+ * - `search: string[]`: Allowlist of URL search params the loader depends on. Only listed params are
+ *   sent in the request and changes to other params are ignored. During SSR and loader JSON
+ *   requests, the loader's request event is filtered to those params too. `search: []` means no
+ *   search params are sent and only route path changes trigger a re-fetch.
+ * - `allowStale: false`: Clears the previous value when re-fetching, so components see a loading
+ *   state instead of stale data during navigation. Useful when old data would be confusing.
+ * - `eTag`: Enable ETag-based caching. Can be `true` (auto-hash), a string, or a function.
+ * - `expires` / `poll`: Control client-side caching and polling behavior.
+ *
+ * The `strictLoaders` Vite plugin option applies `search: []` globally for all loaders that don't
+ * specify an explicit `search` option.
+ *
+ * @public
+ */
 export declare const routeLoader$: LoaderConstructor;
 
+/**
+ * Reactive context for route loaders. On the server this is stored in sharedMap, on the client it's
+ * a store that gets updated on navigation.
+ *
+ * - `loaderPaths`: loader ID → fetch path (the longest route path for that loader)
+ * - `pagePathname` / `pageSearch`: client-only navigation state used for loader invalidation and
+ *   q-loader fetches. They are intentionally omitted from SSR state and fall back to `location`
+ *   until the first SPA navigation.
+ */
+declare type RouteLoaderCtx = {
+    loaderPaths: Record<string, string | undefined>;
+    pagePathname?: string;
+    pageSearch?: string;
+    /** SPA navigation function. Client-only and intentionally omitted from SSR state. */
+    goto?: NoSerialize<RouteNavigate>;
+    /** Client manifest hash for q-loader fetch URLs. */
+    manifestHash?: string;
+};
+
 /* Excluded from this release type: routeLoaderQrl */
 
 /** @public */