@wular/pnext 0.0.1

package/src/compat/bundler/worker.ts

@@ -0,0 +1,278 @@
+// Web Worker bundling (COMPAT - `new Worker(new URL('./w', import.meta.url))`).
+//
+// Next/webpack/turbopack detect this pattern (and SharedWorker) in client code, bundle the referenced
+// module as its own entry chunk, and swap the URL expression for the emitted chunk URL. esbuild has no
+// native support, so this pass:
+//   1. runs as the client-source chain's async PRE-transform, ahead of the sync passes, one of which
+//      inlines the `import.meta.url` this pattern needs,
+//   2. resolves each worker specifier (honoring TS/JSX extensions and any configured resolveExtensions),
+//   3. bundles the worker file with its own esbuild pass - IIFE output so classic AND module workers
+//      both execute it, with internal dynamic imports inlined,
+//   4. rewrites the `new URL(...)` argument to the emitted chunk's public URL string literal.
+//
+// Worker graphs get their own static-asset handling, reusing the compat staticAssetModule extension for
+// images and a generic `{ src }` module for other assets.
+
+import { createHash } from 'node:crypto';
+import { existsSync, statSync } from 'node:fs';
+import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { build, type Plugin } from 'esbuild';
+import { publicEnvDefines, type ResolvedConfig } from '../../config';
+import { getAssetExtensions } from '../../extensions';
+
+// `new Worker(new URL('<spec>', import.meta.url)` / SharedWorker — the URL
+// argument must be a string literal and the base exactly `import.meta.url`.
+const workerPattern = () =>
+  /\bnew\s+(Worker|SharedWorker)\(\s*new\s+URL\(\s*(['"])([^'"]+)\2\s*,\s*import\.meta\.url\s*\)/g;
+
+/** Cheap gate: does this source construct a Worker from a `new URL(...)`? */
+export function sourceHasWorkerNewUrl(source: string): boolean {
+  return (
+    (source.includes('new Worker(') || source.includes('new SharedWorker(')) &&
+    workerPattern().test(source)
+  );
+}
+
+const workerSpecifierExtensions = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.mts'];
+
+function isFile(file: string): boolean {
+  try {
+    return statSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function resolveWorkerEntry(
+  importerDir: string,
+  specifier: string,
+  configuredExtensions: readonly string[] | undefined,
+): string | undefined {
+  if (!specifier.startsWith('.')) return undefined;
+  const base = path.resolve(importerDir, specifier);
+  if (path.extname(base) && isFile(base)) return base;
+  for (const extension of configuredExtensions ?? workerSpecifierExtensions) {
+    if (extension === '') {
+      if (isFile(base)) return base;
+      continue;
+    }
+    const candidate = `${base}${extension}`;
+    if (isFile(candidate)) return candidate;
+  }
+  // A configured extension list that misses the worker's real extension must
+  // not break the build — fall back to the built-in source order.
+  if (configuredExtensions) {
+    for (const extension of workerSpecifierExtensions) {
+      const candidate = `${base}${extension}`;
+      if (isFile(candidate)) return candidate;
+    }
+  }
+  return isFile(base) ? base : undefined;
+}
+
+// Any importable asset a worker may reference: static images (compat descriptor
+// module) plus generic binary assets (.wasm) exposed as `{ src }`.
+const workerAssetFilter = /\.(?:png|jpe?g|gif|webp|avif|svg|ico|bmp|wasm)(?:$|[?#])/;
+
+// Workers fetch `.wasm` via `new URL('./x.wasm', import.meta.url)`; rewrite it
+// (and image URLs) onto the asset import pipeline exactly like the main-graph
+// new-url-asset transform, but with `.wasm` included.
+const workerNewUrlAssetPattern = () =>
+  /new\s+URL\(\s*(['"])([^'"]+?\.(?:png|jpe?g|gif|webp|avif|svg|ico|bmp|wasm)(?:[?#][^'"]*)?)\1\s*,\s*import\.meta\.url\s*\)/g;
+
+function rewriteWorkerNewUrlAssets(source: string): string {
+  if (!source.includes('import.meta.url')) return source;
+  const bindings = new Map<string, string>();
+  const replaced = source.replace(workerNewUrlAssetPattern(), (_match, _quote, spec: string) => {
+    let binding = bindings.get(spec);
+    if (!binding) {
+      binding = `__pnext_worker_url_${bindings.size}`;
+      bindings.set(spec, binding);
+    }
+    return `(${binding}.src)`;
+  });
+  if (bindings.size === 0) return source;
+  const imports = [...bindings]
+    .map(([spec, binding]) => `import ${binding} from ${JSON.stringify(spec)};`)
+    .join('\n');
+  return `${imports}\n${replaced}`;
+}
+
+function splitAssetHash(specifier: string) {
+  const index = specifier.search(/[?#]/);
+  return index === -1
+    ? { sourcePath: specifier, hash: '' }
+    : { sourcePath: specifier.slice(0, index), hash: specifier.slice(index) };
+}
+
+async function workerAssetModuleSource(config: ResolvedConfig, file: string): Promise<string> {
+  const { sourcePath } = splitAssetHash(file);
+  const bytes = new Uint8Array(await readFile(sourcePath));
+  const emitted: string[] = [];
+  const emit = (relative: string) => {
+    emitted.push(relative);
+    return `/${relative}`;
+  };
+  let source = await getAssetExtensions().staticAssetModule({ sourcePath, bytes, emit });
+  if (!source) {
+    const ext = path.extname(sourcePath).toLowerCase() || '.bin';
+    const hash = createHash('sha256').update(bytes).digest('hex').slice(0, 8);
+    const base = path
+      .basename(sourcePath, path.extname(sourcePath))
+      .replace(/[^A-Za-z0-9_-]+/g, '-');
+    const relative = getAssetExtensions().staticAssetRelativePath({ sourcePath, base, hash, ext });
+    const src = emit(relative);
+    // `.src` (worker new-URL rewrite) and default-as-string both observable.
+    source = `const src = ${JSON.stringify(src)};\nexport default { src };\nexport { src };\n`;
+  }
+  for (const relative of emitted) {
+    const target = path.join(config.outPath, 'public', ...relative.split('/'));
+    await mkdir(path.dirname(target), { recursive: true });
+    if (!existsSync(target)) await copyFile(sourcePath, target);
+  }
+  return source;
+}
+
+function workerAssetPlugin(config: ResolvedConfig): Plugin {
+  return {
+    name: 'pnext-worker-static-assets',
+    setup(build) {
+      // Worker-graph sources referencing assets via `new URL(..., import.meta.url)`
+      // (esbuild would otherwise mangle `import.meta.url` in the iife output) are
+      // rewritten onto the asset import pipeline below.
+      build.onLoad({ filter: /\.(?:js|mjs|jsx|ts|tsx|mts)$/, namespace: 'file' }, async args => {
+        const source = await readFile(args.path, 'utf8');
+        if (!workerNewUrlAssetPattern().test(source)) return undefined;
+        const loader = args.path.endsWith('.ts')
+          ? ('ts' as const)
+          : args.path.endsWith('.mts')
+            ? ('ts' as const)
+            : args.path.endsWith('.tsx')
+              ? ('tsx' as const)
+              : ('jsx' as const);
+        return { contents: rewriteWorkerNewUrlAssets(source), loader };
+      });
+      build.onResolve({ filter: workerAssetFilter }, args => {
+        const { sourcePath, hash } = splitAssetHash(args.path);
+        const resolved = path.isAbsolute(sourcePath)
+          ? sourcePath
+          : path.resolve(args.resolveDir, sourcePath);
+        return { path: `${resolved}${hash}`, namespace: 'pnext-worker-asset' };
+      });
+      build.onLoad({ filter: /.*/, namespace: 'pnext-worker-asset' }, async args => ({
+        contents: await workerAssetModuleSource(config, args.path),
+        loader: 'js',
+      }));
+    },
+  };
+}
+
+function workerDefines(): Record<string, string> {
+  const defines: Record<string, string> = {
+    ...publicEnvDefines(),
+    'process.browser': 'true',
+  };
+  // Next inlines the deployment id into every graph, workers included.
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  const deploymentId = process.env.NEXT_DEPLOYMENT_ID;
+  if (deploymentId !== undefined) {
+    defines['process.env.NEXT_DEPLOYMENT_ID'] = JSON.stringify(deploymentId);
+  }
+  return defines;
+}
+
+/**
+ * Bundle one worker entry into `<out>/public/assets/workers/` and return its
+ * public URL path. Deduplicated per resolved entry file across the whole
+ * client build via the caller's cache.
+ */
+async function bundleWorkerEntry(config: ResolvedConfig, entry: string): Promise<string> {
+  const result = await build({
+    entryPoints: [entry],
+    bundle: true,
+    write: false,
+    // IIFE runs under both `new Worker(url)` (classic) and `{ type: 'module' }`
+    // workers; internal dynamic imports are inlined (no splitting), so no
+    // runtime chunk loader is needed.
+    format: 'iife',
+    platform: 'browser',
+    minify: true,
+    define: workerDefines(),
+    plugins: [workerAssetPlugin(config)],
+    logLevel: 'silent',
+  });
+  const output = result.outputFiles[0];
+  if (!output) throw new Error(`pnext: worker bundle produced no output for ${entry}`);
+  const hash = createHash('sha256').update(output.contents).digest('hex').slice(0, 8);
+  const base = path.basename(entry, path.extname(entry)).replace(/[^A-Za-z0-9_-]+/g, '-');
+  const relative = path.posix.join('assets', 'workers', `${base}.${hash}.js`);
+  const target = path.join(config.outPath, 'public', ...relative.split('/'));
+  await mkdir(path.dirname(target), { recursive: true });
+  await writeFile(target, output.contents);
+  return `/${relative}`;
+}
+
+/**
+ * CLIENT-graph source transform: bundle each worker entry a source constructs
+ * from `new URL(..., import.meta.url)` and substitute the emitted chunk URL.
+ * The bundle cache is per-transform (one per registration), so a worker shared
+ * by many modules is built once per build.
+ */
+export function createClientWorkerTransform(
+  config: ResolvedConfig,
+  configuredExtensions: readonly string[] | undefined,
+): (source: string, file: string) => Promise<string> {
+  const bundleCache = new Map<string, Promise<string>>();
+  return async (source, file) => {
+    if (!sourceHasWorkerNewUrl(source)) return source;
+    const rewritten = await rewriteWorkerSource(
+      config,
+      source,
+      file,
+      bundleCache,
+      configuredExtensions,
+    );
+    return rewritten ?? source;
+  };
+}
+
+/**
+ * Rewrite every worker construction in `source` (resolving + bundling each
+ * referenced worker module) and return the transformed source, or undefined
+ * when nothing matched/resolved (caller falls through to the normal loader).
+ */
+export async function rewriteWorkerSource(
+  config: ResolvedConfig,
+  source: string,
+  file: string,
+  bundleCache: Map<string, Promise<string>>,
+  configuredExtensions: readonly string[] | undefined,
+): Promise<string | undefined> {
+  const importerDir = path.dirname(file);
+  const matches = [...source.matchAll(workerPattern())];
+  if (matches.length === 0) return undefined;
+
+  const urls = new Map<string, string>();
+  for (const match of matches) {
+    const spec = match[3]!;
+    if (urls.has(spec)) continue;
+    const entry = resolveWorkerEntry(importerDir, spec, configuredExtensions);
+    if (!entry) continue; // unresolvable: leave the construction untouched
+    let pending = bundleCache.get(entry);
+    if (!pending) {
+      pending = bundleWorkerEntry(config, entry);
+      bundleCache.set(entry, pending);
+    }
+    urls.set(spec, await pending);
+  }
+  if (urls.size === 0) return undefined;
+
+  return source.replace(
+    workerPattern(),
+    (match, ctor: string, _quote: string, spec: string) => {
+      const url = urls.get(spec);
+      return url ? `new ${ctor}(${JSON.stringify(url)}` : match;
+    },
+  );
+}

package/src/compat/cache/build-flags.ts

@@ -0,0 +1,81 @@
+// Build flags the SERVING runtime needs (COMPAT).
+//
+// `next build --debug-prerender` changes what a production server logs for an error that crosses the
+// 'use cache' boundary (real frames + environmentName vs minified frames + a redacted error). The flag
+// is a build-time input, so the build records it next to the other server artifacts and start reads it
+// back.
+//
+// State is anchored on globalThis: the built compat-server bundle and the original module can both be
+// loaded in one process, and a module-local cache would then be filled in one copy and empty in the other.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+const BUILD_FLAG_GLOBALS = Symbol.for('pnext.compat.buildFlags');
+
+export interface BuildFlags {
+  debugPrerender: boolean;
+}
+
+interface BuildFlagState {
+  /** The serving root's output dir, recorded by the init hook. */
+  outPath?: string;
+  /** Lazily read flags: `null` once a read found no build to serve. */
+  flags?: BuildFlags | null;
+}
+
+function state(): BuildFlagState {
+  const root = globalThis as unknown as Record<PropertyKey, BuildFlagState | undefined>;
+  return (root[BUILD_FLAG_GLOBALS] ??= {});
+}
+
+function flagsFile(outPath: string): string {
+  return path.join(outPath, 'server', 'pnext-build-flags.json');
+}
+
+/** Record the output dir at build/start init so the runtime can find the file. */
+export function setBuildFlagsOutPath(outPath: string): void {
+  const current = state();
+  if (current.outPath !== outPath) {
+    current.outPath = outPath;
+    current.flags = undefined;
+  }
+}
+
+/** Persist the build's `--debug-prerender` flag for the serving runtime. */
+export function writeBuildFlags(outPath: string, debugPrerender: boolean): void {
+  const file = flagsFile(outPath);
+  try {
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify({ debugPrerender })}\n`);
+  } catch {
+    // A read-only/absent output dir only costs the runtime this hint.
+  }
+  const current = state();
+  current.outPath = outPath;
+  current.flags = { debugPrerender };
+}
+
+/**
+ * The flags of the build being served, or undefined when there is none to read
+ * (a dev server, or a start against an output dir this process never built).
+ * Callers use the absence to stay out of production-only behavior.
+ */
+export function servedBuildFlags(): BuildFlags | undefined {
+  const current = state();
+  if (current.flags !== undefined) return current.flags ?? undefined;
+  const outPath = current.outPath;
+  if (outPath === undefined) return undefined;
+  let flags: BuildFlags | null = null;
+  try {
+    const file = flagsFile(outPath);
+    if (existsSync(file)) {
+      const parsed = JSON.parse(readFileSync(file, 'utf8')) as { debugPrerender?: unknown };
+      flags = { debugPrerender: parsed.debugPrerender === true };
+    }
+  } catch {
+    flags = null;
+  }
+  current.flags = flags;
+  return flags ?? undefined;
+}

package/src/compat/cache/build-prerender-errors.ts

@@ -0,0 +1,163 @@
+// Build-time `use cache` validation error collection (COMPAT).
+//
+// Three classes of `use cache` misuse must FAIL the build with Next's exact error text (the e2e suites
+// substring-match on the build output): a cache fill that never resolves during a prerender (E236
+// timeout), a `use cache` closure capturing a non-serializable function, and awaiting `searchParams`
+// inside a `use cache` scope (E842).
+//
+// The core build wraps each page prerender in try/catch and DEGRADES a failing page to dynamic, so a
+// thrown render error alone does not fail the build, and the caught search-params variant swallows the
+// throw entirely. Both cases are handled by RECORDING the violation here at the moment of detection
+// (inside the cache runtime, during a prerender) and surfacing them from a build-complete hook that
+// prints Next's messages and aborts. Collection is armed only for a compat build's prerender pass, so
+// the serving runtime and pure-core builds are unaffected.
+
+export type PrerenderErrorKind =
+  | 'hanging'
+  | 'close-over'
+  | 'search-params'
+  | 'use-cache-dynamic'
+  | 'unstable-cache-dynamic';
+
+export interface PrerenderError {
+  kind: PrerenderErrorKind;
+  route: string;
+  /** The error detail printed to stderr (Next's `Error: …` block). */
+  consoleBlock: string;
+}
+
+// The build process (which calls begin/end) and the built compat-server bundle (which runs the
+// prerender and records violations) each load their OWN copy of this module, so a module-local
+// armed/collected set by one copy is invisible to the other and detection would silently never fire.
+// Anchor the state on globalThis so every copy shares one collection window.
+const PRERENDER_ERROR_GLOBALS = Symbol.for('pnext.compat.prerenderErrorGlobals');
+
+interface PrerenderErrorState {
+  collected: PrerenderError[];
+  armed: boolean;
+}
+
+function state(): PrerenderErrorState {
+  const root = globalThis as Record<PropertyKey, unknown>;
+  return (root[PRERENDER_ERROR_GLOBALS] ??= { collected: [], armed: false }) as PrerenderErrorState;
+}
+
+/** Arm collection at the start of a compat build's prerender pass. */
+export function beginPrerenderErrorCollection(): void {
+  const s = state();
+  s.collected.length = 0;
+  s.armed = true;
+}
+
+/** Disarm collection and drain the recorded violations (build-complete hook). */
+export function endPrerenderErrorCollection(): PrerenderError[] {
+  const s = state();
+  s.armed = false;
+  const out = s.collected.slice();
+  s.collected.length = 0;
+  return out;
+}
+
+/**
+ * True while a compat build prerender is in progress. The cache-runtime
+ * detectors gate on this so their throwing/timeout behavior is confined to
+ * `pnext build` and never affects `pnext start`/dev or pure-core builds.
+ */
+export function prerenderErrorCollectionActive(): boolean {
+  return state().armed;
+}
+
+export function recordPrerenderError(error: PrerenderError): void {
+  const s = state();
+  if (!s.armed) return;
+  const collected = s.collected;
+  if (collected.some(e => e.kind === error.kind && e.route === error.route)) return;
+  collected.push(error);
+  // Print at detection time (not only from the build-complete hook): a
+  // close-over violation rethrows out of the cache-components shell render and
+  // aborts the build BEFORE the complete hook runs, so the hook would never get
+  // to print it. Printing here guarantees the message reaches the build output
+  // (stderr) in every abort path; the hook only needs to force the non-zero
+  // exit for the swallowed cases (hanging / caught search-params).
+  console.error(error.consoleBlock);
+  if (error.route) {
+    console.error(`Error occurred prerendering page "${error.route}".`);
+  }
+}
+
+/**
+ * Derive the app-router pathname from a `use cache` function id (`<relative-file>#<name>`). Route
+ * groups and the trailing `page`/`route` segment are stripped. Returns '' when the id is not a
+ * recognizable app-router file.
+ */
+export function routeFromCacheId(id: string): string {
+  const file = id.split('#', 1)[0] ?? '';
+  const withoutExt = file.replace(/\.[jt]sx?$/, '');
+  const segments = withoutExt.split('/');
+  if (segments[0] === 'app' || segments[0] === 'src') segments.shift();
+  if (segments[0] === 'app') segments.shift();
+  const last = segments[segments.length - 1];
+  if (last === 'page' || last === 'route' || last === 'default') segments.pop();
+  const routeSegments = segments.filter(seg => !/^\(.*\)$/.test(seg));
+  return `/${routeSegments.join('/')}`.replace(/\/+$/, '') || '/';
+}
+
+// --- Next's exact error strings -------------------------------------------
+
+export const USE_CACHE_HANGING_MESSAGE =
+  'Filling a cache during prerender timed out, likely because request-specific ' +
+  'arguments such as params, searchParams, cookies() or dynamic data were used ' +
+  'inside "use cache".';
+
+export const USE_CACHE_CLOSE_OVER_FUNCTION_MESSAGE =
+  'Functions cannot be passed directly to Client Components unless you ' +
+  'explicitly expose it by marking it with "use server". Or maybe you meant to ' +
+  'call this function rather than return it.';
+
+/** The `[function]` / caret block Next prints under the close-over error. */
+export const USE_CACHE_CLOSE_OVER_FUNCTION_BLOCK =
+  `\nError: ${USE_CACHE_CLOSE_OVER_FUNCTION_MESSAGE}` + '\n  [function]' + '\n   ^^^^^^^^';
+
+/**
+ * Next's E838 message: a dynamic request API (`cookies()`/`headers()`/
+ * `connection()`) invoked inside a function cached with `unstable_cache()`. The
+ * e2e build suite substring-matches the first sentence
+ * (`Route <route> used \`<api>\` inside a function cached with \`unstable_cache()\`.`);
+ * the remainder mirrors Next's full runtime text.
+ */
+export function unstableCacheDynamicApiMessage(
+  route: string,
+  api: 'cookies()' | 'headers()' | 'connection()',
+): string {
+  return (
+    `Route ${route} used \`${api}\` inside a function cached with ` +
+    '`unstable_cache()`. Accessing Dynamic data sources inside a cache scope is ' +
+    `not supported. If you need this data inside a cached function use \`${api}\` ` +
+    'outside of the cached function and pass the required dynamic data in as an ' +
+    'argument. See more info here: ' +
+    'https://nextjs.org/docs/app/api-reference/functions/unstable_cache'
+  );
+}
+
+export function useCacheDynamicApiMessage(
+  route: string,
+  api: 'cookies()' | 'headers()' | 'connection()',
+): string {
+  return (
+    `Route ${route} used \`${api}\` inside "use cache". Accessing Dynamic data ` +
+    'sources inside a cache scope is not supported. If you need this data inside ' +
+    `a cached function use \`${api}\` outside of the cached function and pass the ` +
+    'required dynamic data in as an argument. See more info here: ' +
+    'https://nextjs.org/docs/messages/next-request-in-use-cache'
+  );
+}
+
+export function useCacheSearchParamsMessage(route: string): string {
+  return (
+    `Route ${route} used \`searchParams\` inside "use cache". Accessing dynamic ` +
+    'request data inside a cache scope is not supported. If you need some search ' +
+    'params inside a cached function await `searchParams` outside of the cached ' +
+    'function and pass only the required search params as arguments to the cached ' +
+    'function. See more info here: https://nextjs.org/docs/messages/next-request-in-use-cache'
+  );
+}

package/src/compat/cache/custom-handler.ts

@@ -0,0 +1,159 @@
+// ---------------------------------------------------------------------------
+// Custom cache-handler loader (COMPAT).
+//
+// Reads the `cacheHandler` path from next.config, loads it in every supported
+// module shape, instantiates the class once, and installs the instance into the
+// core cache seam (src/cache/handler.ts). Runs from a build/start init hook.
+//
+// The config value is one of:
+//   - an absolute filesystem path  (`process.cwd() + '/' + env`)
+//   - a `require.resolve(...)` path (absolute)
+//   - a `file://` URL              (`import.meta.resolve('./x.js')`)
+// and the module exports the handler class as `module.exports`, `.default`, or
+// an ESM `export default`. On Bun, `require()` loads ESM synchronously, so a
+// single require covers every shape.
+// ---------------------------------------------------------------------------
+
+import { createRequire } from 'node:module';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { getNextConfig } from '../next/config-loader';
+import { setCacheHandler, type CacheHandler } from './handler';
+
+type CacheHandlerCtor = new (options: { maxMemoryCacheSize?: number }) => CacheHandler;
+
+let installedFor: string | undefined;
+let installedRoot: string | undefined;
+
+/**
+ * Load + instantiate the configured `cacheHandler` and install it into core.
+ * Idempotent per resolved path; no-op when unconfigured. Instantiation logs
+ * ("initialized custom cache-handler") are what the suites assert.
+ */
+export function installCustomCacheHandler(root: string): void {
+  const configured = getNextConfig().cacheHandler;
+  if (typeof configured !== 'string' || configured.length === 0) {
+    if (installedFor !== undefined) {
+      setCacheHandler(undefined);
+      installedFor = undefined;
+      installedRoot = undefined;
+    }
+    return;
+  }
+  const resolved = configured.startsWith('file:') ? fileURLToPath(configured) : configured;
+  // `import.meta.resolve('./x.js')` in next.config resolves against the bundled
+  // config location (`.pnext/config/`), not the project — fall back to the same
+  // basename at the project root so the handler still loads.
+  const filePath =
+    existsSync(resolved) || !path.isAbsolute(resolved)
+      ? resolved
+      : existsSync(path.join(root, path.basename(resolved)))
+        ? path.join(root, path.basename(resolved))
+        : resolved;
+  if (installedFor === filePath) return;
+
+  const Ctor = loadHandlerCtor(filePath, root);
+  if (!Ctor) return;
+  const instance = new Ctor({});
+  setCacheHandler(instance);
+  installedFor = filePath;
+  installedRoot = root;
+}
+
+export function reinstallCustomCacheHandlerForEdge(): void {
+  if (!installedRoot) return;
+  installedFor = undefined;
+  installCustomCacheHandler(installedRoot);
+}
+
+function loadHandlerCtor(filePath: string, root: string): CacheHandlerCtor | undefined {
+  try {
+    const require = createRequire(pathToFileURL(`${root}/index.js`).href);
+    try {
+      return pickCtor(require(filePath));
+    } catch (error) {
+      // Handlers commonly extend Next internals (e.g. `require('next/dist/
+      // server/lib/incremental-cache/file-system-cache')`) that don't exist
+      // without a real `next` install. Re-evaluate the module with those
+      // requires stubbed to an inert base class so the subclass (whose own
+      // get/set overrides carry the observable behavior) still loads.
+      if (!isNextDistMissing(error)) return undefined;
+      return loadCommonJsCtorWithNextStubs(filePath, require);
+    }
+  } catch {
+    return undefined;
+  }
+}
+
+function loadCommonJsCtorWithNextStubs(
+  filePath: string,
+  rootRequire: NodeRequire,
+): CacheHandlerCtor | undefined {
+  try {
+    const module = { exports: {} as unknown };
+    const localRequire = (specifier: string): unknown => {
+      if (specifier.startsWith('next/dist/')) return nextDistStubModule();
+      if (specifier.startsWith('./') || specifier.startsWith('../')) {
+        return rootRequire(path.resolve(path.dirname(filePath), specifier));
+      }
+      return rootRequire(specifier);
+    };
+    const source = readFileSync(filePath, 'utf8');
+    // eslint-disable-next-line @typescript-eslint/no-implied-eval
+    const evaluate = new Function('require', 'module', 'exports', '__filename', '__dirname', source) as (
+      require: (specifier: string) => unknown,
+      module: { exports: unknown },
+      exports: unknown,
+      filename: string,
+      dirname: string,
+    ) => void;
+    evaluate(localRequire, module, module.exports, filePath, path.dirname(filePath));
+    return pickCtor(module.exports);
+  } catch {
+    return undefined;
+  }
+}
+
+function isNextDistMissing(error: unknown): boolean {
+  const message = (error as { message?: unknown }).message;
+  return typeof message === 'string' && message.includes('next/dist/');
+}
+
+/**
+ * Inert stand-in for a `next/dist/*` module a classic cache handler extends.
+ * The base class carries tolerant no-op cache methods so a subclass's
+ * `super.get/set(...)` calls work; the Proxy serves it for both
+ * `module.exports` and `.default` interop shapes.
+ */
+function nextDistStubModule(): unknown {
+  class NextDistStub {
+    get(): Promise<null> {
+      return Promise.resolve(null);
+    }
+    set(): Promise<void> {
+      return Promise.resolve();
+    }
+    revalidateTag(): Promise<void> {
+      return Promise.resolve();
+    }
+    resetRequestCache(): null {
+      return null;
+    }
+  }
+  return new Proxy(NextDistStub, {
+    get: (target, key) =>
+      key === 'default'
+        ? NextDistStub
+        : ((target as unknown as Record<string | symbol, unknown>)[key] ?? NextDistStub),
+  });
+}
+
+function pickCtor(mod: unknown): CacheHandlerCtor | undefined {
+  if (typeof mod === 'function') return mod as CacheHandlerCtor;
+  if (mod && typeof mod === 'object') {
+    const record = mod as Record<string, unknown>;
+    if (typeof record.default === 'function') return record.default as CacheHandlerCtor;
+  }
+  return undefined;
+}