@reckona/mreact-router 0.0.152 → 0.0.154

package/src/build.ts

@@ -44,9 +44,12 @@ import {
   type BuildClientRouteOutputOptions,
 } from "./navigation-runtime.js";
 import {
+  COMPAT_VENDOR_PLACEHOLDER_PREFIX,
   bundleAppRouterSourceModule,
   fileImportMetaUrlPlugin,
   importAppRouterSourceModule,
+  resolveCompatVendorEntryFiles,
+  sourceReferencesCompatVendorSpecifier,
 } from "./module-runner.js";
 import { scanAppRoutes } from "./routes.js";
 import type { AppRoute } from "./routes.js";
@@ -334,6 +337,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;
@@ -952,6 +960,85 @@ async function buildPublicAssetManifest(
   return [...new Set([...publicAssetPaths, ...appConventionPublicAssets])].sort();
 }
 
+const COMPAT_VENDOR_PLACEHOLDER_IMPORT_PATTERN = /(["'])mreact-compat-vendor:([\w-]+)\1/gu;
+
+function rewriteCompatVendorPlaceholderImports(code: string): string {
+  if (!code.includes(COMPAT_VENDOR_PLACEHOLDER_PREFIX)) {
+    return code;
+  }
+
+  // Module files live in server-modules/code/, vendor chunks in
+  // server-modules/chunks/, so the relative path is stable.
+  return code.replace(
+    COMPAT_VENDOR_PLACEHOLDER_IMPORT_PATTERN,
+    (_match, quote: string, entry: string) => `${quote}../chunks/compat.${entry}.mjs${quote}`,
+  );
+}
+
+function collectCompatVendorEntryUsage(
+  artifacts: ReadonlyArray<readonly [string, BuiltServerModuleArtifact]>,
+): ReadonlySet<string> {
+  const usedEntries = new Set<string>();
+
+  for (const [, artifact] of artifacts) {
+    for (const output of [artifact.string, artifact.stream]) {
+      const bundleCode = output?.bundleCode;
+
+      if (bundleCode === undefined || !bundleCode.includes(COMPAT_VENDOR_PLACEHOLDER_PREFIX)) {
+        continue;
+      }
+
+      for (const match of bundleCode.matchAll(COMPAT_VENDOR_PLACEHOLDER_IMPORT_PATTERN)) {
+        const entry = match[2];
+
+        if (entry !== undefined) {
+          usedEntries.add(entry);
+        }
+      }
+    }
+  }
+
+  return usedEntries;
+}
+
+// Bundles the react-compat server runtime once per build into shared chunks
+// under server-modules/chunks/ so per-route server modules can import it via
+// relative paths instead of inlining their own copy.
+async function writeCompatVendorChunks(
+  serverDir: string,
+  usedEntries: ReadonlySet<string>,
+): Promise<void> {
+  const entryFiles = resolveCompatVendorEntryFiles(serverDir);
+  const entries = await Promise.all(
+    [...entryFiles]
+      .filter(([name]) => usedEntries.has(name))
+      .map(async ([name, filename]) => ({
+        code: await readFile(filename, "utf8"),
+        filename,
+        name,
+      })),
+  );
+  const firstEntry = entries[0];
+
+  if (firstEntry === undefined) {
+    return;
+  }
+
+  const output = await bundleRouterModules({
+    chunkFileNames: "compat-shared.[hash].mjs",
+    entries,
+    entryFileNames: "compat.[name].mjs",
+    platform: "node",
+    root: dirname(firstEntry.filename),
+  });
+  const chunksDir = join(serverDir, "server-modules", "chunks");
+
+  await mkdir(chunksDir, { recursive: true });
+  await Promise.all(
+    output.chunks.map((chunk) => writeFile(join(chunksDir, chunk.fileName), chunk.code)),
+  );
+}
+
 async function writeServerModuleArtifactFiles(
   serverDir: string,
   serverModules: Record<string, BuiltServerModuleArtifact>,
@@ -977,6 +1064,12 @@ async function writeServerModuleArtifactFiles(
     mkdir(join(modulesDir, "render"), { recursive: true }),
   ]);
 
+  const usedCompatVendorEntries = collectCompatVendorEntryUsage(artifactEntries);
+
+  if (usedCompatVendorEntries.size > 0) {
+    await writeCompatVendorChunks(serverDir, usedCompatVendorEntries);
+  }
+
   const writtenArtifacts = await mapWithBuildConcurrency<
     [string, BuiltServerModuleArtifact],
     WrittenServerModuleArtifact
@@ -1106,7 +1199,9 @@ async function externalizeServerModuleOutputCode(
   const moduleCode =
     sourceCode === undefined
       ? undefined
-      : rewritePortableRuntimePackageImports(sourceCode, portableRuntimePackages);
+      : rewriteCompatVendorPlaceholderImports(
+          rewritePortableRuntimePackageImports(sourceCode, portableRuntimePackages),
+        );
 
   if (moduleCode === undefined || moduleCode.length === 0) {
     return output;
@@ -1914,6 +2009,11 @@ async function buildServerModuleArtifacts(options: {
   const routeByFile = new Map(
     options.routes.map((route) => [relative(options.projectRoot, route.file), route]),
   );
+  // One shared compat vendor chunk set replaces per-route inlining whenever
+  // any app source references the react/compat specifier family.
+  const externalizeCompatVendor =
+    options.prebundleServerComponents &&
+    Object.values(options.files).some(sourceReferencesCompatVendorSpecifier);
   const loaderArtifactFiles = new Set<string>();
   const metadataArtifactFiles = new Set<string>();
   const requestArtifactFiles = new Set<string>();
@@ -2134,6 +2234,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",
@@ -2177,6 +2281,7 @@ async function buildServerModuleArtifacts(options: {
                     bundleCode: await buildServerComponentBundleArtifactCode({
                       clientRouteInferenceCache: options.clientRouteInferenceCache,
                       code: output.code,
+                      externalizeCompatVendor,
                       filename: absoluteFile,
                       define: options.define,
                       root: options.projectRoot,
@@ -2216,6 +2321,7 @@ async function buildServerComponentBundleArtifactCode(options: {
   clientRouteInferenceCache: ClientRouteInferenceCache;
   code: string;
   define?: UserConfig["define"] | undefined;
+  externalizeCompatVendor?: boolean | undefined;
   filename: string;
   root?: string | undefined;
   serverOutput: ServerOutputMode;
@@ -2224,6 +2330,7 @@ async function buildServerComponentBundleArtifactCode(options: {
   return await bundleAppRouterSourceModule({
     code: options.code,
     define: options.define,
+    externalizeCompatVendor: options.externalizeCompatVendor,
     label: `server-component:${options.filename}`,
     resolveDir: dirname(options.filename),
     root: options.root,
@@ -5612,6 +5719,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> {
@@ -5719,6 +5831,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/module-runner.ts

@@ -274,10 +274,100 @@ export async function importAppRouterBuiltFileModule<T>(options: {
   return (await import(pathToFileURL(options.file).href)) as T;
 }
 
+
+export const COMPAT_VENDOR_PLACEHOLDER_PREFIX = "mreact-compat-vendor:";
+
+// Specifier-to-dist-entry table for the react-compat server family. The
+// per-route externalization plugin and the shared vendor chunk build must
+// agree exactly with the workspace alias table above, so both derive from
+// this map.
+const compatVendorSpecifierEntries = new Map<string, string>([
+  ["react", "index"],
+  ["react-dom", "index"],
+  ["react-dom/client", "index"],
+  ["react-dom/server", "index"],
+  ["react/jsx-dev-runtime", "jsx-dev-runtime"],
+  ["react/jsx-runtime", "jsx-runtime"],
+  ["@reckona/mreact-compat", "index"],
+  ["@reckona/mreact-compat/event-priority", "event-priority"],
+  ["@reckona/mreact-compat/flight", "flight"],
+  ["@reckona/mreact-compat/hooks", "hooks-entry"],
+  ["@reckona/mreact-compat/internal", "internal"],
+  ["@reckona/mreact-compat/jsx-dev-runtime", "jsx-dev-runtime"],
+  ["@reckona/mreact-compat/jsx-runtime", "jsx-runtime"],
+  ["@reckona/mreact-compat/scheduler", "scheduler"],
+]);
+
+const compatVendorEntrySpecifiers = new Map<string, string>([
+  ["index", "@reckona/mreact-compat"],
+  ["jsx-runtime", "@reckona/mreact-compat/jsx-runtime"],
+  ["jsx-dev-runtime", "@reckona/mreact-compat/jsx-dev-runtime"],
+  ["hooks-entry", "@reckona/mreact-compat/hooks"],
+  ["scheduler", "@reckona/mreact-compat/scheduler"],
+  ["event-priority", "@reckona/mreact-compat/event-priority"],
+  ["flight", "@reckona/mreact-compat/flight"],
+  ["internal", "@reckona/mreact-compat/internal"],
+]);
+
+export function compatVendorEntryNames(): readonly string[] {
+  return [...compatVendorEntrySpecifiers.keys()];
+}
+
+// Cheap build-time prefilter. A false positive only costs one unused vendor
+// chunk build; a false negative keeps the per-route inlining fallback.
+const compatVendorSpecifierPattern =
+  /["'](?:react|react-dom|react\/jsx(?:-dev)?-runtime|react-dom\/(?:client|server)|@reckona\/mreact-compat(?:\/[\w-]+)?)["']/u;
+
+export function sourceReferencesCompatVendorSpecifier(source: string): boolean {
+  return compatVendorSpecifierPattern.test(source);
+}
+
+export function resolveCompatVendorEntryFiles(resolveDir?: string): Map<string, string> {
+  const files = new Map<string, string>();
+
+  for (const [entry, specifier] of compatVendorEntrySpecifiers) {
+    files.set(
+      entry,
+      resolveWorkspacePackageFile({
+        currentFileUrl: import.meta.url,
+        entry,
+        monorepoDir: "react-compat",
+        packageName: "@reckona/mreact-compat",
+        resolveDir,
+        specifier,
+      }),
+    );
+  }
+
+  return files;
+}
+
+// Marks every compat-family import as external with a deterministic
+// placeholder specifier; writeServerModuleArtifactFiles later rewrites the
+// placeholders to relative paths into the emitted shared vendor chunks.
+export function compatVendorExternalizePlugin(): RouterCompatPlugin {
+  return {
+    name: "mreact-compat-vendor-externalize",
+    setup(buildApi) {
+      buildApi.onResolve(
+        { filter: /^(?:react|react-dom|react\/.+|react-dom\/.+|@reckona\/mreact-compat(?:\/.+)?)$/u },
+        (args) => {
+          const entry = compatVendorSpecifierEntries.get(args.path);
+
+          return entry === undefined
+            ? undefined
+            : { external: true, path: `${COMPAT_VENDOR_PLACEHOLDER_PREFIX}${entry}` };
+        },
+      );
+    },
+  };
+}
+
 export async function bundleAppRouterSourceModule(options: {
   code: string;
   define?: UserConfig["define"] | undefined;
   externalizeAppSourceModuleDirs?: readonly string[] | undefined;
+  externalizeCompatVendor?: boolean | undefined;
   label: string;
   plugins?: readonly RouterCompatPlugin[] | undefined;
   resolveDir?: string | undefined;
@@ -295,6 +385,7 @@ export async function bundleAppRouterSourceModule(options: {
     root: options.root,
     vitePlugins: options.vitePlugins,
     plugins: [
+      ...(options.externalizeCompatVendor === true ? [compatVendorExternalizePlugin()] : []),
       workspacePackageResolutionPlugin(),
       ...(options.serverSourceTransform === 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 = () => {