@reckona/mreact-router 0.0.152 → 0.0.153

package/src/render.ts

@@ -137,6 +137,7 @@ import {
   prebuiltRouteLoaderModuleArtifact,
   prebuiltServerComponentModuleCode,
   prebuiltServerModuleOutputMatches,
+  prebuiltServerModuleOutputOptionsMatch,
   type BuiltServerModuleOutputLike,
 } from "./route-module-loader.js";
 
@@ -353,6 +354,8 @@ async function preloadBuiltPageRouteModules(options: {
       options.serverModuleCacheVersion,
       options.define,
       options.vitePlugins,
+      undefined,
+      { serverAwaitHydration: options.analysis.clientInference.client },
     );
   }
 
@@ -476,6 +479,7 @@ type StreamModuleExports = Record<string, unknown> & {
 
 const serverTransformCache = new Map<string, TransformOutput>();
 const serverTransformCacheCounters = createRouterRuntimeCacheCounters();
+let productionDynamicServerTransformWarned = false;
 const serverSourceFileCache = new Map<string, Promise<string>>();
 const serverSourceFileCacheCounters = createRouterRuntimeCacheCounters();
 const routeSourceAnalysisCache = new Map<string, Promise<RouteSourceAnalysis>>();
@@ -640,6 +644,17 @@ function finishRenderTimingPhase(
   timing.phases[phaseName] = logDurationMs(startedAt);
 }
 
+async function readSettledPromiseAtNextTask<T>(
+  promise: Promise<T>,
+): Promise<{ settled: true; value: T } | { settled: false }> {
+  return await Promise.race([
+    promise.then((value) => ({ settled: true as const, value })),
+    new Promise<{ settled: false }>((resolve) => {
+      setTimeout(() => resolve({ settled: false }), 0);
+    }),
+  ]);
+}
+
 function addRenderTimingPhaseDuration(
   timing: RenderTiming | undefined,
   startedAt: number | undefined,
@@ -652,6 +667,12 @@ function addRenderTimingPhaseDuration(
   timing.phases[phaseName] = (timing.phases[phaseName] ?? 0) + logDurationMs(startedAt);
 }
 
+function routeLoaderMayReturnControlResponse(code: string): boolean {
+  return /\b(?:redirect|redirectExternal|rewrite|notFound|throwNotFound)\s*\(/.test(code) ||
+    /\bnew\s+Response\s*\(/.test(code) ||
+    /\bResponse\.(?:redirect|json)\s*\(/.test(code);
+}
+
 async function waitForRenderPreload(
   options: Pick<RenderAppRequestOptions, "preload">,
   timing: RenderTiming | undefined,
@@ -835,6 +856,7 @@ async function renderAppRequestInternal(options: RenderAppRequestOptions): Promi
       appDir: options.appDir,
       filename: "not-found.mreact.tsx",
       pathname: url.pathname,
+      serverSourceFiles: options.serverSourceFiles,
     });
 
     const response = await renderSpecialRoute({
@@ -1208,8 +1230,9 @@ async function renderAppRequestInternal(options: RenderAppRequestOptions): Promi
       }
 
       let streamData: unknown;
-      if (loadingFile === undefined) {
-        phaseStartedAt = renderTimingPhaseStartedAt(timing);
+      let streamDataPromise = dataPromise ?? Promise.resolve(undefined);
+      phaseStartedAt = renderTimingPhaseStartedAt(timing);
+      if (loadingFile === undefined || routeLoaderMayReturnControlResponse(code)) {
         try {
           streamData = dataPromise === undefined ? undefined : await dataPromise;
         } finally {
@@ -1219,6 +1242,20 @@ async function renderAppRequestInternal(options: RenderAppRequestOptions): Promi
           emitRenderTiming(options, timing, streamData.status);
           return streamData;
         }
+        streamDataPromise = Promise.resolve(streamData);
+      } else {
+        try {
+          const settledData = await readSettledPromiseAtNextTask(streamDataPromise);
+          if (settledData.settled) {
+            if (settledData.value instanceof Response) {
+              emitRenderTiming(options, timing, settledData.value.status);
+              return settledData.value;
+            }
+            streamDataPromise = Promise.resolve(settledData.value);
+          }
+        } finally {
+          finishRenderTimingPhase(timing, phaseStartedAt, "loaderWaitMs");
+        }
       }
 
       await waitForRenderPreload(options, timing);
@@ -1249,7 +1286,7 @@ async function renderAppRequestInternal(options: RenderAppRequestOptions): Promi
           appDir: options.appDir,
           assetBaseUrl: options.assetBaseUrl,
           clientRoute,
-          data: dataPromise ?? Promise.resolve(undefined),
+          data: streamDataPromise,
           define: options.define,
           loadingFile,
           pageFile: matched.route.file,
@@ -1737,16 +1774,18 @@ async function nearestBoundaryFileForPath(options: {
   appDir: string;
   filename: string;
   pathname: string;
+  serverSourceFiles?: ReadonlyMap<string, string> | undefined;
 }): Promise<string> {
   const parts = options.pathname
     .replace(/^\/+|\/+$/g, "")
     .split("/")
-    .filter((part) => part.length > 0);
+    .filter((part) => part.length > 0 && part !== "." && part !== "..");
 
-  return nearestBoundaryFileFromParts({
+  return await nearestBoundaryFileFromParts({
     appDir: options.appDir,
     filename: options.filename,
     parts,
+    serverSourceFiles: options.serverSourceFiles,
   });
 }
 
@@ -1754,11 +1793,19 @@ async function nearestBoundaryFileFromParts(options: {
   appDir: string;
   filename: string;
   parts: string[];
+  serverSourceFiles?: ReadonlyMap<string, string> | undefined;
 }): Promise<string> {
   for (let count = options.parts.length; count >= 0; count -= 1) {
     for (const filename of boundaryFilenameCandidates(options.filename)) {
       const candidate = join(options.appDir, ...options.parts.slice(0, count), filename);
 
+      if (options.serverSourceFiles !== undefined) {
+        if (options.serverSourceFiles.has(candidate)) {
+          return candidate;
+        }
+        continue;
+      }
+
       try {
         await access(candidate);
         return candidate;
@@ -1835,10 +1882,16 @@ async function renderSpecialRoute(options: {
   textFallback: string;
   vitePlugins?: readonly PluginOption[] | undefined;
 }): Promise<Response> {
-  try {
-    await access(options.routeFile);
-  } catch {
-    return new Response(options.textFallback, { status: options.status });
+  if (options.serverSourceFiles !== undefined) {
+    if (!options.serverSourceFiles.has(options.routeFile)) {
+      return new Response(options.textFallback, { status: options.status });
+    }
+  } else {
+    try {
+      await access(options.routeFile);
+    } catch {
+      return new Response(options.textFallback, { status: options.status });
+    }
   }
 
   const props = {
@@ -1982,7 +2035,10 @@ async function dispatchServerRoute(options: {
   const handler = module[options.request.method] ?? module.ALL ?? module.default;
 
   if (typeof handler !== "function") {
-    return new Response("Method Not Allowed", { status: 405 });
+    return new Response("Method Not Allowed", {
+      headers: { allow: allowedServerRouteMethods(module).join(", ") },
+      status: 405,
+    });
   }
 
   let response: unknown;
@@ -2007,6 +2063,12 @@ async function dispatchServerRoute(options: {
     : new Response("Invalid route response", { status: 500 });
 }
 
+function allowedServerRouteMethods(module: Record<string, unknown>): string[] {
+  return ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"].filter(
+    (method) => typeof module[method] === "function",
+  );
+}
+
 async function dispatchConventionAssetRoute(options: {
   file: string;
   request: Request;
@@ -2544,7 +2606,10 @@ function transformServerModule(options: {
   if (
     artifact !== undefined &&
     artifact.sourceHash === sourceHash &&
-    options.serverAwaitHydration !== true
+    prebuiltServerModuleOutputOptionsMatch(
+      artifact,
+      options.serverAwaitHydration === true ? { serverAwaitHydration: true } : {},
+    )
   ) {
     return {
       code: artifact.code,
@@ -2578,6 +2643,8 @@ function transformServerModule(options: {
     return cached;
   }
 
+  warnProductionDynamicServerTransform();
+
   const output = transform({
     code: options.code,
     ...(options.clientBoundaryImports === undefined
@@ -2605,6 +2672,19 @@ function transformServerModule(options: {
   return output;
 }
 
+export const __transformServerModuleForTesting = transformServerModule;
+
+function warnProductionDynamicServerTransform(): void {
+  if (process.env.NODE_ENV !== "production" || productionDynamicServerTransformWarned) {
+    return;
+  }
+
+  productionDynamicServerTransformWarned = true;
+  console.warn(
+    "mreact router: dynamic server transform path ran in production. Production deployments should provide prebuilt serverModules; otherwise request-time transforms use development compiler settings.",
+  );
+}
+
 async function analyzeRouteSource(options: {
   appDir: string;
   artifact?: BuiltRouteSourceAnalysisSummary | undefined;
@@ -3442,12 +3522,14 @@ async function loadServerStreamModule(
   define?: UserConfig["define"] | undefined,
   vitePlugins?: readonly PluginOption[] | undefined,
   importPolicy?: AppRouterImportPolicy | undefined,
+  outputOptions: { serverAwaitHydration?: boolean } = {},
 ): Promise<StreamModuleExports> {
   const artifactCode = serverModules?.get(sourcefile)?.stream;
   const codeHash = memoizedHashText(code);
-  const prebuiltCode = prebuiltServerComponentModuleCode(artifactCode, code, codeHash);
+  const prebuiltCode = prebuiltServerComponentModuleCode(artifactCode, code, codeHash, outputOptions);
   if (
     artifactCode !== undefined &&
+    prebuiltServerModuleOutputOptionsMatch(artifactCode, outputOptions) &&
     prebuiltServerModuleOutputMatches(artifactCode, code, codeHash) &&
     artifactCode.moduleFile !== undefined
   ) {
@@ -4539,10 +4621,7 @@ async function loadComposedRouteMetadata(options: {
   serverSourceFiles?: ReadonlyMap<string, string> | undefined;
   vitePlugins?: readonly PluginOption[] | undefined;
 }): Promise<RouteMetadata | undefined> {
-  const cacheKey =
-    options.serverModuleCacheVersion === undefined
-      ? undefined
-      : `${options.appDir}\0${options.filename}\0${options.serverModuleCacheVersion}\0${memoizedHashText(options.code)}\0${viteDefineCacheKey(options.define)}\0${vitePluginsCacheKey(options.vitePlugins)}`;
+  const cacheKey = composedRouteMetadataCacheKey(options);
   if (cacheKey !== undefined) {
     const cached = readRouterRuntimeCacheEntry(
       composedRouteMetadataCache,
@@ -4575,6 +4654,22 @@ async function loadComposedRouteMetadata(options: {
   }
 }
 
+function composedRouteMetadataCacheKey(options: {
+  appDir: string;
+  code: string;
+  define?: UserConfig["define"] | undefined;
+  filename: string;
+  importPolicy?: AppRouterImportPolicy | undefined;
+  serverModuleCacheVersion?: string | undefined;
+  vitePlugins?: readonly PluginOption[] | undefined;
+}): string | undefined {
+  return options.serverModuleCacheVersion === undefined
+    ? undefined
+    : `${options.appDir}\0${options.filename}\0${options.serverModuleCacheVersion}\0${memoizedHashText(options.code)}\0${importPolicyCacheKey(options.importPolicy)}\0${viteDefineCacheKey(options.define)}\0${vitePluginsCacheKey(options.vitePlugins)}`;
+}
+
+export const __composedRouteMetadataCacheKeyForTesting = composedRouteMetadataCacheKey;
+
 async function loadComposedRouteMetadataUncached(options: {
   appDir: string;
   code: string;
@@ -4775,26 +4870,59 @@ interface InlineCspTag {
 
 function inlineCspTags(html: string): InlineCspTag[] {
   const tags: InlineCspTag[] = [];
-  const pattern = /<(script|style)\b([^>]*)>([\s\S]*?)<\/\1>/gi;
-  let match: RegExpExecArray | null;
+  const lowerHtml = html.toLowerCase();
+  let position = 0;
+
+  while (position < html.length) {
+    const scriptIndex = lowerHtml.indexOf("<script", position);
+    const styleIndex = lowerHtml.indexOf("<style", position);
+    const openerIndex =
+      scriptIndex === -1
+        ? styleIndex
+        : styleIndex === -1
+          ? scriptIndex
+          : Math.min(scriptIndex, styleIndex);
+
+    if (openerIndex === -1) {
+      break;
+    }
 
-  while ((match = pattern.exec(html)) !== null) {
-    const name = match[1]?.toLowerCase();
+    const name = lowerHtml.startsWith("<script", openerIndex) ? "script" : "style";
+    const tagEnd = html.indexOf(">", openerIndex + 1);
+    if (tagEnd === -1) {
+      break;
+    }
 
-    if (name !== "script" && name !== "style") {
+    const closeToken = `</${name}>`;
+    const closeIndex = lowerHtml.indexOf(closeToken, tagEnd + 1);
+    const nextScriptIndex = lowerHtml.indexOf("<script", tagEnd + 1);
+    const nextStyleIndex = lowerHtml.indexOf("<style", tagEnd + 1);
+    const nextOpenerIndex =
+      nextScriptIndex === -1
+        ? nextStyleIndex
+        : nextStyleIndex === -1
+          ? nextScriptIndex
+          : Math.min(nextScriptIndex, nextStyleIndex);
+
+    if (closeIndex === -1 || (nextOpenerIndex !== -1 && nextOpenerIndex < closeIndex)) {
+      position = tagEnd + 1;
       continue;
     }
 
     tags.push({
-      attributes: parseTagAttributes(match[2] ?? ""),
-      content: match[3] ?? "",
+      attributes: parseTagAttributes(html.slice(openerIndex + name.length + 1, tagEnd)),
+      content: html.slice(tagEnd + 1, closeIndex),
       name,
     });
+
+    position = closeIndex + closeToken.length;
   }
 
   return tags;
 }
 
+export const __inlineCspTagsForTesting = inlineCspTags;
+
 function parseTagAttributes(source: string): ReadonlyMap<string, string> {
   const attributes = new Map<string, string>();
   const pattern = /([^\s=/>]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
@@ -4842,7 +4970,7 @@ function injectQueryState(html: string, state: DehydratedQueryClient): string {
   )}</script>`;
 
   return /<\/body>/i.test(html)
-    ? html.replace(/<\/body>/i, () => `${script}</body>`)
+    ? replaceFinalBodyCloseTag(html, script)
     : `${html}${script}`;
 }
 
@@ -4856,10 +4984,21 @@ function injectAuthSessionClaims(html: string, claims: unknown): string {
   )}</script>`;
 
   return /<\/body>/i.test(html)
-    ? html.replace(/<\/body>/i, () => `${script}</body>`)
+    ? replaceFinalBodyCloseTag(html, script)
     : `${html}${script}`;
 }
 
+function replaceFinalBodyCloseTag(html: string, insertion: string): string {
+  const matches = [...html.matchAll(/<\/body>/gi)];
+  const last = matches.at(-1);
+
+  if (last?.index === undefined) {
+    return `${html}${insertion}`;
+  }
+
+  return `${html.slice(0, last.index)}${insertion}${html.slice(last.index)}`;
+}
+
 function authIncludesClaims(code: string): boolean {
   return /\bexport\s+const\s+auth\s*=\s*["']include-claims["']\s*;?/.test(code);
 }

package/src/route-module-loader.ts

@@ -58,11 +58,16 @@ export function prebuiltServerComponentModuleCode(
   artifact: BuiltServerModuleArtifact["string"] | BuiltServerModuleArtifact["stream"] | undefined,
   code: string,
   codeHash: string,
+  options: { serverAwaitHydration?: boolean } = {},
 ): string | undefined {
   if (artifact === undefined) {
     return undefined;
   }
 
+  if (!prebuiltServerModuleOutputOptionsMatch(artifact, options)) {
+    return undefined;
+  }
+
   if (!prebuiltServerModuleOutputMatches(artifact, code, codeHash)) {
     return undefined;
   }
@@ -70,6 +75,16 @@ export function prebuiltServerComponentModuleCode(
   return artifact.bundleCode;
 }
 
+export function prebuiltServerModuleOutputOptionsMatch(
+  artifact: NonNullable<BuiltServerModuleArtifact["string"] | BuiltServerModuleArtifact["stream"]>,
+  options: { serverAwaitHydration?: boolean },
+): boolean {
+  return (
+    (artifact.metadata?.serverAwaitHydration === true) ===
+    (options.serverAwaitHydration === true)
+  );
+}
+
 export function prebuiltServerModuleOutputMatches(
   artifact: BuiltServerModuleOutputLike,
   code: string,

package/src/serve.ts

@@ -577,6 +577,11 @@ async function materializeResponseAsBuffer(response: Response): Promise<Response
   });
 }
 
+/**
+ * Starts a Node HTTP server for an already built app-router output directory.
+ *
+ * Use this for production-like local serving or custom Node deployments. It loads `.mreact/server` artifacts, applies the generated import policy when configured, enforces host trust options, and returns a `close()` method for orderly shutdown.
+ */
 export async function startServer(
   options: StartServerOptions,
 ): Promise<{ close(): Promise<void>; server: Server; url: string }> {

package/src/session.ts

@@ -72,6 +72,11 @@ function createSessionId(): string {
   return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 
+/**
+ * Creates a process-local session store backed by an in-memory LRU-like map.
+ *
+ * Use it for development, tests, or single-process deployments; production multi-instance deployments should provide a shared `SessionStore`.
+ */
 export function createMemorySessionStore<TData>(
   options: MemorySessionStoreOptions = {},
 ): SessionStore<TData> {
@@ -152,6 +157,9 @@ function nonNegativeIntegerOrDefault(value: number | undefined, fallback: number
   return value === undefined || !Number.isInteger(value) || value < 0 ? fallback : value;
 }
 
+/**
+ * Reads the current session cookie, loads the matching session record, and deletes expired records.
+ */
 export async function getSession<TData>(
   request: Request,
   store: SessionStore<TData>,
@@ -177,6 +185,9 @@ export async function getSession<TData>(
   return record;
 }
 
+/**
+ * Creates a new session record, stores it, and appends the session cookie to the response.
+ */
 export async function createSession<TData>(
   response: Response,
   store: SessionStore<TData>,
@@ -200,6 +211,9 @@ export async function createSession<TData>(
   return record;
 }
 
+/**
+ * Deletes the current session record when present and appends an expiring session cookie to the response.
+ */
 export async function destroySession<TData>(
   request: Request,
   response: Response,
@@ -219,6 +233,11 @@ export async function destroySession<TData>(
   });
 }
 
+/**
+ * Replaces the current session id while preserving the stored session data.
+ *
+ * Use this after authentication or privilege changes to reduce session fixation risk.
+ */
 export async function rotateSession<TData>(
   request: Request,
   response: Response,

package/src/typed-routes.ts

@@ -54,6 +54,11 @@ export type AppRouteLinkSegment<Segment extends string> = Segment extends `:${st
   ? string
   : Segment;
 
+/**
+ * Builds an internal app-route URL from a route pattern and typed params/search options.
+ *
+ * Dynamic `:param` and `:...catchAll` segments are URL-encoded, search values are serialized with `URLSearchParams`, and protocol-relative or external paths are rejected.
+ */
 export function href<const Path extends `/${string}`>(
   path: Path,
   ...args: HasRouteParams<Path> extends true

package/src/types.ts

@@ -25,6 +25,11 @@ export interface LoaderContext<TParams extends RouteParams = RouteParams> {
   request: Request;
 }
 
+/**
+ * Context passed to a route `generateMetadata` export.
+ *
+ * Metadata is evaluated on the server after loader data is available, so it can derive head tags, robots data, sitemap entries, and security header directives from the same request and route params as the page.
+ */
 export interface GenerateMetadataContext<
   TData = unknown,
   TParams extends RouteParams = RouteParams,
@@ -49,6 +54,11 @@ export type PageComponent<TLoader extends RouteLoader> = (
   props: PageProps<InferLoaderData<TLoader>, InferLoaderParams<TLoader>>,
 ) => ReactCompatNode;
 
+/**
+ * Preserves the relationship between a page component and its loader when authoring route files.
+ *
+ * Wrap a default page export with `definePage<typeof loader>(...)` to infer `data` and `params` props from the route loader without changing runtime behavior.
+ */
 export function definePage<TLoader extends RouteLoader>(
   component: PageComponent<TLoader>,
 ): PageComponent<TLoader> {
@@ -73,6 +83,11 @@ export interface MetadataImage {
   width?: MetadataScalar;
 }
 
+/**
+ * Declarative metadata returned by route metadata exports.
+ *
+ * Values are rendered into the document head and response headers by the app router; use `generateMetadata` when the values depend on loader data, params, or the current request.
+ */
 export interface RouteMetadata {
   alternates?: {
     canonical?: MetadataScalar;