@reckona/mreact-router 0.0.151 → 0.0.153

package/src/build.ts

@@ -90,12 +90,13 @@ import { sourceModuleCandidates } from "./source-modules.js";
 import { collectBuildInferredServerActions } from "./server-action-inference.js";
 import { viteDefineCacheKey, vitePluginsCacheKey } from "./vite-plugin-cache-key.js";
 import { workspacePackageFile } from "./workspace-packages.js";
+import { prependTailwindSourceDirectives } from "./tailwind-source.js";
 import {
   parseRouteMiddlewareControl,
   parseStaticMiddlewareConfig,
   validateRouteMiddlewareControl,
 } from "./middleware.js";
-import type { PluginOption, UserConfig } from "vite";
+import type { Plugin, PluginOption, UserConfig } from "vite";
 
 const nativeEscapeTransform = {
   batchImportName: "escapeHtmlBatch",
@@ -333,6 +334,11 @@ export interface BuiltPrerenderedRoute {
 
 type StaticParams = Record<string, string | number | boolean | readonly string[]>;
 
+/**
+ * Builds an app-router project into server, client, and optional deployment-target artifacts.
+ *
+ * Use this from custom build scripts when the CLI is too coarse-grained; the returned manifest paths describe the files written under `outDir`. The build reads route files, loaders, middleware, metadata, server actions, and client references, so callers should pass the same project root and source allow-list they expect to deploy.
+ */
 export async function buildApp(options: BuildAppOptions): Promise<BuildAppResult> {
   const timingSink = options.onBuildPhaseTiming;
   const progressSink = options.onBuildProgress;
@@ -530,6 +536,7 @@ export async function buildApp(options: BuildAppOptions): Promise<BuildAppResult
           sourceAnalysis,
           sourceMapDir: join(options.outDir, "source-maps", "client"),
           sourceMaps: project.clientSourceMaps,
+          sourceDirs: project.allowedSourceDirs,
           vitePlugins,
         })
       : timeBuildPhase(timingSink, progressSink, "clientBundles", () =>
@@ -544,6 +551,7 @@ export async function buildApp(options: BuildAppOptions): Promise<BuildAppResult
             sourceAnalysis,
             sourceMapDir: join(options.outDir, "source-maps", "client"),
             sourceMaps: project.clientSourceMaps,
+            sourceDirs: project.allowedSourceDirs,
             vitePlugins,
           }),
         ),
@@ -1759,6 +1767,12 @@ async function prerenderStaticRoutes(options: {
       artifact,
     ]),
   );
+  const serverModuleCacheVersion = buildPrerenderServerModuleCacheVersion({
+    define: options.define,
+    project: options.project,
+    sourceAnalysis: options.sourceAnalysis,
+    vitePlugins: options.vitePlugins,
+  });
 
   const prerenderedEntries = await mapWithBuildConcurrency(
     options.routes.filter((route): route is AppRoute & { kind: "page" } => route.kind === "page"),
@@ -1780,6 +1794,7 @@ async function prerenderStaticRoutes(options: {
           define: options.define,
           importPolicy,
           request: new Request(`http://mreact.local${pathname}`),
+          serverModuleCacheVersion,
           serverModules: serverModuleMap,
           vitePlugins: options.vitePlugins,
         });
@@ -1810,6 +1825,28 @@ async function prerenderStaticRoutes(options: {
   return prerendered;
 }
 
+function buildPrerenderServerModuleCacheVersion(options: {
+  define?: UserConfig["define"] | undefined;
+  project: ResolvedAppRouterProject;
+  sourceAnalysis: BuildSourceAnalysisScope;
+  vitePlugins?: readonly PluginOption[] | undefined;
+}): string {
+  const sourceHashes = Array.from(options.sourceAnalysis.byFile.entries())
+    .map(([file, analysis]) => [file, analysis.sourceHash] as const)
+    .sort(([left], [right]) => left.localeCompare(right));
+
+  return `build-prerender:${hashText(
+    JSON.stringify({
+      allowedSourceDirs: [...options.project.allowedSourceDirs].sort(),
+      projectRoot: options.project.projectRoot,
+      routesDir: options.project.routesDir,
+      sourceHashes,
+      viteDefine: viteDefineCacheKey(options.define),
+      vitePlugins: vitePluginsCacheKey(options.vitePlugins),
+    }),
+  ).slice(0, 16)}`;
+}
+
 async function prerenderPathsForRoute(
   route: AppRoute,
   analysis: BuildRouteSourceAnalysis,
@@ -2102,6 +2139,10 @@ async function buildServerModuleArtifacts(options: {
             filename: join(options.projectRoot, file),
             moduleContextCache: options.clientRouteInferenceCache,
             serverOutput,
+            ...(serverOutput === "stream" &&
+            (routeAnalysis?.clientRoute ?? clientInference?.client) === true
+              ? { serverAwaitHydration: true as const }
+              : {}),
           });
           const fatalDiagnostics = output.diagnostics.filter(
             (diagnostic) => diagnostic.code !== "MR_UNSUPPORTED_SERVER_EVENT_HANDLER",
@@ -5012,6 +5053,7 @@ async function writeClientRouteBundles(options: {
   sourceAnalysis: BuildSourceAnalysisScope;
   sourceMapDir: string;
   sourceMaps: AppRouterClientSourceMapMode;
+  sourceDirs: readonly string[];
   vitePlugins?: readonly PluginOption[] | undefined;
 }): Promise<ClientRouteBundleManifest> {
   type PreparedClientRouteEntry = {
@@ -5033,6 +5075,7 @@ async function writeClientRouteBundles(options: {
     pageRoutes,
     projectRoot: options.projectRoot,
     sourceAnalysis: options.sourceAnalysis,
+    sourceDirs: options.sourceDirs,
     vitePlugins: options.vitePlugins,
   });
   const specialCssAssets = await writeSpecialRouteCssAssetBatches({
@@ -5042,6 +5085,7 @@ async function writeClientRouteBundles(options: {
     clientDir: options.clientDir,
     projectRoot: options.projectRoot,
     sourceAnalysis: options.sourceAnalysis,
+    sourceDirs: options.sourceDirs,
     vitePlugins: options.vitePlugins,
   });
   const entries: PreparedRouteEntry[] = await Promise.all(
@@ -5271,6 +5315,7 @@ async function writeSpecialRouteCssAssetBatches(options: {
   clientDir: string;
   projectRoot: string;
   sourceAnalysis: BuildSourceAnalysisScope;
+  sourceDirs: readonly string[];
   vitePlugins?: readonly PluginOption[] | undefined;
 }): Promise<{ assets: string[]; styles: ClientStyleManifestEntry[] }> {
   const boundaryFiles = await collectSpecialBoundaryFiles(options.appDir);
@@ -5295,6 +5340,7 @@ async function writeSpecialRouteCssAssetBatches(options: {
       pageFile: file,
       projectRoot: options.projectRoot,
       routeIds: [specialBoundaryRouteId(options.appDir, file)],
+      sourceDirs: options.sourceDirs,
       vitePlugins: options.vitePlugins,
     });
 
@@ -5335,6 +5381,7 @@ async function writeRouteCssAssetBatches(options: {
   pageRoutes: readonly (AppRoute & { kind: "page" })[];
   projectRoot: string;
   sourceAnalysis: BuildSourceAnalysisScope;
+  sourceDirs: readonly string[];
   vitePlugins?: readonly PluginOption[] | undefined;
 }): Promise<{ assets: string[]; byRoute: Map<string, string[]> }> {
   const cssInputs = await mapWithBuildConcurrency(options.pageRoutes, async (route) => {
@@ -5378,6 +5425,7 @@ async function writeRouteCssAssetBatches(options: {
           pageFile: group.routeFiles[0] ?? options.appDir,
           projectRoot: options.projectRoot,
           routeIds: group.routeIds,
+          sourceDirs: options.sourceDirs,
           vitePlugins: options.vitePlugins,
         }),
       ] as const,
@@ -5410,6 +5458,7 @@ async function writeRouteCssAssetsForFiles(options: {
   pageFile: string;
   projectRoot: string;
   routeIds: readonly string[];
+  sourceDirs: readonly string[];
   vitePlugins?: readonly PluginOption[] | undefined;
 }): Promise<RouteCssAssetBatch> {
   const cssFiles = [...options.cssFiles];
@@ -5429,7 +5478,13 @@ async function writeRouteCssAssetsForFiles(options: {
     minify: true,
     platform: "browser",
     root: options.projectRoot,
-    vitePlugins: options.vitePlugins,
+    vitePlugins: [
+      productionRouteCssTailwindSourcePlugin({
+        cssFiles,
+        sourceDirs: options.sourceDirs,
+      }),
+      ...(options.vitePlugins ?? []),
+    ],
   });
   const cssAssets = (output.assets ?? []).filter((asset) => asset.fileName.endsWith(".css"));
   const nonCssAssets = (output.assets ?? []).filter((asset) => !asset.fileName.endsWith(".css"));
@@ -5463,6 +5518,31 @@ async function writeRouteCssAssetsForFiles(options: {
   return { assets: writtenAssets.sort(), css: written };
 }
 
+function productionRouteCssTailwindSourcePlugin(options: {
+  cssFiles: readonly string[];
+  sourceDirs: readonly string[];
+}): Plugin {
+  const cssFiles = new Set(options.cssFiles);
+
+  return {
+    name: "mreact-production-route-css-tailwind-source",
+    enforce: "pre",
+    transform(code, id) {
+      const [filename] = id.split(/[?#]/, 1);
+
+      if (filename === undefined || !cssFiles.has(filename)) {
+        return;
+      }
+
+      return prependTailwindSourceDirectives({
+        code,
+        cssFile: filename,
+        sourceDirs: options.sourceDirs,
+      });
+    },
+  };
+}
+
 function applyClientSourceMapReference(options: {
   code: string;
   scriptBasename: string;
@@ -5541,6 +5621,11 @@ async function writeCloudflareWorkerArtifact(options: {
   );
 }
 
+/**
+ * Packages a built app-router output directory into the minimal AWS Lambda artifact layout.
+ *
+ * The package contains `.mreact`, a Lambda handler, project package metadata, production dependencies, and `mreact-lambda-artifact.json`; it intentionally excludes source files and development tooling that are not needed at runtime.
+ */
 export async function packageAwsLambdaArtifact(
   options: PackageAwsLambdaArtifactOptions,
 ): Promise<AwsLambdaArtifactManifest> {
@@ -5648,6 +5733,11 @@ async function assertAwsLambdaRuntimeDependencies(outDir: string): Promise<void>
   );
 }
 
+/**
+ * Packages a Cloudflare-target build for Cloudflare Pages advanced mode.
+ *
+ * The package writes `_worker.js`, generated client assets, public assets, and `mreact-cloudflare-pages-artifact.json`; deploy the output directory rather than the raw `.mreact` build tree.
+ */
 export async function packageCloudflarePagesArtifact(
   options: PackageCloudflarePagesArtifactOptions,
 ): Promise<CloudflarePagesArtifactManifest> {

package/src/cache.ts

@@ -56,6 +56,11 @@ const cacheState = ((
 });
 cacheState.storage ??= new AsyncLocalStorage<RouteCacheContext>();
 
+/**
+ * Creates an in-memory route response cache for app-router rendering.
+ *
+ * The cache is process-local, evicts expired entries during reads/writes, and is suitable for development, tests, or single-process deployments that do not need shared invalidation.
+ */
 export function createMemoryRouteCache(options: MemoryRouteCacheOptions = {}): AppRouterCache {
   const maxEntries = positiveIntegerOrDefault(options.maxEntries, 10_000);
   const sweepIntervalMs = nonNegativeIntegerOrDefault(options.sweepIntervalMs, 60_000);
@@ -192,6 +197,11 @@ export function routeCachePolicyFromSource(code: string): RouteCachePolicy | und
   };
 }
 
+/**
+ * Sets the cache policy for the current app-router render.
+ *
+ * Call this during a loader or route render to override the response `Cache-Control` policy; it throws outside an active app-router request.
+ */
 export function cacheControl(options: CacheControlOptions): void {
   const activeContext = activeRouteCacheContext();
 
@@ -326,6 +336,11 @@ function requestCarriesCredentials(request: Request | undefined): boolean {
   return request.headers.has("authorization") || request.headers.has("cookie");
 }
 
+/**
+ * Invalidates cached route responses for a normalized app-router path.
+ *
+ * During a request the invalidation is scoped to that route cache context; outside a request it is queued for the next cache access.
+ */
 export function revalidatePath(path: string): void {
   const normalizedPath = normalizeRevalidationPath(path);
   const activeContext = activeRouteCacheContext();

package/src/cookies.ts

@@ -22,6 +22,11 @@ function assertAttributeValue(value: string): void {
   }
 }
 
+/**
+ * Parses a raw `Cookie` header into decoded name/value pairs.
+ *
+ * Malformed percent-encoded values are skipped so one bad cookie does not abort request handling.
+ */
 export function parseCookieHeader(
   cookieHeader: string | null | undefined,
 ): Map<string, string> {
@@ -50,6 +55,11 @@ export function parseCookieHeader(
   return values;
 }
 
+/**
+ * Serializes a cookie name, value, and attributes for a `Set-Cookie` header.
+ *
+ * Cookie names and attribute values are validated, and `SameSite=None` requires `Secure`.
+ */
 export function serializeCookie(
   name: string,
   value: string,
@@ -91,6 +101,9 @@ export function serializeCookie(
   return parts.join("; ");
 }
 
+/**
+ * Appends a serialized cookie to a response's `Set-Cookie` headers and returns the same response.
+ */
 export function setCookie(
   response: Response,
   name: string,
@@ -101,6 +114,9 @@ export function setCookie(
   return response;
 }
 
+/**
+ * Appends an expiring `Set-Cookie` header that removes a cookie in the browser.
+ */
 export function deleteCookie(
   response: Response,
   name: string,

package/src/dev-server.ts

@@ -33,6 +33,11 @@ export interface StartDevServerOptions extends AppRouterProjectOptions {
   onUpgrade?: HttpUpgradeHandler | undefined;
 }
 
+/**
+ * Starts the local app-router development server with Vite middleware and route compilation.
+ *
+ * The server trusts only the configured host settings, merges declared application packages into the development import policy, and returns a `close()` method that should be awaited by tests and scripts.
+ */
 export async function startDevServer(
   options: StartDevServerOptions,
 ): Promise<{ close(): Promise<void>; server: Server; url: string }> {

package/src/link.ts

@@ -39,6 +39,11 @@ export interface LinkProps<Href extends string = LinkHref> extends LinkOptions<H
   [attribute: string]: unknown;
 }
 
+/**
+ * Converts router link options into anchor attributes consumed by the client navigation runtime.
+ *
+ * Use this when rendering a custom anchor component that should still opt into mreact prefetch, scroll, reload, or transition behavior.
+ */
 export function linkProps(options: LinkOptions<string>): Record<string, string> {
   return {
     href: options.href,
@@ -61,6 +66,11 @@ export type ConcreteLinkHrefGuard<Href extends string> = [RegisteredAppRoutePath
     ? { readonly __mreactRoutePatternHrefError__: never }
     : unknown;
 
+/**
+ * Renders an app-router anchor with typed `href` support and navigation runtime attributes.
+ *
+ * In JSX it returns an anchor element compatible with the mreact runtime; during server streaming it can also write directly to an `HtmlSink`. Unsafe URL attribute values are dropped during rendering.
+ */
 export function Link<const Href extends LinkHref>(
   props: LinkProps<Href> & ConcreteLinkHrefGuard<Href>,
 ): ReactCompatElement;

package/src/middleware.ts

@@ -110,28 +110,78 @@ export function middlewareMatches(config: MiddlewareModule["config"], pathname:
 }
 
 export function parseRouteMiddlewareControl(code: string): RouteMiddlewareControl | undefined {
-  if (!/\bexport\s+const\s+middleware\s*=/.test(code)) {
+  const masked = maskCodeLiterals(code);
+  const declaration = /\bexport\s+const\s+middleware\s*=\s*\{/.exec(masked);
+
+  if (declaration === null) {
+    return undefined;
+  }
+
+  const objectStart = masked.indexOf("{", declaration.index);
+  const objectEnd = findMatchingBrace(masked, objectStart);
+
+  if (objectStart < 0 || objectEnd < 0) {
     return undefined;
   }
 
-  if (/\bmiddleware\s*=\s*\{[\s\S]*?\bskip\s*:\s*true\b/.test(code)) {
+  const maskedBody = masked.slice(objectStart + 1, objectEnd);
+  const body = code.slice(objectStart + 1, objectEnd);
+
+  if (/\bskip\s*:\s*true\b/.test(maskedBody)) {
     return { skip: true };
   }
 
-  const skipArray = /\bmiddleware\s*=\s*\{[\s\S]*?\bskip\s*:\s*\[([\s\S]*?)\]/.exec(code);
+  const skipArray = /\bskip\s*:\s*\[([\s\S]*?)\]/.exec(maskedBody);
 
   if (skipArray === null) {
     return undefined;
   }
 
+  const arrayStart = skipArray.index + skipArray[0].indexOf("[") + 1;
+  const arrayEnd = skipArray.index + skipArray[0].lastIndexOf("]");
+  const arrayBody = body.slice(arrayStart, arrayEnd);
   const ids = Array.from(
-    skipArray[1]?.matchAll(/["']([^"']+)["']/g) ?? [],
+    arrayBody.matchAll(/["']([^"']+)["']/g),
     (match) => match[1],
   ).filter((id) => id !== undefined);
 
   return ids.length === 0 ? undefined : { skip: ids };
 }
 
+function maskCodeLiterals(code: string): string {
+  return code.replace(
+    /\/\*[\s\S]*?\*\/|\/\/[^\n\r]*|"(?:\\[\s\S]|[^"\\])*"|'(?:\\[\s\S]|[^'\\])*'|`(?:\\[\s\S]|[^`\\])*`/g,
+    (match) => " ".repeat(match.length),
+  );
+}
+
+function findMatchingBrace(code: string, openIndex: number): number {
+  if (openIndex < 0) {
+    return -1;
+  }
+
+  let depth = 0;
+
+  for (let index = openIndex; index < code.length; index += 1) {
+    const char = code[index];
+
+    if (char === "{") {
+      depth += 1;
+      continue;
+    }
+
+    if (char === "}") {
+      depth -= 1;
+
+      if (depth === 0) {
+        return index;
+      }
+    }
+  }
+
+  return -1;
+}
+
 export function mergeRouteMiddlewareControls(
   controls: readonly (RouteMiddlewareControl | undefined)[],
 ): RouteMiddlewareControl | undefined {

package/src/navigation.ts

@@ -61,6 +61,11 @@ function throwUnsafeRewrite(location: string): never {
   throw new TypeError(`unsafe rewrite target: ${JSON.stringify(location)}`);
 }
 
+/**
+ * Throws an internal redirect for loaders, middleware, route handlers, or server actions.
+ *
+ * The target must be same-origin or relative; use `redirectExternal()` for trusted `http` or `https` destinations. The default status is `303`.
+ */
 export function redirect(location: string, options: RedirectOptions = {}): never {
   if (!isSafeInternalRedirect(location)) {
     throwUnsafeRedirect(location);
@@ -72,6 +77,11 @@ export function redirect(location: string, options: RedirectOptions = {}): never
   });
 }
 
+/**
+ * Throws an external redirect for trusted `http` or `https` destinations.
+ *
+ * This helper is intentionally separate from `redirect()` so off-site navigation is explicit. The default status is `307`.
+ */
 export function redirectExternal(
   location: string,
   options: RedirectOptions = {},
@@ -86,6 +96,11 @@ export function redirectExternal(
   });
 }
 
+/**
+ * Creates a same-origin `303 See Other` redirect response.
+ *
+ * Use this from route handlers when returning a `Response` is more convenient than throwing through the app-router control flow.
+ */
 export function redirect303(location: string, init: ResponseInit = {}): Response {
   if (!isSafeInternalRedirect(location)) {
     throwUnsafeRedirect(location);
@@ -101,6 +116,9 @@ export function redirect303(location: string, init: ResponseInit = {}): Response
   });
 }
 
+/**
+ * Creates a plain-text error response with a default `text/plain` content type.
+ */
 export function textError(message: string, status = 400, init: ResponseInit = {}): Response {
   const headers = new Headers(init.headers);
 
@@ -115,6 +133,11 @@ export function textError(message: string, status = 400, init: ResponseInit = {}
   });
 }
 
+/**
+ * Reads `request.formData()` and optionally validates it with a schema-like parser.
+ *
+ * Pass a schema object with `parse(FormData)` when a route handler or server action should receive typed form data.
+ */
 export async function parseForm(request: Request): Promise<FormData>;
 export async function parseForm<T>(request: Request, schema: ParseSchema<T>): Promise<T>;
 export async function parseForm<T>(
@@ -126,6 +149,11 @@ export async function parseForm<T>(
   return schema === undefined ? form : schema.parse(form);
 }
 
+/**
+ * Throws a route-level 404 control error.
+ *
+ * Use this from loaders, metadata, middleware, or route handlers when the matched route is valid but the requested resource is absent.
+ */
 export function notFound(): never {
   throw Object.assign(new Error("Not Found"), {
     name: notFoundErrorName,
@@ -133,14 +161,25 @@ export function notFound(): never {
   });
 }
 
+/**
+ * Alias for `notFound()` for codebases that prefer an explicit throwing helper name.
+ */
 export function throwNotFound(): never {
   return notFound();
 }
 
+/**
+ * Continues middleware processing without changing the request.
+ */
 export function next(): MiddlewareNext {
   return undefined;
 }
 
+/**
+ * Creates an internal rewrite response consumed by app-router middleware.
+ *
+ * The target must be a same-origin route path, query, hash, or relative URL; protocol-relative, external, and control-character targets are rejected.
+ */
 export function rewrite(location: string, init: ResponseInit = {}): Response {
   if (!isSafeInternalRedirect(location)) {
     throwUnsafeRewrite(location);
@@ -160,10 +199,16 @@ export function rewrite(location: string, init: ResponseInit = {}): Response {
   return response;
 }
 
+/**
+ * Creates a JSON response using the platform `Response.json()` implementation.
+ */
 export function json(value: unknown, init?: ResponseInit): Response {
   return Response.json(value, init);
 }
 
+/**
+ * Creates an HTML response and defaults the content type to `text/html; charset=utf-8`.
+ */
 export function html(value: string, init: ResponseInit = {}): Response {
   if (init.headers === undefined) {
     return new Response(value, {
@@ -184,6 +229,9 @@ export function html(value: string, init: ResponseInit = {}): Response {
   });
 }
 
+/**
+ * Returns the request headers object for route code that follows app-router helper naming.
+ */
 export function headers(request: Request): Headers {
   return request.headers;
 }
@@ -194,6 +242,11 @@ export interface RequestCookies {
   has(name: string): boolean;
 }
 
+/**
+ * Parses request cookies into a small read-only helper.
+ *
+ * Values are decoded with `decodeURIComponent`; malformed encoded values are ignored rather than throwing during request handling.
+ */
 export function cookies(request: Request): RequestCookies {
   let values: ReadonlyMap<string, string> | undefined;
   const cookieValues = () => {