@qwik.dev/router 2.0.0-beta.37 → 2.0.0-beta.39

package/lib/chunks/worker-thread.mjs

@@ -0,0 +1,317 @@
+import { _serialize } from '@qwik.dev/core/internal';
+import { parentPort } from 'node:worker_threads';
+import { r as runQwikRouter, a as resolveRequestHandlers, b as renderQwikMiddleware } from './user-response.mjs';
+import { b as trimInternalPathname } from './request-path.mjs';
+import { I as getRouteLoaders, J as getRouteLoaderValues, l as loadRoute } from './head.qwik.mjs';
+
+const staticWorkerThreadDeps = {
+  loadRoute,
+  renderQwikMiddleware,
+  resolveRequestHandlers,
+  trimInternalPathname,
+  runQwikRouter
+};
+const createNoopWritableStream = () => new WritableStream();
+function isRedirectMessage(value) {
+  return typeof value === "object" && value !== null && value.constructor?.name === "RedirectMessage";
+}
+async function requestHandlerForSsg(serverRequestEv, opts, deps) {
+  const { render, checkOrigin, qwikRouterConfig } = opts;
+  if (!qwikRouterConfig) {
+    throw new Error("qwikRouterConfig is required.");
+  }
+  const pathname = deps.trimInternalPathname(serverRequestEv.url.pathname);
+  if (pathname === "/.well-known" || pathname.startsWith("/.well-known/")) {
+    return null;
+  }
+  const { routes, serverPlugins, cacheModules } = qwikRouterConfig;
+  const loadedRoute = await deps.loadRoute(routes, cacheModules, pathname);
+  const requestHandlers = deps.resolveRequestHandlers(serverPlugins, loadedRoute, serverRequestEv.request.method, checkOrigin ?? true, deps.renderQwikMiddleware(render));
+  if (qwikRouterConfig.fallthrough && loadedRoute.$notFound$ && !pathname.endsWith("/404.html")) {
+    return null;
+  }
+  const rebuildRouteInfo = async (url) => {
+    const cleanPathname = deps.trimInternalPathname(url.pathname);
+    const loadedRoute2 = await deps.loadRoute(routes, cacheModules, cleanPathname);
+    const requestHandlers2 = deps.resolveRequestHandlers(serverPlugins, loadedRoute2, serverRequestEv.request.method, checkOrigin ?? true, deps.renderQwikMiddleware(render));
+    return {
+      loadedRoute: loadedRoute2,
+      requestHandlers: requestHandlers2
+    };
+  };
+  return deps.runQwikRouter(serverRequestEv, loadedRoute, requestHandlers, rebuildRouteInfo, qwikRouterConfig.basePathname);
+}
+async function workerRender(sys, opts, staticRoute, pendingPromises, callback, deps) {
+  const url = new URL(staticRoute.pathname, opts.origin);
+  const result = {
+    type: "render",
+    pathname: staticRoute.pathname,
+    url: url.href,
+    ok: false,
+    error: null,
+    filePath: null,
+    contentType: null,
+    resourceType: null
+  };
+  try {
+    let routeWriter = null;
+    let closeResolved;
+    const closePromise = new Promise((closePromiseResolve) => {
+      closeResolved = closePromiseResolve;
+    });
+    const request = new Request(url);
+    const requestCtx = {
+      mode: "static",
+      locale: void 0,
+      url,
+      request,
+      env: {
+        get(key) {
+          return sys.getEnv(key);
+        }
+      },
+      platform: sys.platform,
+      getClientConn: () => {
+        return {};
+      },
+      getWritableStream: (status, headers, _, _r, requestEv) => {
+        const isNotFoundPage = url.pathname.endsWith("/404.html");
+        result.ok = status >= 200 && status < 300 || isNotFoundPage && status === 404;
+        if (!result.ok) {
+          return createNoopWritableStream();
+        }
+        result.contentType = (headers.get("Content-Type") || "").toLowerCase();
+        const isHtml = result.contentType.includes("text/html");
+        const routeFilePath = sys.getRouteFilePath(url.pathname, isHtml);
+        if (isHtml) {
+          result.resourceType = "page";
+        }
+        const hasRouteWriter = isHtml ? opts.emitHtml !== false : true;
+        const writeLoaderDataEnabled = isHtml && opts.emitData !== false;
+        const stream = new WritableStream({
+          async start() {
+            try {
+              if (hasRouteWriter || writeLoaderDataEnabled) {
+                await sys.ensureDir(routeFilePath);
+              }
+              if (hasRouteWriter) {
+                routeWriter = sys.createWriteStream(routeFilePath);
+                routeWriter.on("error", (e) => {
+                  console.error(e);
+                  routeWriter = null;
+                  result.error = {
+                    message: e.message,
+                    stack: e.stack
+                  };
+                });
+              }
+            } catch (e) {
+              console.error("Error during stream start", staticRoute.pathname, e);
+              routeWriter = null;
+              result.error = {
+                message: String(e),
+                stack: e.stack || ""
+              };
+            }
+          },
+          write(chunk) {
+            try {
+              if (routeWriter) {
+                routeWriter.write(Buffer.from(chunk.buffer));
+              }
+            } catch (e) {
+              console.error("Error during stream write", staticRoute.pathname, e);
+              routeWriter = null;
+              result.error = {
+                message: String(e),
+                stack: e.stack || ""
+              };
+            }
+          },
+          async close() {
+            const writePromises = [];
+            try {
+              if (writeLoaderDataEnabled && !isNotFoundPage) {
+                const routeLoaders = getRouteLoaders(requestEv);
+                const loaderValues = getRouteLoaderValues(requestEv);
+                const manifestHash = opts.manifest?.manifestHash || "dev";
+                for (const loader of routeLoaders) {
+                  if (loader.__cacheControl !== "immutable") {
+                    continue;
+                  }
+                  const data = loaderValues[loader.__id];
+                  if (data === void 0) {
+                    continue;
+                  }
+                  const loaderFilePath = sys.getLoaderFilePath(url.pathname, loader.__id, manifestHash);
+                  const loaderWriter = sys.createWriteStream(loaderFilePath);
+                  loaderWriter.on("error", (e) => {
+                    console.error(e);
+                    result.error = {
+                      message: e.message,
+                      stack: e.stack
+                    };
+                  });
+                  const serialized = await deps.serialize({
+                    d: data
+                  });
+                  loaderWriter.write(serialized);
+                  writePromises.push(new Promise((resolve) => {
+                    result.filePath = routeFilePath;
+                    loaderWriter.end(resolve);
+                  }));
+                }
+              }
+              if (routeWriter) {
+                writePromises.push(new Promise((resolve) => {
+                  result.filePath = routeFilePath;
+                  routeWriter.end(resolve);
+                }).finally(closeResolved));
+              }
+              if (writePromises.length > 0) {
+                await Promise.all(writePromises);
+              }
+            } catch (e) {
+              console.error("Error during stream close", staticRoute.pathname, e);
+              routeWriter = null;
+              result.error = {
+                message: String(e),
+                stack: e.stack || ""
+              };
+            }
+          }
+        });
+        return stream;
+      }
+    };
+    const promise = requestHandlerForSsg(requestCtx, opts, deps).then((rsp) => {
+      if (rsp != null) {
+        return rsp.completion.then((r) => {
+          if (routeWriter) {
+            return closePromise.then(() => r);
+          }
+          return r;
+        });
+      }
+    }).then((e) => {
+      if (e !== void 0) {
+        if (isRedirectMessage(e)) {
+          return;
+        }
+        if (e instanceof Error) {
+          result.error = {
+            message: e.message,
+            stack: e.stack
+          };
+        } else {
+          result.error = {
+            message: String(e),
+            stack: void 0
+          };
+        }
+        console.error("Error during request handling", staticRoute.pathname, e);
+      }
+    }).catch((e) => {
+      console.error("Unhandled error during request handling", staticRoute.pathname, e);
+      result.error = {
+        message: String(e),
+        stack: e.stack || ""
+      };
+    }).finally(() => {
+      pendingPromises.delete(promise);
+      callback(result);
+    });
+    pendingPromises.add(promise);
+  } catch (e) {
+    console.error("Error during render", staticRoute.pathname, e);
+    if (e instanceof Error) {
+      result.error = {
+        message: e.message,
+        stack: e.stack
+      };
+    } else {
+      result.error = {
+        message: String(e),
+        stack: void 0
+      };
+    }
+    callback(result);
+  }
+}
+async function workerThread(sys) {
+  const opts = sys.getOptions();
+  const pendingPromises = /* @__PURE__ */ new Set();
+  const deps = {
+    ...staticWorkerThreadDeps,
+    serialize: _serialize
+  };
+  process.on("uncaughtException", (e) => {
+    console.error("Worker uncaught exception (suppressed):", e.message);
+  });
+  process.on("unhandledRejection", (e) => {
+    console.error("Worker unhandled rejection (suppressed):", e instanceof Error ? e.message : e);
+  });
+  const onMessage = async (msg) => {
+    switch (msg.type) {
+      case "render": {
+        return new Promise((resolve) => {
+          workerRender(sys, opts, msg, pendingPromises, resolve, deps).catch((e) => {
+            console.error("Error during render", msg.pathname, e);
+            resolve({
+              type: "render",
+              pathname: msg.pathname,
+              url: "",
+              ok: false,
+              error: {
+                message: e instanceof Error ? e.message : String(e),
+                stack: e instanceof Error ? e.stack : void 0
+              },
+              filePath: null,
+              contentType: null,
+              resourceType: null
+            });
+          });
+        });
+      }
+      case "close": {
+        if (pendingPromises.size) {
+          const promises = Array.from(pendingPromises);
+          pendingPromises.clear();
+          await Promise.all(promises);
+        }
+        return {
+          type: "close"
+        };
+      }
+    }
+  };
+  parentPort?.on("message", async (msg) => {
+    try {
+      parentPort?.postMessage(await onMessage(msg));
+    } catch (e) {
+      if (msg.type === "render") {
+        const error = e instanceof Error ? e : new Error(String(e));
+        parentPort?.postMessage({
+          type: "render",
+          pathname: msg.pathname,
+          url: "",
+          ok: false,
+          error: {
+            message: error.message,
+            stack: error.stack
+          },
+          filePath: null,
+          contentType: null,
+          resourceType: null
+        });
+      } else {
+        console.error("Worker message handler error", e);
+      }
+    }
+    if (msg.type === "close") {
+      parentPort?.close();
+    }
+  });
+}
+
+export { workerThread };

package/lib/index.d.ts

@@ -1,7 +1,9 @@
 /// <reference path="./modules.d.ts" />
 
-import type { AsyncSignal } from '@qwik.dev/core';
+import type { AbortMessage } from '@qwik.dev/router/middleware/request-handler';
+import type { CacheControl } 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';
@@ -24,6 +26,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';
@@ -38,51 +41,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 */
@@ -394,6 +399,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;
 };
@@ -434,6 +447,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;
 
@@ -482,8 +503,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`**.
      *
@@ -501,7 +522,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.
@@ -534,8 +555,8 @@ 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 */
@@ -548,7 +569,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 }
 
@@ -566,24 +587,28 @@ declare type LoaderConstructorQRL = {
 
 /** @public */
 declare type LoaderOptions = {
-    /** @deprecated Unused */
+    /**
+     * 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.
+     * Cache-Control for this loader's JSON responses. The browser HTTP cache is the single source of
+     * freshness for loader data: on every client navigation the loaders re-fetch, and this header
+     * decides whether the browser serves the fetch from cache, revalidates, or hits the server.
      *
-     * On the client, the loader's AsyncSignal `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.
+     * Accepts any `cacheControl()` value (`'immutable'`, `'no-cache'`, a max-age number, an options
+     * object) or a function of the request event; the function may return `null` to skip the header.
+     * A `Cache-Control` header set inside the loader function wins over this option.
+     *
+     * Defaults to `no-cache` (always revalidate; combine with `eTag` for cheap 304s).
+     *
+     * The literal value `'immutable'` also marks the loader's data as static, so SSG writes a
+     * per-loader JSON file at build time.
      */
-    readonly poll?: boolean;
+    readonly cacheControl?: CacheControl | ((ev: RequestEvent) => CacheControl | null);
     /**
      * Enable ETag-based caching for this loader's JSON responses.
      *
@@ -632,17 +657,21 @@ declare type LoaderOptions = {
      */
     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 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.
      *
-     * 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.
+     * Setting `false` is experimental and requires adding `experimental: ["blockSSR"]` to your
+     * qwikVite plugin options.
      */
-    readonly allowStale?: boolean;
+    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;
@@ -840,9 +869,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
@@ -906,7 +935,8 @@ export declare type ResolvedDocumentHead<FrontMatter extends Record<string, any>
  */
 export declare const routeAction$: ActionConstructor;
 
-/* Excluded from this release type: routeActionQrl */
+/** @public */
+export declare const routeActionQrl: ActionConstructorQRL;
 
 declare type RouteActionResolver = {
     status: number;
@@ -963,10 +993,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 */
@@ -986,7 +1019,7 @@ export declare interface RouteData {
 /**
  * Define a route loader that fetches data before the route renders.
  *
- * Route loaders run on the server during SSR and return data as an `AsyncSignal`. On the client,
+ * 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.
@@ -1001,10 +1034,9 @@ export declare interface RouteData {
  *   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.
+ * - `cacheControl`: Cache-Control for loader JSON responses; the browser HTTP cache controls
+ *   client-side freshness. `'immutable'` additionally lets SSG write the loader file.
  *
  * The `strictLoaders` Vite plugin option applies `search: []` globally for all loaders that don't
  * specify an explicit `search` option.
@@ -1028,6 +1060,8 @@ declare type RouteLoaderCtx = {
     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 */