@wular/pnext 0.0.1

package/src/compat/pages/router-state.ts

@@ -0,0 +1,94 @@
+// Pages-router SSR state (COMPAT). The materialized page wrappers call pagesRouterSsrState() with their
+// pages-route pattern and resolved params; the resulting state (pattern pathname, canonical asPath,
+// merged query) is stashed on the anchored per-request scope so the next/router shim - which SSRs the
+// page component from a separately compiled bundle - returns the values Next's useRouter() would. The
+// wrapper also serializes the state into a `<script type="application/json">` node so the browser-side
+// shim reads the same values after hydration and after soft navigations.
+
+import type { RouteParamValue } from '../../types';
+
+export interface PagesRouterSsrState {
+  /** Pages-route pattern, e.g. `/blog/[slug]`. */
+  pathname: string;
+  /** The as-requested URL (path + original search), pre-rewrite. */
+  asPath: string;
+  /** Rewrite-destination search params merged with dynamic route params. */
+  query: Record<string, string | string[]>;
+}
+
+const STATE_KEY = Symbol.for('pnext.pagesRouterState');
+const REQUEST_STORAGE = Symbol.for('pnext.requestStorage');
+const WORK_UNIT_STORAGE = Symbol.for('pnext.workUnitStorage');
+const CANONICAL_URL_KEY = Symbol.for('pnext.compat.navigation.canonicalUrl');
+
+interface StorageLike {
+  getStore(): Record<PropertyKey, unknown> | undefined;
+}
+
+// All reads go through the globalThis-anchored storages (never module-local
+// imports): the wrapper bundle, the router shim bundle, and core each carry
+// their own compiled copy of this module, and only the anchored instances are
+// shared between them.
+function anchoredScope(key: symbol): Record<PropertyKey, unknown> | undefined {
+  const storage = (globalThis as Record<PropertyKey, unknown>)[key] as StorageLike | undefined;
+  return storage?.getStore?.();
+}
+
+function currentRequestUrl(): string | undefined {
+  const scope = anchoredScope(REQUEST_STORAGE);
+  const request = scope?.request as { url?: string } | undefined;
+  return typeof request?.url === 'string' ? request.url : undefined;
+}
+
+function canonicalHref(): string | undefined {
+  const unit = anchoredScope(WORK_UNIT_STORAGE);
+  const compat = unit?.compat as Record<symbol, unknown> | undefined;
+  const value = compat?.[CANONICAL_URL_KEY];
+  return typeof value === 'string' ? value : undefined;
+}
+
+/**
+ * Compute and stash the pages-router state for the active render. `pattern` is the pages-route pattern
+ * the materializer knows statically; `params` the resolved dynamic params. Query mirrors Next: the
+ * (rewrite-destination) request search merged with the route params, params winning. asPath is the
+ * canonical URL the browser asked for - its own search, never a rewrite's.
+ */
+export function pagesRouterSsrState(
+  pattern: string,
+  params: Record<string, RouteParamValue> | undefined,
+): PagesRouterSsrState {
+  const requestUrl = currentRequestUrl();
+  const canonical = canonicalHref() ?? requestUrl;
+  const query: Record<string, string | string[]> = {};
+  if (requestUrl) {
+    for (const [key, value] of new URL(requestUrl).searchParams) {
+      // The router-fetch cache key rides soft-navigation request URLs; it is
+      // never part of the page's query.
+      if (key !== '_rsc') query[key] = value;
+    }
+  }
+  for (const [key, value] of Object.entries(params ?? {})) {
+    if (value !== undefined) query[key] = value;
+  }
+  let asPath = pattern;
+  if (canonical) {
+    const url = new URL(canonical);
+    asPath = `${url.pathname}${url.search}`;
+  }
+  const state: PagesRouterSsrState = { pathname: pattern, asPath, query };
+  const scope = anchoredScope(REQUEST_STORAGE);
+  if (scope) scope[STATE_KEY] = state;
+  return state;
+}
+
+/** The state stashed by the active render's page wrapper, if any. */
+export function currentPagesRouterState(): PagesRouterSsrState | undefined {
+  const scope = anchoredScope(REQUEST_STORAGE);
+  const state = scope?.[STATE_KEY];
+  return state ? (state as PagesRouterSsrState) : undefined;
+}
+
+/** Serialize state for the inline JSON node (script-safe: `<` escaped). */
+export function serializePagesRouterState(state: PagesRouterSsrState): string {
+  return JSON.stringify(state).replace(/</g, '\\u003c');
+}

package/src/compat/ppr/io.ts

@@ -0,0 +1,38 @@
+// io() primitive (COMPAT). Marks the content AFTER `await io()` as dynamic under cacheComponents:
+// during prerender it is a hanging promise, so awaiting it postpones the boundary and that content
+// becomes a runtime hole; at request time it resolves so the content renders. Inside a `use cache`
+// scope it is a no-op (the cache is filled at build, so post-io content is buildtime), and without
+// cacheComponents it is a no-op entirely.
+
+import { cacheComponents, hangingPromise, isPrerendering } from '../../ppr';
+import { insideDataCacheProducer } from '../cache/revalidate';
+
+/**
+ * A resolved promise pre-tagged with React's tracked-thenable state (`status: 'fulfilled'`).
+ * `React.use(io())` is a supported call site, and our use() short-circuits a fulfilled thenable instead
+ * of suspending. A plain `Promise.resolve()` has no status, so use() would throw to suspend and -
+ * because io() returns a FRESH promise on every replay and the pages render has no use()-thenable
+ * replay scope - the component would re-throw forever. `await io()` is unaffected.
+ */
+function resolvedIo(): Promise<void> {
+  const promise = Promise.resolve() as Promise<void> & {
+    status?: string;
+    value?: undefined;
+  };
+  promise.status = 'fulfilled';
+  promise.value = undefined;
+  return promise;
+}
+
+/**
+ * Await this to mark subsequent content dynamic. See module header for the
+ * prerender / request / use-cache / no-cacheComponents matrix.
+ */
+export function io(): Promise<void> {
+  if (!cacheComponents()) return resolvedIo();
+  // Inside a `use cache` / unstable_cache producer the cache boundary wins: the
+  // value is produced at build, so io() does not postpone.
+  if (insideDataCacheProducer()) return resolvedIo();
+  if (isPrerendering()) return hangingPromise<void>('io()');
+  return resolvedIo();
+}

package/src/compat/ppr/missing-root-params.ts

@@ -0,0 +1,105 @@
+// Missing-root-params build validation (COMPAT, cacheComponents).
+//
+// Under cacheComponents, a ROOT param (a dynamic segment at or above a root layout) MUST be enumerated
+// by generateStaticParams: the root layout / document shell is built ahead of the request, so its
+// params cannot hang like an ordinary dynamic hole. A route that carries a root param with no value
+// provided is a hard build error, with a distinct message for one vs several missing params.
+//
+// The message string embeds the leading `Error: ` because the CLI prints the thrown error's raw
+// `.message`, and the Next e2e suite substring-matches it verbatim off cliOutput. Runs as a build step
+// gated on cacheComponents, ordered before the prerender pass so the build aborts before any shell work.
+
+import type { ResolvedConfig } from '../../config';
+import type { RouteManifestEntry } from '../../types';
+import { staticParamsFor } from '../../render';
+import { PnextBuildValidationError } from '../validation';
+import { scanRootParams } from './root-params-scan';
+
+/**
+ * Convert a colon route pattern (`/:lang/blog/:slug`) to the bracket form Next
+ * prints in build errors (`/[lang]/blog/[slug]`). A `*`/`+` suffix marks a
+ * catch-all (`:slug*` -> `[...slug]`); a trailing `?` marks it optional
+ * (`[[...slug]]`).
+ */
+function toBracketPattern(pattern: string): string {
+  return pattern
+    .split('/')
+    .map(segment => {
+      if (!segment.startsWith(':')) return segment;
+      let name = segment.slice(1);
+      let optional = false;
+      let catchAll = false;
+      if (name.endsWith('?')) {
+        optional = true;
+        name = name.slice(0, -1);
+      }
+      if (name.endsWith('*') || name.endsWith('+')) {
+        catchAll = true;
+        name = name.slice(0, -1);
+      }
+      if (catchAll) return optional ? `[[...${name}]]` : `[...${name}]`;
+      return `[${name}]`;
+    })
+    .join('/');
+}
+
+/** The keys generateStaticParams actually enumerated for this route. */
+function providedParamKeys(
+  allSets: Record<string, unknown>[],
+): Set<string> {
+  const provided = new Set<string>();
+  for (const set of allSets) {
+    for (const [key, value] of Object.entries(set)) {
+      if (value !== undefined) provided.add(key);
+    }
+  }
+  return provided;
+}
+
+/**
+ * Throw PnextBuildValidationError for the first page route that carries a root
+ * param with no generateStaticParams value. Root params are validated in route
+ * order (route.params order), so the message lists them the way they appear in
+ * the path pattern. No-op when the app defines no root params.
+ */
+export async function validateRootParamsProvided(
+  config: ResolvedConfig,
+  routes: RouteManifestEntry[],
+): Promise<void> {
+  const rootParams = scanRootParams(config.appPath);
+  if (rootParams.size === 0) return;
+
+  const pageRoutes = routes.filter(
+    route => route.kind === 'page' && !route.interception,
+  );
+
+  for (const route of pageRoutes) {
+    const routeRootParams = route.params.filter(name => rootParams.has(name));
+    if (routeRootParams.length === 0) continue;
+
+    let provided: Set<string>;
+    try {
+      const staticParams = await staticParamsFor(config, route);
+      provided = providedParamKeys(staticParams.allSets);
+    } catch {
+      // A generateStaticParams that throws provides nothing — treat every root
+      // param as missing rather than masking the (more relevant) config error.
+      provided = new Set<string>();
+    }
+
+    const missing = routeRootParams.filter(name => !provided.has(name));
+    if (missing.length === 0) continue;
+
+    const routePattern = toBracketPattern(route.route || '/');
+    if (missing.length === 1) {
+      throw new PnextBuildValidationError(
+        `Error: A required root parameter (${missing[0]}) was not provided in ` +
+          `generateStaticParams for ${routePattern}, please provide at least one value.`,
+      );
+    }
+    throw new PnextBuildValidationError(
+      `Error: Required root params (${missing.join(', ')}) were not provided in ` +
+        `generateStaticParams for ${routePattern}, please provide at least one value for each.`,
+    );
+  }
+}

package/src/compat/ppr/root-params-scan.ts

@@ -0,0 +1,164 @@
+// Root-params scan (COMPAT).
+//
+// A ROOT param is a dynamic segment that sits at or above a ROOT LAYOUT (a layout that renders
+// `<html>`). For `app/[lang]/[locale]/layout.tsx` as the root layout, both `lang` and `locale` are root
+// params. With multiple root layouts (route groups each owning their own `<html>`), the root-param set
+// is per-root-layout - a name is a root param when SOME root layout has it at or above its directory.
+//
+// The scan drives which names `next/root-params` legitimately exports (import validation) and typegen.
+// Route-group and slot dirs never contribute params; catch-all segments contribute their param name.
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+const LAYOUT_BASENAMES = ['layout.tsx', 'layout.ts', 'layout.jsx', 'layout.js'];
+
+/** True when a layout source renders `<html>` (i.e. it is a root/document layout). */
+function isRootLayoutSource(source: string): boolean {
+  return /<html[\s>]/.test(source);
+}
+
+/** Extract the param name from a segment dir name, or undefined for a static one. */
+function paramNameOfSegment(segment: string): string | undefined {
+  // [[...slug]] optional catch-all, [...slug] catch-all, [slug] dynamic.
+  const optional = /^\[\[\.\.\.(.+)\]\]$/.exec(segment);
+  if (optional) return optional[1];
+  const catchAll = /^\[\.\.\.(.+)\]$/.exec(segment);
+  if (catchAll) return catchAll[1];
+  const dynamic = /^\[(.+)\]$/.exec(segment);
+  if (dynamic) return dynamic[1];
+  return undefined;
+}
+
+function findLayoutFile(dir: string): string | undefined {
+  for (const base of LAYOUT_BASENAMES) {
+    const candidate = path.join(dir, base);
+    if (existsSync(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+/**
+ * Walk `app/` collecting, for every root layout, the param names on the path
+ * from app root down to (and including) that layout's directory. The union is
+ * the app's root-param set.
+ */
+export function scanRootParams(appPath: string): Set<string> {
+  const rootParams = new Set<string>();
+  if (!existsSync(appPath)) return rootParams;
+
+  const walk = (dir: string, paramsAbove: string[]): void => {
+    const layoutFile = findLayoutFile(dir);
+    if (layoutFile) {
+      let source = '';
+      try {
+        source = readFileSync(layoutFile, 'utf8');
+      } catch {
+        source = '';
+      }
+      if (isRootLayoutSource(source)) {
+        for (const name of paramsAbove) rootParams.add(name);
+      }
+    }
+    let children: string[] = [];
+    try {
+      children = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const child of children) {
+      const childPath = path.join(dir, child);
+      let isDir = false;
+      try {
+        isDir = statSync(childPath).isDirectory();
+      } catch {
+        isDir = false;
+      }
+      if (!isDir) continue;
+      if (child.startsWith('@')) continue; // parallel-route slot dir
+      const param = paramNameOfSegment(child);
+      walk(childPath, param ? [...paramsAbove, param] : paramsAbove);
+    }
+  };
+
+  walk(appPath, []);
+  return rootParams;
+}
+
+export type RootParamValueType = 'string' | 'string[]' | 'undefined';
+
+interface ScannedParam {
+  name: string;
+  segment: string;
+}
+
+/**
+ * Per-param value types for root-params typegen, mirroring Next's collection:
+ * `[name]` contributes `string`, `[...name]` contributes `string[]`,
+ * `[[...name]]` contributes `string[]` and `undefined`. With multiple root
+ * layouts, a param absent from some root also gains `undefined`.
+ */
+export function scanRootParamTypes(appPath: string): Map<string, Set<RootParamValueType>> {
+  const roots: Map<string, RootParamValueType[]>[] = [];
+  if (!existsSync(appPath)) return new Map();
+
+  const walk = (dir: string, paramsAbove: ScannedParam[]): void => {
+    const layoutFile = findLayoutFile(dir);
+    if (layoutFile) {
+      let source = '';
+      try {
+        source = readFileSync(layoutFile, 'utf8');
+      } catch {
+        source = '';
+      }
+      if (isRootLayoutSource(source)) {
+        const params = new Map<string, RootParamValueType[]>();
+        for (const { name, segment } of paramsAbove) {
+          params.set(
+            name,
+            segment.startsWith('[[...')
+              ? ['string[]', 'undefined']
+              : segment.startsWith('[...')
+                ? ['string[]']
+                : ['string'],
+          );
+        }
+        roots.push(params);
+      }
+    }
+    let children: string[] = [];
+    try {
+      children = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const child of children) {
+      const childPath = path.join(dir, child);
+      let isDir = false;
+      try {
+        isDir = statSync(childPath).isDirectory();
+      } catch {
+        isDir = false;
+      }
+      if (!isDir) continue;
+      if (child.startsWith('@')) continue; // parallel-route slot dir
+      const param = paramNameOfSegment(child);
+      walk(childPath, param ? [...paramsAbove, { name: param, segment: child }] : paramsAbove);
+    }
+  };
+
+  walk(appPath, []);
+
+  const combined = new Map<string, Set<RootParamValueType>>();
+  for (const params of roots) {
+    for (const [name, types] of params) {
+      const set = combined.get(name) ?? new Set<RootParamValueType>();
+      for (const type of types) set.add(type);
+      combined.set(name, set);
+    }
+  }
+  for (const [name, set] of combined) {
+    if (roots.some(params => !params.has(name))) set.add('undefined');
+  }
+  return combined;
+}

package/src/compat/ppr/root-params-transform.ts

@@ -0,0 +1,75 @@
+// next/root-params import rewrite (COMPAT).
+//
+// `next/root-params` exports one async getter per root param. The set of names is app-specific, so a
+// static alias module cannot list them as named exports - a bare `import { lang } from
+// 'next/root-params'` would fail at bundle time with "no matching export". This transform rewrites such
+// imports into named bindings pulled off the module's default Proxy, which resolves any getter:
+//
+//   import { lang, locale as l } from 'next/root-params';
+//     -> import __pnextRootParams from 'next/root-params';
+//        const lang = __pnextRootParams.lang;
+//        const l = __pnextRootParams.locale;
+//
+// The alias map still resolves the specifier to compat/next/root-params.ts, so the default import binds
+// the Proxy. Build-time validation that a name is actually a root param lives in root-params-scan.ts;
+// this transform stays permissive.
+
+import { isIdentifier, uniqueIdentifier } from '../../utils/source';
+
+const ROOT_PARAMS_SPECIFIER = /['"]next\/root-params['"]/;
+
+// `[^}]` for the clause, never a lazy `[\s\S]*?`: the latter backtracks across
+// an earlier `import { X } from 'react'` and swallows that line too.
+const IMPORT_RE =
+  /^[ \t]*import\s+\{([^}]*)\}\s+from\s+['"]next\/root-params['"]\s*;?[ \t]*(?:\r?\n)?/gm;
+
+interface Binding {
+  imported: string;
+  local: string;
+}
+
+function parseBindings(clause: string): Binding[] {
+  return clause
+    .split(',')
+    .map(part => part.trim())
+    .filter(Boolean)
+    .flatMap(part => {
+      if (part.startsWith('type ')) return [];
+      const [importedRaw, localRaw] = part.split(/\s+as\s+/);
+      const imported = importedRaw?.trim();
+      const local = (localRaw ?? importedRaw)?.trim();
+      if (!imported || !local || !isIdentifier(imported) || !isIdentifier(local)) return [];
+      return [{ imported, local }];
+    });
+}
+
+/**
+ * Rewrite `next/root-params` named imports to default-Proxy member reads.
+ * A no-op for sources that do not import the module. Registered as a server
+ * source transform and applied in the client bundler plugin.
+ */
+export function rewriteRootParamsSource(source: string): string {
+  if (!ROOT_PARAMS_SPECIFIER.test(source)) return source;
+  const proxyName = uniqueIdentifier(source, '__pnextRootParams');
+  const declarations: string[] = [];
+  let importedProxy = false;
+
+  const rewritten = source.replace(IMPORT_RE, (_statement, clause: string) => {
+    const bindings = parseBindings(clause);
+    if (bindings.length === 0) return '';
+    importedProxy = true;
+    for (const { imported, local } of bindings) {
+      declarations.push(
+        `const ${local} = ${proxyName}[${JSON.stringify(imported)}];`,
+      );
+    }
+    return '';
+  });
+
+  if (!importedProxy) return source;
+  return [
+    `import ${proxyName} from ${JSON.stringify('next/root-params')};`,
+    ...declarations,
+    rewritten,
+  ].join('\n');
+}

package/src/compat/ppr/root-params.ts

@@ -0,0 +1,129 @@
+// next/root-params runtime (COMPAT).
+//
+// `next/root-params` exports one async getter per ROOT param. Since the getter NAMES do not affect the
+// runtime (each getter just reads its own param off the request ALS param store), a single Proxy-backed
+// module satisfies every app.
+//
+// The build-time scan validates that only real root params are imported - importing a non-root name is
+// a build/dev error there - so this runtime is intentionally permissive and a valid getter always works.
+// Context errors (server action / route handler / unstable_cache) match Next's messages exactly.
+
+import { currentParams, currentRequest, getWorkUnit } from '../../request/context';
+import {
+  cacheComponents,
+  hangingPromise,
+  isPrerendering,
+  isRuntimePrefetchPrerender,
+} from '../../ppr';
+import { insideUnstableCacheProducer } from '../cache/revalidate';
+import { insideUseCacheProducer, recordUseCacheRootParamRead } from '../cache/use-cache';
+
+/** E-code errors Next throws for root-params used in an unsupported context. */
+function rootParamContextError(name: string): Error | undefined {
+  const unit = getWorkUnit();
+  const call = `\`import('next/root-params').${name}()\``;
+
+  const inUseCache = insideUseCacheProducer();
+  const inUnstableCache = insideUnstableCacheProducer();
+
+  // Root params inside a `use cache` NESTED within `unstable_cache`: E1140.
+  // (The `use cache` scope sits inside the unstable_cache producer, so both
+  // markers are active.) Root params are not available in that context.
+  if (inUseCache && inUnstableCache) {
+    return Object.assign(
+      new Error(
+        `Root params (${call}) were used inside a cache scope nested within \`unstable_cache\`. Root params are not available in this context.`,
+      ),
+      { digest: 'E1140' },
+    );
+  }
+
+  // Inside a plain `use cache` (not under unstable_cache): legal. Record the
+  // read so the entry's cache key participates in this root param (Stage B-3),
+  // then let the getter resolve the value below (no error).
+  if (inUseCache) {
+    recordUseCacheRootParamRead(name);
+    return undefined;
+  }
+
+  // Inside `unstable_cache` (a data-cache producer that is NOT a `use cache`
+  // scope): E1141.
+  if (inUnstableCache) {
+    return Object.assign(
+      new Error(
+        `Root params (${call}) were used inside \`unstable_cache\`. This is not supported. Use \`"use cache"\` instead.`,
+      ),
+      { digest: 'E1141' },
+    );
+  }
+
+  if (!unit) return undefined;
+
+  if (unit.phase === 'action') {
+    return new Error(
+      `${call} was used inside a Server Action. This is not supported. ` +
+        `Functions from 'next/root-params' can only be called in the context of a route.`,
+    );
+  }
+
+  // Route handlers are detected via routeKind (core sets no 'handler' phase).
+  if (unit.phase !== 'after' && unit.routeKind === 'route-handler') {
+    const route = (() => {
+      try {
+        return new URL(currentRequest()?.url ?? '').pathname;
+      } catch {
+        return '';
+      }
+    })();
+    return new Error(
+      `Route ${route} used ${call} inside a Route Handler. ` +
+        `Support for this API in Route Handlers is planned for a future version of Next.js.`,
+    );
+  }
+
+  return undefined;
+}
+
+/**
+ * Read a single root param off the request param store. Async (matching Next's
+ * getter shape). A catch-all resolves to an array; an absent optional catch-all
+ * resolves to undefined.
+ */
+export function rootParam<T = string | string[] | undefined>(name: string): Promise<T> {
+  const error = rootParamContextError(name);
+  if (error) return Promise.reject(error);
+  // A runtime-prefetch prerender renders against the REAL sampled request, so root params are concrete
+  // there (root params are always available in static prerenders, so a runtime prefetch has them too).
+  // Hanging them would postpone the root layout itself - the whole document, not a boundary - and the
+  // render would produce no shell at all.
+  if (
+    !insideUseCacheProducer() &&
+    cacheComponents() &&
+    isPrerendering() &&
+    !isRuntimePrefetchPrerender()
+  ) {
+    return hangingPromise<T>(`rootParam(${name})`);
+  }
+  const params = currentParams();
+  return Promise.resolve(params[name] as T);
+}
+
+/**
+ * The aliased module surface: a Proxy whose every string property is an async
+ * getter for that root param. `import { lang } from 'next/root-params'` picks up
+ * `rootParam('lang')`. Non-root imports are rejected at build (the scan), so
+ * this Proxy never needs to distinguish them at runtime.
+ */
+const rootParamsModule = new Proxy(
+  {},
+  {
+    get(_target, prop: string | symbol): unknown {
+      if (typeof prop !== 'string') return undefined;
+      if (prop === '__esModule') return true;
+      if (prop === 'default') return undefined;
+      return () => rootParam(prop);
+    },
+  },
+) as Record<string, () => Promise<unknown>>;
+
+export default rootParamsModule;

package/src/compat/ppr/segment-config-incompat.ts

@@ -0,0 +1,34 @@
+// Legacy segment-config incompatibility under cacheComponents (COMPAT). Under `cacheComponents: true`
+// the legacy per-segment route config exports are incompatible and must error at build. This module
+// produces the exact Next message for a given offending key and file path; it is delivered ready-to-wire
+// rather than wired into build validation here.
+
+/** The legacy segment-config exports that cacheComponents rejects. */
+export const INCOMPATIBLE_SEGMENT_KEYS = [
+  'revalidate',
+  'dynamicParams',
+  'dynamic',
+  'fetchCache',
+] as const;
+
+export type IncompatibleSegmentKey = (typeof INCOMPATIBLE_SEGMENT_KEYS)[number];
+
+/** Next's exact incompat message for an offending segment-config export. */
+export function segmentConfigIncompatMessage(key: IncompatibleSegmentKey, file: string): string {
+  return `"${key}" is not compatible with \`nextConfig.cacheComponents\`. Please remove it. Used in ${file}`;
+}
+
+const EXPORT_RE = (key: string) =>
+  new RegExp(`\\bexport\\s+const\\s+${key}\\b`);
+
+/**
+ * Scan a page/layout source for an incompatible segment-config export, returning
+ * the first offending key (or undefined). Layout configs propagate to child
+ * pages, so callers should scan the layout chain too.
+ */
+export function findIncompatibleSegmentKey(source: string): IncompatibleSegmentKey | undefined {
+  for (const key of INCOMPATIBLE_SEGMENT_KEYS) {
+    if (EXPORT_RE(key).test(source)) return key;
+  }
+  return undefined;
+}