vinext 1.0.0 → 1.1.0

package/dist/config/dotenv.js

@@ -1,7 +1,19 @@
 import path from "../deps/.pnpm/pathslash@0.1.0/deps/pathslash/dist/index.js";
 import fs from "node:fs";
-import { parseEnv } from "node:util";
 //#region src/config/dotenv.ts
+const DOTENV_LINE = /^\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?$/gm;
+function parseDotenv(content) {
+	const parsed = {};
+	const lines = content.replace(/\r\n?/g, "\n");
+	for (const match of lines.matchAll(DOTENV_LINE)) {
+		let value = (match[2] ?? "").trim();
+		const quote = value[0];
+		value = value.replace(/^(['"`])([\s\S]*)\1$/gm, "$2");
+		if (quote === "\"") value = value.replace(/\\n/g, "\n").replace(/\\r/g, "\r");
+		parsed[match[1]] = value;
+	}
+	return parsed;
+}
 /**
 * Next.js-compatible dotenv lookup order (highest priority first).
 */
@@ -42,8 +54,7 @@ function loadDotenv({ root, mode, processEnv = process.env }) {
 	for (const relativeFile of getDotenvFiles(mode)) {
 		const filePath = path.join(root, relativeFile);
 		if (!fs.existsSync(filePath)) continue;
-		const fileContent = fs.readFileSync(filePath, "utf-8");
-		const expanded = expandEnv(parseEnv(fileContent), processEnv);
+		const expanded = expandEnv(parseDotenv(fs.readFileSync(filePath, "utf-8")), processEnv);
 		for (const [key, value] of Object.entries(expanded)) {
 			if (processEnv[key] !== void 0) continue;
 			processEnv[key] = value;

package/dist/config/next-config.d.ts

@@ -111,6 +111,11 @@ export type NextConfig = {
   crossOrigin?: "anonymous" | "use-credentials";
   /** Whether to add trailing slashes */
   trailingSlash?: boolean;
+  /**
+   * Compress responses from the Node production server. Defaults to true.
+   * @see https://nextjs.org/docs/app/api-reference/config/next-config-js/compress
+   */
+  compress?: boolean;
   /** Keep the original request URL visible to middleware/proxy. */
   skipProxyUrlNormalize?: boolean;
   /** @deprecated Use `skipProxyUrlNormalize` instead. */
@@ -312,6 +317,8 @@ export type ResolvedNextConfig = {
    */
   assetPrefix: string;
   trailingSlash: boolean;
+  /** Whether the Node production server compresses responses (`compress`, default true). */
+  compress: boolean;
   skipProxyUrlNormalize: boolean;
   typescript: {
     tsconfigPath?: string;

package/dist/config/next-config.js

@@ -1,5 +1,5 @@
 import path, { toSlash } from "../deps/.pnpm/pathslash@0.1.0/deps/pathslash/dist/index.js";
-import { normalizePageExtensions } from "../routing/file-matcher.js";
+import { DEFAULT_PAGE_EXTENSIONS, normalizePageExtensions } from "../routing/file-matcher.js";
 import { loadCommonJsModule, shouldRetryAsCommonJs } from "../utils/commonjs-loader.js";
 import { isUnknownRecord } from "../utils/record.js";
 import { PHASE_DEVELOPMENT_SERVER, PHASE_PRODUCTION_BUILD } from "../shims/constants.js";
@@ -184,11 +184,24 @@ function warnConfigLoadFailure(filename, err) {
 	if (isNextIntlPlugin) console.warn("[vinext] Hint: createNextIntlPlugin() is not needed with vinext. Remove the next-intl/plugin wrapper from your next.config — vinext auto-detects next-intl and registers the i18n config alias automatically.");
 }
 /**
+* The `defaultConfig` handed to a function-form next.config. Next.js passes
+* its full `defaultConfig` (packages/next/src/server/config-shared.ts); vinext
+* passes the subset configs are known to read, with values matching Next.js,
+* so `[...defaultConfig.pageExtensions, "page.js"]` works. Fresh per call so a
+* config that mutates it cannot leak into later loads.
+*/
+function createFunctionConfigDefaults() {
+	return {
+		pageExtensions: [...DEFAULT_PAGE_EXTENSIONS],
+		compress: true
+	};
+}
+/**
 * Resolve a Next-style config value, calling it if it's a function-form config
 * (Next.js supports `module.exports = (phase, opts) => config`).
 */
 async function resolveConfigValue(config, phase = DEFAULT_PHASE) {
-	if (typeof config === "function") return await config(phase, { defaultConfig: {} });
+	if (typeof config === "function") return await config(phase, { defaultConfig: createFunctionConfigDefaults() });
 	return config;
 }
 /**
@@ -436,7 +449,7 @@ async function loadNextConfigWithPackageIdentity(root, phase) {
 					},
 					load(id) {
 						if (id !== resolvedVirtualConfigId) return;
-						return `import * as configModule from ${configPathLiteral};\nconst cjsModule = configModule[${JSON.stringify(VINEXT_CJS_EXPORTS_KEY)}];\nconst cjsInitial = configModule[${JSON.stringify(VINEXT_CJS_INITIAL_KEY)}];\nconst cjsExports = cjsModule && cjsModule.exports;\nconst cjsValue = cjsExports != null && (cjsExports !== cjsInitial || (typeof cjsExports === "object" && Object.keys(cjsExports).length > 0)) ? cjsExports : undefined;\nconst value = cjsValue ?? configModule.default ?? configModule;\nexport default typeof value === "function" ? await value(${phaseLiteral}, { defaultConfig: {} }) : value;\n`;
+						return `import * as configModule from ${configPathLiteral};\nconst cjsModule = configModule[${JSON.stringify(VINEXT_CJS_EXPORTS_KEY)}];\nconst cjsInitial = configModule[${JSON.stringify(VINEXT_CJS_INITIAL_KEY)}];\nconst cjsExports = cjsModule && cjsModule.exports;\nconst cjsValue = cjsExports != null && (cjsExports !== cjsInitial || (typeof cjsExports === "object" && Object.keys(cjsExports).length > 0)) ? cjsExports : undefined;\nconst value = cjsValue ?? configModule.default ?? configModule;\nexport default typeof value === "function" ? await value(${phaseLiteral}, { defaultConfig: ${JSON.stringify(createFunctionConfigDefaults())} }) : value;\n`;
 					}
 				},
 				...isTypeScriptConfig ? [cjsGlobalsInjectorPlugin(configPath)] : [],
@@ -748,6 +761,7 @@ async function resolveNextConfig(config, root = toSlash(process.cwd()), options
 			basePath: "",
 			assetPrefix: "",
 			trailingSlash: false,
+			compress: true,
 			skipProxyUrlNormalize: false,
 			typescript: {},
 			output: "",
@@ -933,6 +947,7 @@ async function resolveNextConfig(config, root = toSlash(process.cwd()), options
 		basePath: config.basePath ?? "",
 		assetPrefix: normalizeAssetPrefix(config.assetPrefix),
 		trailingSlash: config.trailingSlash ?? false,
+		compress: config.compress !== false,
 		skipProxyUrlNormalize: config.skipProxyUrlNormalize ?? config.skipMiddlewareUrlNormalize ?? false,
 		typescript: typeof config.typescript?.tsconfigPath === "string" ? { tsconfigPath: config.typescript.tsconfigPath } : {},
 		output: output === "export" || output === "standalone" ? output : "",

package/dist/entries/app-rsc-entry.d.ts

@@ -60,6 +60,8 @@ type AppRouterConfig = {
   globalNotFound?: boolean;
   /** Enables Next.js Cache Components semantics for App Router document HTML. */
   cacheComponents?: boolean;
+  /** Reads an MDX source's ESM exports, as the prerender listing does. */
+  readMdxEsm?: ((source: string) => string) | null;
   /** Resolved `experimental.prefetchInlining` thresholds. */
   prefetchInlining?: PrefetchInliningConfig;
   /** Whether the RSC build discovered any server references. Defaults to true. */

package/dist/entries/app-rsc-entry.js

@@ -2,11 +2,12 @@ import { toSlash } from "../deps/.pnpm/pathslash@0.1.0/deps/pathslash/dist/index
 import { appRouteHasMainTreeLoadingBoundary } from "../routing/app-router.js";
 import { resolveEntryPath } from "./runtime-entry-module.js";
 import { isProxyFile } from "../server/middleware.js";
-import { extractExportConstString } from "../build/report.js";
+import { extractExportConstString, getAppRouteRenderEntryPath } from "../build/report.js";
 import { routePatternParts } from "../routing/route-pattern.js";
 import { safeJsonStringify } from "../server/html.js";
 import { DEFAULT_DEVICE_SIZES, DEFAULT_IMAGE_SIZES } from "../server/image-optimization.js";
 import { buildAppRscManifestCode } from "./app-rsc-manifest.js";
+import { classifyAppPageRouteStaticEligibility } from "../build/app-page-static-eligibility.js";
 import { generateDevOriginCheckCode } from "../server/dev-origin-check.js";
 import { ACTION_OWNER_MANIFEST_ID } from "../plugins/action-owner-manifest.js";
 import fs from "node:fs";
@@ -38,7 +39,6 @@ const appPageExecutionPath = resolveEntryPath("../server/app-page-execution.js",
 const appFallbackRendererPath = resolveEntryPath("../server/app-fallback-renderer.js", import.meta.url);
 const appElementsPath = resolveEntryPath("../server/app-elements.js", import.meta.url);
 const appPageRouteWiringPath = resolveEntryPath("../server/app-page-route-wiring.js", import.meta.url);
-const appPageProbePath = resolveEntryPath("../server/app-page-probe.js", import.meta.url);
 const appPageDispatchPath = resolveEntryPath("../server/app-page-dispatch.js", import.meta.url);
 const appPagePprRuntimePath = resolveEntryPath("../server/app-page-ppr-runtime.js", import.meta.url);
 const fileBasedMetadataPath = resolveEntryPath("../server/file-based-metadata.js", import.meta.url);
@@ -46,7 +46,6 @@ const appPageRequestPath = resolveEntryPath("../server/app-page-request.js", imp
 const appSegmentConfigPath = resolveEntryPath("../server/app-segment-config.js", import.meta.url);
 const appRscRouteMatchingPath = resolveEntryPath("../server/app-rsc-route-matching.js", import.meta.url);
 const appRscResponseStagePath = resolveEntryPath("../server/app-rsc-response-stage.js", import.meta.url);
-const appRscCombinedHandlerPath = resolveEntryPath("../server/app-rsc-combined-handler.js", import.meta.url);
 const rscStreamHintsPath = resolveEntryPath("../server/rsc-stream-hints.js", import.meta.url);
 const isrCachePath = resolveEntryPath("../server/isr-cache.js", import.meta.url);
 const thenableParamsShimPath = resolveEntryPath("../shims/thenable-params.js", import.meta.url);
@@ -64,10 +63,10 @@ const appHookWarningSuppressionPath = resolveEntryPath("../server/app-hook-warni
 const serverGlobalsPath = resolveEntryPath("../server/server-globals.js", import.meta.url);
 const appPagesBridgePath = resolveEntryPath("../server/app-pages-bridge.js", import.meta.url);
 const routePatternPath = resolveEntryPath("../routing/route-pattern.js", import.meta.url);
-function buildAppRequestRouteMetadata(routes) {
+function createSegmentSourceReader() {
 	const sourceCache = /* @__PURE__ */ new Map();
-	const forcesDynamic = (filePath) => {
-		if (!filePath) return false;
+	return (filePath) => {
+		if (!filePath) return null;
 		let source = sourceCache.get(filePath);
 		if (source === void 0) {
 			try {
@@ -77,19 +76,57 @@ function buildAppRequestRouteMetadata(routes) {
 			}
 			sourceCache.set(filePath, source);
 		}
+		return source;
+	};
+}
+/** Segment config files of the tree a direct request to a page route renders. */
+function appPageSegmentConfigPaths(route) {
+	return [
+		...route.layouts,
+		route.pagePath,
+		...route.parallelSlots.flatMap((slot) => [
+			slot.layoutPath,
+			...slot.configLayoutPaths ?? [],
+			slot.pagePath ?? slot.defaultPath
+		])
+	];
+}
+/**
+* Patterns of the static App pages that answer a request whose raw pathname
+* reaches a dynamic sibling but whose segment-decoded pathname names them, so
+* `/%61` and `/caf%C3%A9` render `/a` and `/café` rather than `/[slug]`.
+*
+* Next.js serves those requests from the response cached under the decoded
+* pathname, which exists only for a page it prerendered. The prerender listing
+* classifies those: a page whose effective segment config renders it
+* dynamically (`dynamic = "force-dynamic"`, `revalidate = 0` or the edge
+* runtime on any segment) and a Route Handler have no such entry, so the
+* dynamic sibling renders. So does a page whose sources can't be read here;
+* its sibling's render stays out of the shared caches. A cacheComponents
+* build lists every page route, as the prerender listing does.
+*/
+function buildAppDecodedPathnamePatterns(routes, config) {
+	const isPrerenderedPage = (route) => {
+		if (config?.cacheComponents) return true;
+		try {
+			return classifyAppPageRouteStaticEligibility(route, config?.readMdxEsm ?? null) === "eligible";
+		} catch {
+			return false;
+		}
+	};
+	return routes.filter((route) => !route.isDynamic && !route.routePath && getAppRouteRenderEntryPath(route) !== null && isPrerenderedPage(route)).map((route) => route.pattern);
+}
+function buildAppRequestRouteMetadata(routes) {
+	const readSource = createSegmentSourceReader();
+	const forcesDynamic = (filePath) => {
+		const source = readSource(filePath);
 		return source !== null && extractExportConstString(source, "dynamic") === "force-dynamic";
 	};
 	return routes.map((route) => ({
 		canUseCanonicalLoadingShell: appRouteHasMainTreeLoadingBoundary(route),
 		forceDynamic: route.routePath ? forcesDynamic(route.routePath) : [
-			...route.layouts,
-			route.pagePath,
-			...route.parallelSlots.flatMap((slot) => [
-				slot.layoutPath,
-				...slot.configLayoutPaths ?? [],
-				slot.pagePath ?? slot.defaultPath,
-				...slot.interceptingRoutes.flatMap((intercept) => [...intercept.layoutPaths, intercept.pagePath])
-			]),
+			...appPageSegmentConfigPaths(route),
+			...route.parallelSlots.flatMap((slot) => slot.interceptingRoutes.flatMap((intercept) => [...intercept.layoutPaths, intercept.pagePath])),
 			...route.siblingIntercepts.flatMap((intercept) => [...intercept.layoutPaths, intercept.pagePath])
 		].some(forcesDynamic),
 		ids: route.ids ?? null,
@@ -202,11 +239,12 @@ export const __imageConfig = ${JSON.stringify({
 		contentSecurityPolicy: config?.imageConfig?.contentSecurityPolicy
 	})};
 const __routes = ${JSON.stringify(requestRoutes)};
-const __routeMatcher = __createAppRscRouteMatcher(__routes);
+const __routeMatcher = __createAppRscRouteMatcher(__routes, ${JSON.stringify(buildAppDecodedPathnamePatterns(routes, config))});
 const __metadataRouteMatchers = ${JSON.stringify(metadataRouteMatchers)};
 
 function matchRoute(pathname) { return __routeMatcher.matchRoute(pathname); }
 function matchRequestRoute(pathname) { return __routeMatcher.matchRequestRoute(pathname); }
+function matchRawRequestRoute(pathname) { return __routeMatcher.matchRawRequestRoute(pathname); }
 function hasInterceptionId(interceptionId) { return __routeMatcher.hasInterceptionId(interceptionId); }
 function __isMetadataPath(pathname) {
   const parts = pathname.split("/").filter(Boolean);
@@ -240,6 +278,7 @@ function __isMetadataPath(pathname) {
 ${generateDevOriginCheckCode(config?.allowedDevOrigins)}
 
 const __requestHandler = createAppRscRequestHandler({
+  assetPrefix: __assetPrefix,
   basePath: __basePath,
   buildId: process.env.__VINEXT_BUILD_ID ?? null,
   cacheabilityRequestProjection: __cacheabilityRequestProjection,
@@ -262,6 +301,7 @@ const __requestHandler = createAppRscRequestHandler({
   hasInterceptionId,
   matchRoute,
   matchRequestRoute,
+  matchRawRequestRoute,
   matchInterceptRoute(pathname, sourcePathname, interceptionId) {
     const intercept = __routeMatcher.findIntercept(pathname, sourcePathname, interceptionId);
     if (!intercept) return null;
@@ -475,7 +515,7 @@ ${instrumentationPath ? `import * as _instrumentation from ${JSON.stringify(toSl
 import { ensureInstrumentationRegistered as __ensureInstrumentationRegistered } from ${JSON.stringify(instrumentationRuntimePath)};` : ""}
 ${applicationInitializationCode}
 ${middlewarePath ? instrumentationPath ? "let middlewareModule;" : `import * as middlewareModule from ${JSON.stringify(toSlash(middlewarePath))};` : ""}
-${responseStageOnly ? `import { renderAppWorkerResponseStage as __renderAppWorkerResponseStage } from ${JSON.stringify(appRscResponseStagePath)};` : `import { createAppRscHandler } from ${JSON.stringify(appRscCombinedHandlerPath)};`}
+${responseStageOnly ? `import { renderAppWorkerResponseStage as __renderAppWorkerResponseStage } from ${JSON.stringify(appRscResponseStagePath)};` : `import { createAppRscHandler } from "vinext/server/app-rsc-combined-handler";`}
 import { registerConfiguredCacheAdapters as __registerConfiguredCacheAdapters } from "virtual:vinext-cache-adapters";
 import __pagesClientAssets from "virtual:vinext-pages-client-assets";
 ${actionOwners === void 0 ? `import __vinextActionOwners from ${JSON.stringify(ACTION_OWNER_MANIFEST_ID)};` : ""}
@@ -513,7 +553,6 @@ import {
   resolveAppPageChildSegments as __resolveAppPageChildSegments,
 } from ${JSON.stringify(appPageRouteWiringPath)};
 import { buildPageElements as __buildPageElements } from ${JSON.stringify(appPageElementBuilderPath)};
-import { buildAppPageProbes as __buildAppPageProbes } from ${JSON.stringify(appPageProbePath)};
 import {
   dispatchAppPage as __dispatchAppPage,
 } from ${JSON.stringify(appPageDispatchPath)};
@@ -566,7 +605,7 @@ import { suppressHookWarningAls } from ${JSON.stringify(appHookWarningSuppressio
 import { clearAppRequestContext as __clearRequestContext, setAppNavigationContext as setNavigationContext } from ${JSON.stringify(appRequestContextPath)};
 __configureMemoryCacheHandler({ cacheMaxMemorySize: ${JSON.stringify(cacheMaxMemorySize)} });
 import { createAppPrerenderStaticParamsResolver as __createAppPrerenderStaticParamsResolver } from ${JSON.stringify(appPrerenderStaticParamsPath)};
-import { ensureAppRouteModulesLoaded as __ensureRouteLoaded, loadAppInterceptPage as __loadAppInterceptPage } from ${JSON.stringify(appRouteModuleLoaderPath)};
+import { ensureAppRouteModulesLoaded as __ensureRouteLoaded } from ${JSON.stringify(appRouteModuleLoaderPath)};
 import {
   getRenderedConcreteUrlPathsForRoute as __getRenderedConcreteUrlPathsForRoute,
   initPregeneratedPathsFromGlobals as __initPregeneratedPathsFromGlobals,
@@ -744,7 +783,7 @@ function __VINEXT_CLASS_REASONS(routeIdx) {
 const routes = [
 ${routeEntries.join(",\n")}
 ];
-const __routeMatcher = __createAppRscRouteMatcher(routes);
+const __routeMatcher = __createAppRscRouteMatcher(routes, ${JSON.stringify(buildAppDecodedPathnamePatterns(routes, config))});
 
 ${instrumentationPath ? "let metadataRoutes;" : `const metadataRoutes = [
 ${metaRouteEntries.join(",\n")}
@@ -841,6 +880,10 @@ function matchRequestRoute(url) {
   return __routeMatcher.matchRequestRoute(url);
 }
 
+function matchRawRequestRoute(url) {
+  return __routeMatcher.matchRawRequestRoute(url);
+}
+
 /**
  * Check if a pathname matches any intercepting route.
  * Returns the match info or null.
@@ -952,6 +995,7 @@ ${rootParamNameEntries.join("\n")}
 __setPagesClientAssets(__pagesClientAssets);
 function __VINEXT_ACTION_OWNERS() { return ${actionOwners === void 0 ? "__vinextActionOwners" : safeJsonStringify(actionOwners)}; }
 ${responseStageOnly ? "const __responseStageOptions = {" : "const __appRscHandler = createAppRscHandler({"}
+  assetPrefix: __assetPrefix,
   basePath: __basePath,
   buildId: process.env.__VINEXT_BUILD_ID ?? null,
   ensureRouteLoaded: __ensureRouteLoaded,
@@ -999,6 +1043,7 @@ ${responseStageOnly ? "const __responseStageOptions = {" : "const __appRscHandle
     scriptNonce,
     searchParams,
     renderMode,
+    renderWholeDocument,
   }) {
     const PageComponent = route.page?.default;
     const __segmentConfigBranches = __resolveRouteSegmentConfigBranches(route);
@@ -1020,7 +1065,6 @@ ${responseStageOnly ? "const __responseStageOptions = {" : "const __appRscHandle
       routePatternParts: route.patternParts,
       routeSegments: route.routeSegments,
     });
-    const _asyncRouteParams = makeThenableParams(params);
     return __dispatchAppPage({
       basePath: __basePath,
       bypassInterceptionContextCache,
@@ -1039,6 +1083,7 @@ ${responseStageOnly ? "const __responseStageOptions = {" : "const __appRscHandle
           observePageSearchParamsAccess: buildOptions?.observePageSearchParamsAccess === true,
           isForceStatic: buildOptions?.isForceStatic === true,
           serveStreamingMetadata: buildOptions?.serveStreamingMetadata,
+          placeStreamedMetadataInHead: buildOptions?.placeStreamedMetadataInHead === true,
           isProduction: process.env.NODE_ENV === "production",
         }, layoutParamAccess, displayPathname, scriptNonce);
       },
@@ -1126,31 +1171,6 @@ ${responseStageOnly ? "const __responseStageOptions = {" : "const __appRscHandle
           route,
         });
       },
-      async probePage(probeSearchParams = searchParams) {
-        const __probeIntercept = findIntercept(
-          interceptionPathname,
-          interceptionContext,
-          interceptionId,
-        );
-        // The intercepting-route page module is lazy (page: null + __pageLoader).
-        // Resolve it before probing so buildAppPageProbes inspects the real page
-        // component for dynamic bailout — matching the render path, which also
-        // hydrates it (resolveAppPageInterceptState). Without this the intercept
-        // probe branch silently inspects an undefined component and never
-        // observes the page's searchParams/headers access. Shared loader, so
-        // the import is isolated from the request context here too.
-        if (__probeIntercept) await __loadAppInterceptPage(__probeIntercept);
-        return Promise.all(__buildAppPageProbes({
-          route,
-          pageComponent: PageComponent,
-          asyncRouteParams: _asyncRouteParams,
-          searchParams: probeSearchParams,
-          intercept: __probeIntercept,
-          isRscRequest,
-          matchedParams: params,
-          makeThenableParams,
-        }));
-      },
       renderErrorBoundaryPage(renderErr, errorOrigin) {
         const __activeIntercept = findIntercept(
           interceptionPathname,
@@ -1209,6 +1229,7 @@ ${responseStageOnly ? "const __responseStageOptions = {" : "const __appRscHandle
       searchParams,
       setNavigationContext,
       renderMode,
+      renderWholeDocument,
     });
   },
   async dispatchMatchedRouteHandler({
@@ -1563,6 +1584,7 @@ ${responseStageOnly ? "const __responseStageOptions = {" : "const __appRscHandle
   },` : ""}
   matchRoute,
   matchRequestRoute,
+  matchRawRequestRoute,
   hasInterceptionId,
   matchInterceptRoute(pathname, sourcePathname, interceptionId) {
     const intercept = findIntercept(pathname, sourcePathname, interceptionId);

package/dist/index.d.ts

@@ -106,7 +106,10 @@ export type VinextOptions = {
    * Configure cache handlers declaratively, so you don't need a custom worker
    * entry that calls `setDataCacheHandler()` / `setCdnCacheAdapter()`. Each slot
    * is a `{ adapter, options }` descriptor pointing at an adapter module whose
-   * default export is a factory; the plugin registers them automatically on the
+   * default export is a factory function or a class; either receives one
+   * `{ env, options }` argument (classes are invoked with `new`, other
+   * functions are called; see `CacheAdapterDescriptor.adapter` for how
+   * classes are recognised). The plugin registers them automatically on the
    * first request, passing the host `env` (Worker bindings) so adapters that
    * need a binding — e.g. a KV namespace — can read it.
    *