@reckona/mreact-router 0.0.203 → 0.0.205

package/src/adapters/cloudflare.ts

@@ -33,14 +33,17 @@ import { middlewareMatches, type MiddlewareModule } from "../middleware.js";
 import { normalizeRoutePath } from "../route-path.js";
 import type { AppRoute } from "../routes.js";
 import { contentSecurityPolicy } from "../csp.js";
-import { isNotFoundError, rewriteLocation } from "../navigation.js";
+import { isNotFoundError, isRedirectError, rewriteLocation } from "../navigation.js";
 import { validateRouteMetadata } from "../metadata.js";
 import { routeSecurityHeaders } from "../security-headers.js";
 import type { AppRouterPrerenderStore } from "../serve.js";
 import { emitRouterDevtoolsEvent } from "./devtools.js";
 import { escapeHtmlAttribute, escapeHtmlText } from "@reckona/mreact-shared/html-escape";
-import { isCurrentPrerenderedRoute, replayedPrerenderedRouteHeaders } from "../prerender-entry.js";
-import { hasNavigationRouteMarker } from "../navigation-marker.js";
+import {
+  isCurrentPrerenderedRoute,
+  replayedPrerenderedRouteHeaders,
+  validatedPrerenderedNavigationHtml,
+} from "../prerender-entry.js";
 
 /** Re-exports build manifest contracts used by Cloudflare handlers. */
 export type {
@@ -68,6 +71,8 @@ export type {
   AppRouterRequestStartLogEvent,
   AppRouterRequestTimingLogEvent,
   AppRouterRuntime,
+  AppRouterUpgradeErrorLogEvent,
+  AppRouterUpgradeRejectedLogEvent,
 } from "../logger.js";
 /** Re-exports response hook contracts used by Cloudflare handlers. */
 export type { AppRouterResponseHook, AppRouterResponseHookContext } from "../render.js";
@@ -214,6 +219,7 @@ export type CloudflareRouteModuleComponent<Data = unknown, Env = unknown> = (
  * Defines the exports accepted from a Cloudflare page route module.
  */
 export interface CloudflareRouteModule<Data = unknown, Env = unknown> {
+  [exportName: string]: unknown;
   App?: CloudflareRouteModuleComponent<Data, Env> | undefined;
   CloudflareRouteComponent?: CloudflareRouteModuleComponent<Data, Env> | undefined;
   default?: CloudflareRouteModuleComponent<Data, Env> | undefined;
@@ -573,12 +579,24 @@ export function createCloudflareRouteModuleRenderer<Env = unknown>(
         return error;
       }
 
+      if (isRedirectError(error)) {
+        return new Response(null, {
+          headers: { location: error.location },
+          status: error.status,
+        });
+      }
+
       if (isNotFoundError(error)) {
         return cloudflareNotFoundResponse(request);
       }
 
       throw error;
     }
+
+    if (data instanceof Response) {
+      return data;
+    }
+
     const props = {
       ...context,
       data,
@@ -590,6 +608,13 @@ export function createCloudflareRouteModuleRenderer<Env = unknown>(
     try {
       rendered = await runWithCloudflareQueryClient(queryClient, () => component(props));
     } catch (error) {
+      if (isRedirectError(error)) {
+        return new Response(null, {
+          headers: { location: error.location },
+          status: error.status,
+        });
+      }
+
       if (isNotFoundError(error)) {
         return cloudflareNotFoundResponse(request);
       }
@@ -1406,20 +1431,11 @@ function prerenderedResponse(
   }
 
   const prerendered = prerenderedRoutes?.[path];
-  const candidateNavigationHtml = prerendered?.navigationHtml;
-
   if (!isCurrentPrerenderedRoute(prerendered)) {
-    if (
-      isNavigation &&
-      typeof candidateNavigationHtml === "string" &&
-      !hasNavigationRouteMarker(candidateNavigationHtml)
-    ) {
-      return cloudflareDocumentReloadNavigationResponse();
-    }
     return undefined;
   }
 
-  const html = isNavigation ? prerendered.navigationHtml : prerendered.html;
+  const html = isNavigation ? validatedPrerenderedNavigationHtml(prerendered) : prerendered.html;
   if (html === undefined) {
     return cloudflareDocumentReloadNavigationResponse();
   }

package/src/adapters/edge.ts

@@ -20,6 +20,8 @@ export type {
   AppRouterRequestStartLogEvent,
   AppRouterRequestTimingLogEvent,
   AppRouterRuntime,
+  AppRouterUpgradeErrorLogEvent,
+  AppRouterUpgradeRejectedLogEvent,
 } from "../logger.js";
 
 /**

package/src/adapters/node.ts

@@ -1,4 +1,5 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
+import type { DehydrateOptions } from "@reckona/mreact-query";
 import type { AppRouterCache } from "../cache.js";
 import { nodeRequestToWebRequest, sendResponse } from "../http.js";
 import type { AppRouterServerActionOptions } from "../actions.js";
@@ -19,10 +20,7 @@ import { resolveNodeRequestProtocol } from "../node-server.js";
 /** Re-exports cache contracts used by Node handlers. */
 export type { AppRouterCache, AppRouterCacheEntry } from "../cache.js";
 /** Re-exports server action contracts used by Node handlers. */
-export type {
-  AppRouterAllowedServerAction,
-  AppRouterServerActionOptions,
-} from "../actions.js";
+export type { AppRouterAllowedServerAction, AppRouterServerActionOptions } from "../actions.js";
 /** Re-exports import policy contracts used by Node handlers. */
 export type { AppRouterImportPolicy } from "../import-policy.js";
 /** Re-exports logger contracts used by Node handlers. */
@@ -37,6 +35,8 @@ export type {
   AppRouterRequestStartLogEvent,
   AppRouterRequestTimingLogEvent,
   AppRouterRuntime,
+  AppRouterUpgradeErrorLogEvent,
+  AppRouterUpgradeRejectedLogEvent,
 } from "../logger.js";
 /** Re-exports response hook contracts used by Node handlers. */
 export type { AppRouterResponseHook, AppRouterResponseHookContext } from "../render.js";
@@ -63,17 +63,14 @@ import {
 } from "../serve.js";
 
 /** Re-exports request and rendering contracts used by Node handlers. */
-export type {
-  AppRouterPrerenderStore,
-  RequestHostPolicy,
-  ResponseSinkStrategy,
-} from "../serve.js";
+export type { AppRouterPrerenderStore, RequestHostPolicy, ResponseSinkStrategy } from "../serve.js";
 
 /**
  * Configures a Node request handler for built app-router output.
  */
 export interface NodeRequestHandlerOptions {
   allowedHosts?: readonly string[] | undefined;
+  dehydrateOptions?: DehydrateOptions | undefined;
   errorHandler?:
     | ((error: unknown) => {
         body: string;
@@ -139,13 +136,14 @@ export function createNodeRequestHandler(options: NodeRequestHandlerOptions): No
         forwardedProto: incoming.headers["x-forwarded-proto"],
         trustForwardedProto: options.trustForwardedProto,
       });
-      const request = nodeRequestToWebRequest(incoming, `${protocol}://${host}`);
+      const request = nodeRequestToWebRequest(incoming, `${protocol}://${host}`, outgoing);
       const logFields = requestLogFields(request, "node");
       emitRouterLog(options.logger, "info", {
         ...logFields,
         type: "router:request:start",
       });
       const response = await renderBuiltAppRequest({
+        dehydrateOptions: options.dehydrateOptions,
         outDir: options.outDir,
         importPolicy: options.importPolicy,
         instrumentation: options.instrumentation,

package/src/adapters/static.ts

@@ -1,7 +1,13 @@
 import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, join, resolve, sep } from "node:path";
 import type { BuiltPrerenderedRoute, BuiltServerManifest } from "../build.js";
-import { isCurrentPrerenderedRoute } from "../prerender-entry.js";
+import {
+  isCurrentPrerenderedRoute,
+  validatedPrerenderedNavigationHtml,
+} from "../prerender-entry.js";
+
+const staticNavigationBase = "/_mreact/navigation";
+const staticNavigationMetadata = `<meta name="mreact-static-navigation" content="${staticNavigationBase}">`;
 
 /**
  * Configures static export from a built app-router output directory.
@@ -104,8 +110,31 @@ async function writePrerenderedRoute(
   }
 
   const file = routeToHtmlFile(exportDir, route);
+  const navigationHtml = validatedPrerenderedNavigationHtml(entry);
+  if (navigationHtml === undefined) {
+    throw new Error(`Cannot export route ${route} without a valid navigation variant.`);
+  }
+  const navigationFile = routeToHtmlFile(join(exportDir, staticNavigationBase), route);
   await mkdir(dirname(file), { recursive: true });
-  await writeFile(file, entry.html);
+  await mkdir(dirname(navigationFile), { recursive: true });
+  await writeFile(file, withStaticNavigationMetadata(entry.html));
+  await writeFile(navigationFile, navigationHtml);
+}
+
+function withStaticNavigationMetadata(html: string): string {
+  const head = /<head(?:\s[^>]*)?>/i.exec(html);
+  if (head?.index !== undefined) {
+    const insertion = head.index + head[0].length;
+    return `${html.slice(0, insertion)}${staticNavigationMetadata}${html.slice(insertion)}`;
+  }
+
+  const doctype = /^\s*<!doctype\s+html\s*>/i.exec(html);
+  if (doctype !== null) {
+    const insertion = doctype[0].length;
+    return `${html.slice(0, insertion)}${staticNavigationMetadata}${html.slice(insertion)}`;
+  }
+
+  return `${staticNavigationMetadata}${html}`;
 }
 
 function routeToHtmlFile(exportDir: string, route: string): string {

package/src/build.ts

@@ -16,6 +16,7 @@ import { builtinModules } from "node:module";
 import { availableParallelism } from "node:os";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import type { DehydrateOptions } from "@reckona/mreact-query";
 import {
   collectStaticImportReferences,
   collectTopLevelValueExportNames,
@@ -57,6 +58,7 @@ import {
   resolveCompatVendorEntryFiles,
   sourceReferencesCompatVendorSpecifier,
 } from "./module-runner.js";
+import { dehydrateOptionsFromModule } from "./dehydrate-policy.js";
 import { compileRouteMatcherArtifact, scanAppRoutes } from "./routes.js";
 import type { AppRoute, CompiledRouteMatcherArtifact } from "./routes.js";
 import { appFileConventionForRootFilename } from "./file-conventions.js";
@@ -249,10 +251,11 @@ export interface BuildAppResult {
 
 interface IncrementalBuildCacheManifest {
   fingerprint: string;
-  version: 1;
+  version: 2;
 }
 
 interface IncrementalBuildServerManifestOutputs {
+  dehydratePolicyModule?: string;
   serverModuleFiles?: Record<string, string>;
   serverModuleRenderFiles?: Record<string, string>;
   serverModuleRequestFiles?: Record<string, string>;
@@ -326,6 +329,7 @@ export interface PackageCloudflarePagesArtifactOptions {
 export interface BuiltServerManifest {
   allowedSourceDirs?: readonly string[];
   assetBaseUrl?: string;
+  dehydratePolicyModule?: string;
   version: 1;
   files: Record<string, string>;
   prerenderedRoutes?: Record<string, BuiltPrerenderedRoute>;
@@ -456,6 +460,13 @@ async function buildAppWithResolvedProject(
   options: BuildAppOptions,
   project: ResolvedAppRouterProject,
 ): Promise<BuildAppResult> {
+  if (
+    (options as BuildAppOptions & { dehydrateOptions?: unknown }).dehydrateOptions !== undefined
+  ) {
+    throw new Error(
+      "buildApp dehydration policies must use dehydratePolicyModule so the same executable policy is available to prerendering and built runtimes.",
+    );
+  }
   const timingSink = options.onBuildPhaseTiming;
   const progressSink = options.onBuildProgress;
   const shouldTrackBuildPhases = timingSink !== undefined || progressSink !== undefined;
@@ -572,6 +583,24 @@ async function buildAppWithResolvedProject(
     });
   }
 
+  const builtDehydratePolicy =
+    project.dehydratePolicyModule === undefined
+      ? undefined
+      : await buildDehydratePolicyModule({
+          define: viteDefine,
+          file: project.dehydratePolicyModule,
+          projectRoot: project.projectRoot,
+          vitePlugins,
+        });
+  const dehydratePolicyArtifact =
+    builtDehydratePolicy === undefined
+      ? undefined
+      : `dehydrate-policy.${hashText(builtDehydratePolicy.code).slice(0, 16)}.mjs`;
+  if (builtDehydratePolicy !== undefined && dehydratePolicyArtifact !== undefined) {
+    await writeFile(join(serverDir, dehydratePolicyArtifact), builtDehydratePolicy.code);
+  }
+  const dehydrateOptions = builtDehydratePolicy?.dehydrateOptions;
+
   const publicAssets =
     shouldTrackBuildPhases === false
       ? await buildPublicAssetManifest(project, clientDir)
@@ -729,6 +758,7 @@ async function buildAppWithResolvedProject(
           assetBaseUrl: project.assetBaseUrl,
           clientRoutes: clientManifestRoutes,
           define: viteDefine,
+          dehydrateOptions,
           project,
           routes,
           serverModules,
@@ -741,6 +771,7 @@ async function buildAppWithResolvedProject(
             assetBaseUrl: project.assetBaseUrl,
             clientRoutes: clientManifestRoutes,
             define: viteDefine,
+            dehydrateOptions,
             project,
             routes,
             serverModules,
@@ -790,6 +821,9 @@ async function buildAppWithResolvedProject(
       relative(project.projectRoot, directory),
     ),
     ...(project.assetBaseUrl === undefined ? {} : { assetBaseUrl: project.assetBaseUrl }),
+    ...(dehydratePolicyArtifact === undefined
+      ? {}
+      : { dehydratePolicyModule: dehydratePolicyArtifact }),
     version: 1,
     routes: serverRoutes,
     routeMatcher: compileRouteMatcherArtifact(serverRoutes),
@@ -903,7 +937,7 @@ async function buildAppWithResolvedProject(
 }
 
 const incrementalBuildCacheFilename = "build-cache.json";
-const incrementalBuildCacheVersion = 1;
+const incrementalBuildCacheVersion = 2;
 
 async function createIncrementalBuildCacheFingerprint(options: {
   buildTargets: readonly AppRouterBuildTarget[];
@@ -949,6 +983,12 @@ async function createIncrementalBuildCacheFingerprint(options: {
     assetBaseUrl: options.project.assetBaseUrl ?? null,
     clientConsolePureFunctions: options.project.clientConsolePureFunctions ?? [],
     clientSourceMaps: options.project.clientSourceMaps,
+    dehydratePolicyModule:
+      options.project.dehydratePolicyModule === undefined
+        ? null
+        : normalizeBuildInputPath(
+            relative(options.project.projectRoot, options.project.dehydratePolicyModule),
+          ),
     define,
     nodeEnv: process.env.NODE_ENV ?? null,
     publicAssetBaseUrl: options.project.publicAssetBaseUrl ?? null,
@@ -1015,6 +1055,9 @@ async function hasRequiredIncrementalBuildOutputs(
   }
 
   for (const file of [
+    ...(serverManifest.dehydratePolicyModule === undefined
+      ? []
+      : [serverManifest.dehydratePolicyModule]),
     ...Object.values(serverManifest.serverModuleFiles ?? {}),
     ...Object.values(serverManifest.serverModuleRenderFiles ?? {}),
     ...Object.values(serverManifest.serverModuleRequestFiles ?? {}),
@@ -1466,7 +1509,7 @@ async function buildRouteUsesRequestInput(options: {
       files: options.files,
       projectRoot: options.projectRoot,
       source: entry.source,
-    })
+    }),
   );
 }
 
@@ -2560,6 +2603,38 @@ function isReservedPublicAssetPath(pathname: string): boolean {
   return pathname === "/_mreact" || pathname.startsWith("/_mreact/");
 }
 
+async function buildDehydratePolicyModule(options: {
+  define?: UserConfig["define"] | undefined;
+  file: string;
+  projectRoot: string;
+  vitePlugins?: readonly PluginOption[] | undefined;
+}): Promise<{ code: string; dehydrateOptions: DehydrateOptions }> {
+  const source = await readFile(options.file, "utf8");
+  const code = await bundleAppRouterSourceModule({
+    code: source,
+    define: options.define,
+    label: `dehydrate-policy:${options.file}`,
+    plugins: [fileImportMetaUrlPlugin()],
+    resolveDir: dirname(options.file),
+    root: options.projectRoot,
+    sourcefile: options.file,
+    vitePlugins: options.vitePlugins,
+  });
+  const policyModule = await importAppRouterSourceModule<unknown>({
+    code,
+    label: `dehydrate-policy-runtime:${options.file}`,
+    sourcefile: options.file,
+  });
+
+  return {
+    code,
+    dehydrateOptions: dehydrateOptionsFromModule(
+      policyModule,
+      `mreactRouter dehydratePolicyModule ${options.file}`,
+    ),
+  };
+}
+
 function isNodeError(error: unknown): error is NodeJS.ErrnoException {
   return error instanceof Error && "code" in error;
 }
@@ -2568,6 +2643,7 @@ async function prerenderStaticRoutes(options: {
   appDir: string;
   assetBaseUrl?: string | undefined;
   clientRoutes: readonly ClientRouteManifestEntry[];
+  dehydrateOptions?: DehydrateOptions | undefined;
   define?: UserConfig["define"] | undefined;
   project: ResolvedAppRouterProject;
   routes: readonly AppRoute[];
@@ -2633,14 +2709,11 @@ async function prerenderStaticRoutes(options: {
           clientScripts,
           clientStyles,
           define: options.define,
+          dehydrateOptions: options.dehydrateOptions,
           importPolicy,
           navigationScripts,
-          request: new Request(
-            `http://mreact.local${pathname}`,
-            analysis.clientRoute
-              ? undefined
-              : { headers: { "x-mreact-prerender-variant-capture": "1" } },
-          ),
+          request: new Request(`http://mreact.local${pathname}`),
+          prerenderVariantCapture: !analysis.clientRoute,
           renderSignals,
           serverModuleCacheVersion,
           serverModules: serverModuleMap,
@@ -5006,9 +5079,43 @@ function validateOptionalHeadMetadata(value, path) {
         }
       }
     }
+    validateMetaRefreshHeadDescriptor(descriptor, descriptorPath);
   });
 }
 
+function validateMetaRefreshHeadDescriptor(descriptor, path) {
+  if (descriptor.tag !== "meta" || descriptor.attrs === undefined) {
+    return;
+  }
+  const attrs = Object.entries(descriptor.attrs);
+  const hasRefresh = attrs.some(([name, value]) => {
+    const canonicalName = name.toLowerCase();
+    return (canonicalName === "http-equiv" || canonicalName === "httpequiv")
+      && typeof value === "string"
+      && value.toLowerCase() === "refresh";
+  });
+  if (!hasRefresh) {
+    return;
+  }
+  for (const [name, value] of attrs) {
+    if (name.toLowerCase() !== "content" || typeof value !== "string") {
+      continue;
+    }
+    const match = /^[^;]*;\\s*url\\s*=\\s*([\\s\\S]+)$/iu.exec(value);
+    if (match === null || match[1] === undefined) {
+      continue;
+    }
+    let target = match[1].trim();
+    const quote = target[0];
+    if ((quote === String.fromCharCode(34) || quote === "'") && target[target.length - 1] === quote) {
+      target = target.slice(1, -1).trim();
+    }
+    if (isUnsafeUrlValueForName("href", target)) {
+      throw new Error(\`Invalid metadata field \${path}.attrs.\${name}: unsafe refresh URL value.\`);
+    }
+  }
+}
+
 function validateHeadAttribute(name, value, path) {
   if (!isSafeHeadAttributeName(name)) {
     throw new Error(\`Invalid metadata field \${path}: expected safe HTML attribute name.\`);
@@ -5070,7 +5177,7 @@ function isUnsafeUrlValueForName(name, value) {
   }
   const scheme = match[1].toLowerCase();
   if (scheme === "data" && (name === "src" || name === "poster")) {
-    return !/^data:image\\/(?!svg\\+xml(?:[;,]|$))/i.test(canonical);
+    return !/^data:image\\/(?!svg\\+xml\\s*(?:[;,]|$))/i.test(canonical);
   }
   return scheme === "javascript" || scheme === "data" || scheme === "vbscript" || scheme === "livescript" || scheme === "mhtml" || scheme === "file";
 }

package/src/built-runtime.ts

@@ -1,6 +1,8 @@
 import { createHash } from "node:crypto";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, normalize } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { DehydrateOptions } from "@reckona/mreact-query";
 import type {
   BuiltPrerenderedRoute,
   BuiltServerManifest,
@@ -10,6 +12,7 @@ import { builtClientAssetPaths } from "./built-assets.js";
 import type { BuiltServerModuleArtifactRuntime } from "./built-server-module-artifacts.js";
 import type { ClientRouteManifestEntry } from "./client-route-inference.js";
 import type { AppRouterImportPolicy } from "./import-policy.js";
+import { dehydrateOptionsFromModule } from "./dehydrate-policy.js";
 import { createRouteMatcher, type AppRoute, type RouteMatcher } from "./routes.js";
 
 export interface BuiltRuntime extends BuiltServerModuleArtifactRuntime {
@@ -19,6 +22,7 @@ export interface BuiltRuntime extends BuiltServerModuleArtifactRuntime {
   clientScripts: ReadonlyMap<string, string>;
   clientStylesByFile: ReadonlyMap<string, readonly string[]>;
   clientStyles: ReadonlyMap<string, readonly string[]>;
+  dehydrateOptions?: DehydrateOptions | undefined;
   generatedImportPolicy?: AppRouterImportPolicy | undefined;
   hasMiddleware: boolean;
   navigationScripts: ReadonlyMap<string, string>;
@@ -160,6 +164,13 @@ export async function materializeBuiltRuntime(options: {
     options.importPolicyText,
     options.importPolicyPath,
   );
+  const dehydrateOptions =
+    serverManifest.dehydratePolicyModule === undefined
+      ? undefined
+      : await loadBuiltDehydratePolicy(
+          join(options.outDir, "server", safeManifestFilePath(serverManifest.dehydratePolicyModule)),
+          serverManifest.dehydratePolicyModule,
+        );
 
   return {
     appDir: routesDir,
@@ -171,6 +182,7 @@ export async function materializeBuiltRuntime(options: {
     clientScripts,
     clientStylesByFile,
     clientStyles,
+    ...(dehydrateOptions === undefined ? {} : { dehydrateOptions }),
     ...(generatedImportPolicy === undefined ? {} : { generatedImportPolicy }),
     hasMiddleware,
     navigationScripts,
@@ -198,6 +210,22 @@ export async function materializeBuiltRuntime(options: {
   };
 }
 
+async function loadBuiltDehydratePolicy(
+  policyPath: string,
+  manifestPath: string,
+): Promise<DehydrateOptions> {
+  let policyModule: unknown;
+  try {
+    policyModule = await import(pathToFileURL(policyPath).href);
+  } catch (error) {
+    throw builtArtifactReadError("built app dehydration policy", policyPath, error);
+  }
+  return dehydrateOptionsFromModule(
+    policyModule,
+    `Built dehydration policy ${manifestPath}`,
+  );
+}
+
 export async function readBuiltImportPolicyText(outDir: string): Promise<string | undefined> {
   const policyPath = join(outDir, "server", "import-policy.json");