@wular/pnext 0.0.1

package/src/compat/register/client-errors.ts

@@ -0,0 +1,18 @@
+// Client error runtime registration (COMPAT, client half).
+//
+// The client error runtime (src/compat/client/errors/*) is a BROWSER module bundled into each compat
+// client entry - like nav-compat and action-router it is imported and installed by the generated entry,
+// not wired into a server render registry. There is therefore no server-side extension to assign here:
+// this registrar exists as the single server-bootstrap wiring point and documents the entry-append
+// contract. The compat entry already imports the route's nearest error.js and installs the action-error
+// overlay; to activate the general client error pipeline it additionally calls installClientErrors.
+
+import type { ResolvedConfig } from '../../config';
+import { nextCompatEnabled } from '../../compat';
+
+export function registerClientErrorExtensions(config: ResolvedConfig): void {
+  if (!nextCompatEnabled(config)) return;
+  // No server-side render/routing extension: the client runtime installs in the
+  // browser from the generated entry (seam 5, clientEntryModules). Kept as the
+  // stable registration seam so the orchestrator can wire it uniformly.
+}

package/src/compat/register/config.ts

@@ -0,0 +1,17 @@
+// Config-source registration (COMPAT - may import core freely).
+//
+// registerConfigSource() wires the next.config.* loader into the core configSources seam. It runs earlier
+// than the other compat sub-registrars: loadConfig invokes it lazily, before bootstrapCompat, so the
+// next.config values feed pnext's resolved config for build AND start/dev. The orchestrator must call
+// this from register.ts too, so a single registerCompatExtensions() pass leaves the source installed.
+
+import { registerConfigSource as registerCoreConfigSource } from '../../config';
+import type { ConfigSourceOverrides } from '../../config';
+import { loadNextConfig } from '../next/config-loader';
+
+export function registerConfigSource(): void {
+  registerCoreConfigSource(async (root, options): Promise<ConfigSourceOverrides> => {
+    const { overrides } = await loadNextConfig(root, options);
+    return overrides;
+  });
+}

package/src/compat/register/css-extras.ts

@@ -0,0 +1,120 @@
+// CSS-extras registration (COMPAT).
+//
+// Wires the compat CSS features into core:
+//
+//   1. Sass/scss -> the CssExtensions registry. src/css.ts reads getCssExtensions() at its build sites:
+//      bundleCssChunk / buildGlobalCss add the sass chunk plugins and the `.scss`/`.sass` loader entries
+//      so the sass onLoad fires; registerCssRuntime and cssModuleClientPlugin consult resolveCssModule /
+//      loadCssModuleForClient for `*.module.{scss,sass}` before falling back to the empty-module default.
+//
+//   2. Sass loaders are also composed onto the JS bundle esbuild seams (client + server) as a safety net,
+//      so a `.scss` reachable through the JS graph resolves too. COMPOSED, not clobbered: the live plugin
+//      factories are read first and the sass module-loader appended. register-actions sets
+//      clientEsbuildPlugins wholesale, so this MUST run after it - and does, being later in register.ts.
+//
+//   3. useServerInsertedHTML, the CSP nonce and inline-CSS ship as standalone helpers consumed by the
+//      render layer / next-navigation re-export.
+//
+// Gated on next-compat: a pure-core or react-only app keeps every no-op default and never loads the sass
+// module.
+
+import type { Plugin } from 'esbuild';
+import type { ResolvedConfig } from '../../config';
+import {
+  getBundlerExtensions,
+  setBundlerExtensions,
+  setCssExtensions,
+} from '../../extensions';
+import { nextCompatEnabled } from '../../render/hooks';
+import {
+  sassChunkPlugin,
+  sassLoadCssModuleForClient,
+  sassResolveCssModule,
+} from '../css/sass-plugin';
+import { isSassFile, isSassModuleFile, sassModuleMapping } from '../css/sass';
+import {
+  nextCssLoadModuleForClient,
+  nextCssModuleChunkPlugin,
+  nextCssResolveModule,
+} from '../css/modules';
+import { nextPlanRouteCssChunks } from '../css/chunking';
+import { inlineCssStylesheets } from '../css/inline-css';
+
+export function registerCssExtrasExtensions(config: ResolvedConfig): void {
+  if (!nextCompatEnabled(config)) return;
+
+  // (1) CSS-chunk + module-map registry consumed by src/css.ts. The two entries
+  // the route scanner needs (extraCssExtensions, resolveCssDependency) plus the
+  // source materialization are boot facts — register-boot.ts owns them.
+  const resolveNextCssModule = nextCssResolveModule(config);
+  const loadNextCssModuleForClient = nextCssLoadModuleForClient(config);
+  const resolveSassCssModule = sassResolveCssModule(config);
+  const loadSassCssModuleForClient = sassLoadCssModuleForClient(config);
+  setCssExtensions({
+    deferRootNotFoundCss: () => true,
+    inlineStylesheets: inlineCssStylesheets,
+    cssChunkPlugins: () => [nextCssModuleChunkPlugin(config), sassChunkPlugin(config)],
+    resolveCssModule: file => resolveNextCssModule(file) ?? resolveSassCssModule(file),
+    loadCssModuleForClient: file =>
+      loadNextCssModuleForClient(file) ?? loadSassCssModuleForClient(file),
+    planRouteCssChunks: nextPlanRouteCssChunks,
+  });
+
+  // (2) Compose the sass module-loader onto the JS bundle esbuild seams.
+  const current = getBundlerExtensions();
+  const priorClient = current.clientEsbuildPlugins;
+  const priorServer = current.serverEsbuildPlugins;
+  setBundlerExtensions({
+    clientEsbuildPlugins: (cfg: ResolvedConfig): Plugin[] => [
+      ...priorClient(cfg),
+      sassModuleLoaderPlugin(cfg),
+    ],
+    serverEsbuildPlugins: (cfg: ResolvedConfig, opts?): Plugin[] => [
+      ...priorServer(cfg, opts),
+      nextCssServerModuleLoaderPlugin(cfg),
+      sassModuleLoaderPlugin(cfg),
+    ],
+  });
+}
+
+function nextCssServerModuleLoaderPlugin(config: ResolvedConfig): Plugin {
+  const loadModule = nextCssLoadModuleForClient(config);
+  return {
+    name: 'pnext-compat-server-css-module',
+    setup(build) {
+      build.onLoad({ filter: /\.module\.css$/ }, ({ path: file }) => {
+        const contents = loadModule(file);
+        return contents ? { contents, loader: 'js' } : null;
+      });
+    },
+  };
+}
+
+/**
+ * esbuild onLoad for a `.scss`/`.sass` reached through a JS graph: a
+ * `*.module.*` import evaluates to its class map, a global import to an empty
+ * side-effect module (its bytes ship via the CSS chunk, not the JS bundle).
+ * Mirrors core's `cssModuleClientPlugin` for the sass extensions.
+ */
+function sassModuleLoaderPlugin(config: ResolvedConfig): Plugin {
+  return {
+    name: 'pnext-compat-sass-module',
+    setup(build) {
+      build.onLoad({ filter: /\.(?:scss|sass)$/ }, ({ path: file }) => {
+        if (!isSassFile(file)) return null;
+        const contents = isSassModuleFile(file)
+          ? `export default ${JSON.stringify(sassModuleMapping(file, config.root, sassIncludePathsFor(config)))};`
+          : 'export default undefined;';
+        return { contents, loader: 'js' };
+      });
+    },
+  };
+}
+
+// Local include-paths read kept here to avoid importing sass-plugin internals;
+// the JS-graph loader rarely needs includePaths (module maps resolve from the
+// file itself), so an empty list is acceptable — the CSS-chunk plugin
+// (sass-plugin.ts) threads the real sassOptions.includePaths.
+function sassIncludePathsFor(_config: ResolvedConfig): string[] {
+  return [];
+}

package/src/compat/register/edge-runtime.ts

@@ -0,0 +1,6 @@
+import { setRuntimeExtensions } from '../../extensions';
+import { withEdgeRuntime } from '../edge-runtime';
+
+export function registerEdgeRuntimeExtensions(): void {
+  setRuntimeExtensions({ withEdgeRuntime });
+}

package/src/compat/register/errors.ts

@@ -0,0 +1,46 @@
+// Error/404 pipeline registration (COMPAT).
+//
+// Wires the Next error-boundary behaviors into the core render/routing registries at the gated bootstrap
+// seam: serializeError gets the digest protocol plus prod message redaction, and routeConventions gets
+// global-error / global-not-found boundary discovery. A pure-core app registers none of these, keeping
+// the compact core error UI and no digest/redaction.
+
+import type { ResolvedConfig } from '../../config';
+import { setRenderExtensions } from '../../extensions';
+import { nextCompatEnabled } from '../../compat';
+import {
+  serializeBoundaryError,
+  wrapThrownValue,
+  formatErrorLog,
+} from '../lifecycle/error-serialize';
+import {
+  httpAccessFallbackUi,
+  defaultGlobalErrorUi,
+  globalErrorReportScript,
+} from '../lifecycle/error-ui';
+import { getNextConfig } from '../next/config-loader';
+
+// global-error / global-not-found are CORE document conventions (discovered by
+// src/routing/routes.ts findGlobalError + src/render renderGlobalNotFoundResponse);
+// compat only skins the Next-pixel-exact default UI strings/markup and the
+// digest protocol here. forbidden/unauthorized stay compat conventions
+// (registered in register-routing.ts).
+export function registerErrorExtensions(config: ResolvedConfig): void {
+  if (!nextCompatEnabled(config)) return;
+
+  setRenderExtensions({
+    serializeError: serializeBoundaryError,
+    httpAccessFallbackUi,
+    defaultGlobalErrorUi,
+    globalErrorReportScript,
+    wrapThrownValue,
+    formatErrorLog,
+    // Read lazily per call: next.config loads after registration.
+    globalNotFoundEnabled: () => {
+      const experimental = getNextConfig().experimental as
+        | { globalNotFound?: boolean }
+        | undefined;
+      return experimental?.globalNotFound === true;
+    },
+  });
+}

package/src/compat/register/export.ts

@@ -0,0 +1,23 @@
+import { nextCompatEnabled } from '../../compat';
+import { onExtensionHostReset, registerBuildCompleteHooks } from '../../extensions';
+import type { ResolvedConfig } from '../../config';
+import { emitMetadataRouteArtifacts } from '../metadata-route-artifacts';
+import { emitStaticExport } from '../export';
+import { emitCustomServerShim } from '../next/custom-server';
+
+let registered = false;
+// Host-scoped guard: a fresh host must be registered into again.
+onExtensionHostReset(() => (registered = false));
+
+export function registerExportExtensions(config: ResolvedConfig): void {
+  if (registered) return;
+  if (!nextCompatEnabled(config)) return;
+  registered = true;
+
+  registerBuildCompleteHooks(async ctx => {
+    if (!nextCompatEnabled(ctx.config)) return;
+    await emitStaticExport(ctx);
+    await emitMetadataRouteArtifacts(ctx);
+    await emitCustomServerShim(ctx.config);
+  });
+}

package/src/compat/register/font.ts

@@ -0,0 +1,36 @@
+// next/font extension registration (COMPAT - may import core freely).
+//
+// Wires next/font preload delivery into core: requestExtensions.responseFinalizers gets the `Link`
+// response header carrying the font preloads collected during the render.
+//
+// The font runtime stashes the render's preloadable font links on the request work unit. The registered
+// finalizer, which runs before the first flush inside the same work unit, reads them back and emits a
+// single `Link` header - matching Next, which delivers font preloads via a response header rather than
+// HTML link tags.
+//
+// Registration is idempotent and also happens lazily on the first font-collection scope, so it is safe
+// to call in a pure-core app and works before the orchestrator wires it in.
+
+import type { ResolvedConfig } from '../../config';
+import {
+  registerClientSourceTransforms,
+  registerServerSourceTransforms,
+  withSniff,
+} from '../../extensions';
+import { rewriteNextFontSource } from '../index';
+import { registerFontFinalizerOnce } from '../next/font/runtime';
+
+const fontSourceTransformRoots = new Set<string>();
+
+export function registerFontExtensions(config: ResolvedConfig): void {
+  registerFontFinalizerOnce();
+  if (!config.compat?.next || fontSourceTransformRoots.has(config.root)) return;
+  fontSourceTransformRoots.add(config.root);
+  const sniff = ['next/font', 'next/root-params'];
+  registerServerSourceTransforms(
+    withSniff(sniff, (source, file) => rewriteNextFontSource(source, file, 'server', config.root)),
+  );
+  registerClientSourceTransforms(
+    withSniff(sniff, (source, file) => rewriteNextFontSource(source, file, 'client', config.root)),
+  );
+}

package/src/compat/register/hooks.ts

@@ -0,0 +1,34 @@
+// ---------------------------------------------------------------------------
+// Registration seam for the next/navigation router hooks (COMPAT).
+//
+// The hooks themselves (useSelectedLayoutSegment(s), usePathname,
+// useSearchParams, useParams) need no runtime registration: compat/index.ts maps
+// `next/navigation` to compat/next/{navigation,client-navigation}.ts, and the
+// per-layout segment scope is installed by the core renderer (render/slots.ts +
+// render/renderer.ts applyLayouts), gated on next-compat.
+//
+// The ONE thing that must be wired centrally is canonical-URL tracking for
+// usePathname()/useSearchParams() on rewrites. After a same-origin rewrite the
+// downstream render sees the DESTINATION URL, so the hooks need the original
+// (as-requested) URL recorded on the work unit. The rewrite feeder already calls
+// recordRewrite(from, to) (src/proxy.ts proxyRewriteObserver + register-proxy.ts;
+// config rewrites via register-proxy). The orchestrator should also call
+// recordCanonicalUrl(from) at the SAME site(s) so the canonical URL is stashed
+// before the request URL is replaced with the destination.
+//
+// Reason it is not wired here: the rewrite observer slot
+// (setProxyRewriteObserver) is single-valued and owned by register-proxy.ts.
+// registerNavigationHooks() is provided so register.ts can call it in one place;
+// today it only re-exports the canonical setter for the proxy wiring.
+// ---------------------------------------------------------------------------
+
+export { recordCanonicalUrl, canonicalUrlHref } from '../next/canonical-url';
+
+/**
+ * Placeholder registration entry point kept for symmetry with the other register-<x> modules. The router
+ * hooks are wired declaratively (module map + renderer seam); the only imperative wiring
+ * (recordCanonicalUrl on rewrites) belongs in the proxy-rewrite observer.
+ */
+export function registerNavigationHooks(): void {
+  // No-op: nothing to install at runtime beyond the declarative wiring above.
+}

package/src/compat/register/image.ts

@@ -0,0 +1,133 @@
+// next/image extension registration (COMPAT - may import core freely).
+//
+// Wires the next/image pipeline into core: requestExtensions.interceptors gets the /_next/image optimizer
+// endpoint, and buildExtensions.steps gets images-manifest.json emission. Safe to call in a pure-core
+// app: the interceptor and build step no-op unless compat.next is enabled.
+
+import path from 'node:path';
+import { mkdir, writeFile } from 'node:fs/promises';
+import type { ResolvedConfig } from '../../config';
+import { nextCompatEnabled } from '../../compat';
+import {
+  registerBuildCompleteHooks,
+  registerBuildSteps,
+  registerRequestInterceptors,
+  type BuildStepContext,
+  type RequestInterceptor,
+} from '../../extensions';
+import { getImagesConfig, type ResolvedImagesConfig } from '../next/image/config';
+import { isImageOptimizerRequest, serveImageOptimizer } from '../next/image/optimizer';
+import { manifestLocalPatterns } from '../next/image/patterns';
+import { getDocumentScriptExtensions, setDocumentScriptExtensions } from '../../render/hooks';
+import { setWorkUnitRoute } from '../../request/context';
+
+export function registerImageExtensions(config: ResolvedConfig): void {
+  globalThis.__PNEXT_IMAGE_CONFIG__ = getImagesConfig();
+  registerRequestInterceptors(imageOptimizerInterceptor);
+  registerBuildSteps(writeImagesManifestStep);
+  registerBuildCompleteHooks(async ctx => {
+    if (nextCompatEnabled(ctx.config)) await mirrorStaticMedia(ctx.config);
+  });
+
+  if (nextCompatEnabled(config)) {
+    const previousHeadTags = getDocumentScriptExtensions().documentHeadTags;
+    setDocumentScriptExtensions({
+      documentHeadTags: (cfg, ctx) =>
+        `${previousHeadTags?.(cfg, ctx) ?? ''}${PLACEHOLDER_SCRIPT_TAG}`,
+    });
+  }
+}
+
+// Placeholder removal for images that never hydrate (a next/image rendered by a server component has no
+// island, so no ClientImage effect runs). The server img carries `data-nimg-ph` = the loaded,
+// placeholder-free style; once it settles we decode() then restore it, matching ClientImage's
+// handleLoading. Images inside hydrating islands are skipped - their ClientImage owns the lifecycle.
+//
+// Fully self-contained and defensive: a single try/catch so it can never throw into the document, and
+// per-element load/error handlers only (no global capture listener) so it cannot interfere with
+// hydration. Binds on DOMContentLoaded - placeholder imgs live in the body, below this head script - and
+// also settles images already complete by then.
+//
+// Conflict-free with ClientImage: the loaded style is re-read from the live `data-nimg-ph` attribute
+// INSIDE the post-decode callback, not at bind time. A hydrating route's ClientImage vdom carries no
+// `data-nimg-ph`, so preact's hydration strips the SSR attribute; by the time this callback fires the
+// attribute is gone on any hydrated image, the check bails, and ClientImage stays the sole owner.
+const PLACEHOLDER_SCRIPT_TAG = `<script>(function(){try{function b(){var l=document.querySelectorAll("img[data-nimg-ph]");for(var i=0;i<l.length;i++){(function(img){if(img.closest("[data-pnext-client]"))return;var done=false;function r(){if(done)return;done=true;("decode"in img?img.decode():Promise.resolve()).catch(function(){}).then(function(){var t=img.getAttribute("data-nimg-ph");if(t==null||!img.isConnected)return;img.style.cssText=t;img.removeAttribute("data-nimg-ph")})}if(img.complete&&img.naturalWidth>0)r();else{img.addEventListener("load",r);img.addEventListener("error",r)}})(l[i])}}if(document.readyState==="loading")document.addEventListener("DOMContentLoaded",b);else b()}catch(e){}})();</script>`;
+
+declare global {
+  var __PNEXT_IMAGE_CONFIG__: ResolvedImagesConfig | undefined;
+}
+
+const imageOptimizerInterceptor: RequestInterceptor = async (request, ctx) => {
+  const config = ctx.config;
+  if (!nextCompatEnabled(config)) return undefined;
+  const url = new URL(request.url);
+  const images = getImagesConfig();
+  if (!isImageOptimizerRequest(url, images)) return undefined;
+  if (request.method !== 'GET' && request.method !== 'HEAD') return undefined;
+  // Optimizer responses own their headers outright — classify as a static
+  // asset so the app-router finalizers (Vary token merge, x-nextjs-* stamps)
+  // leave them untouched. Next serves /_next/image outside the router too.
+  setWorkUnitRoute('static-asset');
+  return serveImageOptimizer(request, config);
+};
+
+// Next-compatible images-manifest.json (.next/): the qualities/localpatterns
+// e2e suites read it in production to assert the resolved images config.
+async function writeImagesManifestStep(ctx: BuildStepContext): Promise<void> {
+  const config = ctx.config;
+  if (!nextCompatEnabled(config)) return;
+  const images = getImagesConfig();
+
+  // normalizeLocalPatterns already appends the internal media patterns when
+  // localPatterns is configured, so manifest and runtime share one source.
+  const localPatterns = manifestLocalPatterns(images.localPatterns);
+
+  const manifest = {
+    version: 1,
+    images: {
+      contentDispositionType: images.contentDispositionType,
+      contentSecurityPolicy: images.contentSecurityPolicy,
+      dangerouslyAllowLocalIP: images.dangerouslyAllowLocalIP,
+      dangerouslyAllowSVG: images.dangerouslyAllowSVG,
+      deviceSizes: images.deviceSizes,
+      disableStaticImages: images.disableStaticImages,
+      domains: images.domains,
+      formats: images.formats,
+      imageSizes: images.imageSizes,
+      loader: images.loader,
+      loaderFile: images.loaderFile,
+      remotePatterns: images.remotePatterns,
+      localPatterns,
+      maximumRedirects: images.maximumRedirects,
+      maximumResponseBody: images.maximumResponseBody,
+      minimumCacheTTL: images.minimumCacheTTL,
+      path: images.path,
+      qualities: images.qualities,
+      sizes: [...images.deviceSizes, ...images.imageSizes],
+      unoptimized: images.unoptimized,
+      customCacheHandler: images.customCacheHandler,
+    },
+  };
+
+  const outDir = path.join(config.root, '.next');
+  await mkdir(outDir, { recursive: true });
+  await writeFile(path.join(outDir, 'images-manifest.json'), JSON.stringify(manifest, null, 2));
+}
+
+// Tooling (and Next's e2e suites) discover fingerprinted static-import images
+// by scanning <distDir>/static/media; pnext emits them under
+// outPath/public/_next/static/media. Mirror them into .next so both layouts
+// hold the same files.
+async function mirrorStaticMedia(config: ResolvedConfig): Promise<void> {
+  const { cp } = await import('node:fs/promises');
+  for (const dir of ['media', 'immutable/media']) {
+    const source = path.join(config.outPath, 'public', '_next', 'static', dir);
+    const target = path.join(config.root, '.next', 'static', dir);
+    try {
+      await cp(source, target, { recursive: true, force: true });
+    } catch {
+      // no static media emitted for this build
+    }
+  }
+}

package/src/compat/register/index.ts

@@ -0,0 +1,111 @@
+// Compat registration entry point (COMPAT - may import core freely).
+//
+// registerCompatExtensions(config) is invoked exactly once, from the single core seam
+// (src/compat-bootstrap.ts), when compat is enabled. It fans out to the per-domain sub-registrars, each
+// in its OWN file. Each imports the real compat implementations and assigns them into the core
+// registries in src/extensions.ts.
+//
+// Importing this module IS the expensive part of compat (the whole implementation graph), so the handful
+// of facts core needs before its first compile live in ./register-boot, which the boot tier loads on its
+// own. This file re-runs that registrar (idempotent) so calling it alone still yields a fully wired
+// compat layer.
+
+import type { ResolvedConfig } from '../../config';
+import { registerCompatBootExtensions } from './boot';
+import type * as BuildTier from './build-tier';
+import { registerCacheExtensions } from './cache';
+import { registerActionExtensions } from './actions';
+import { registerRenderExtensions } from './render';
+import { registerProxyExtensions } from './proxy';
+import { registerConfigSource } from './config';
+import {
+  registerProtocolExtensions,
+  registerProtocolRequestValidation,
+} from './protocol';
+import { registerLifecycleExtensions } from './lifecycle';
+import { registerImageExtensions } from './image';
+import { registerErrorExtensions } from './errors';
+import { registerFontExtensions } from './font';
+import { registerStaticImageExtensions } from './static-image';
+import { registerUseCacheExtensions } from './usecache';
+import { registerClientErrorExtensions } from './client-errors';
+import { registerPprExtensions } from './ppr';
+import { registerMdxExtensions } from './mdx';
+import { registerOtelExtensions, registerOtelRootInterceptor } from './otel';
+import { registerInstrumentationClientExtensions } from './instrumentation-client';
+import { registerMiscExtensions } from './misc';
+import { registerCssExtrasExtensions } from './css-extras';
+import { registerSegmentExtensions } from './segment';
+import { registerBundlerExtensions } from './bundler';
+import { registerPagesApiExtensions } from './pages-api';
+import { registerEdgeRuntimeExtensions } from './edge-runtime';
+
+export interface RegisterCompatOptions {
+  /**
+   * Serving only (the dev server). Skips the build-only domains — nothing on a
+   * request path reads what they register — so their module graphs never load.
+   */
+  serve?: boolean;
+}
+
+export async function registerCompatExtensions(
+  config: ResolvedConfig,
+  options: RegisterCompatOptions = {},
+): Promise<void> {
+  // Loaded up front so the calls below stay in their original order; skipped
+  // outright when only serving (see RegisterCompatOptions.serve).
+  const build: typeof BuildTier | undefined = options.serve
+    ? undefined
+    : await import('./build-tier');
+  // Route conventions, page/CSS extensions, module aliases, proxy names and the
+  // lifecycle init hooks — already done when the boot tier ran first.
+  registerCompatBootExtensions(config);
+  build?.registerBuildCompatExtensions();
+  registerConfigSource();
+  // The otel ROOT-span interceptor must run before every short-circuiting
+  // interceptor (segment prefetch, RSC protocol, action dispatch) so those
+  // responses are traced too; the rest of otel registers last (below).
+  registerOtelRootInterceptor(config);
+  // Protocol validation next: an invalid next-router-state-tree must 500 before
+  // the segment/action interceptors answer the request.
+  registerProtocolRequestValidation(config);
+  // Typed-routes typegen and typecheck run before structural validation so a type error surfaces ahead of
+  // runtime checks, matching `next build`, which runs tsc before its own validations. The typecheck only
+  // covers .ts/.tsx pages/layouts/handlers via the generated validator, so JS-only fixtures still fall
+  // through to the structural validation below with their runtime error message.
+  build?.registerTypedRoutesExtensions(config);
+  // Build validation fails fast before the remaining build steps run.
+  build?.registerValidationExtensions(config);
+  registerCacheExtensions(config);
+  // Before actions: the /_tree prefetch responder must intercept ahead of the
+  // action dispatch interceptor.
+  registerSegmentExtensions(config);
+  registerActionExtensions(config);
+  registerPagesApiExtensions(config);
+  registerEdgeRuntimeExtensions();
+  registerRenderExtensions(config);
+  registerProxyExtensions(config);
+  registerProtocolExtensions(config);
+  registerLifecycleExtensions(config);
+  registerImageExtensions(config);
+  registerErrorExtensions(config);
+  registerFontExtensions(config);
+  build?.registerMiddlewareExtensions();
+  build?.registerExportExtensions(config);
+  registerStaticImageExtensions();
+  registerUseCacheExtensions(config);
+  registerClientErrorExtensions(config);
+  registerPprExtensions(config);
+  registerMiscExtensions(config);
+  registerBundlerExtensions(config);
+  // After registerActionExtensions: composes (not clobbers) clientEsbuildPlugins.
+  registerCssExtrasExtensions(config);
+  // MDX last: it composes (not clobbers) clientEsbuildPlugins, so it must
+  // capture every previously-registered plugin factory.
+  registerMdxExtensions(config);
+  // Otel after everything: its route re-stamp interceptor must observe the
+  // post-rewrite request (the root span opens in the EARLY interceptor above).
+  registerOtelExtensions(config);
+  // After otel: composes (not clobbers) the documentHeadTags extension.
+  registerInstrumentationClientExtensions(config);
+}

package/src/compat/register/instrumentation-client.ts

@@ -0,0 +1,35 @@
+// instrumentation-client registration (COMPAT).
+//
+// Wires the client instrumentation emulation onto the core seams:
+//   - a BUILD STEP bundles the app's instrumentation-client.(ts|js), plus next.config
+//     `instrumentationClientInject` entries in order, into `<out>/public/assets/instrumentation-client.js`.
+//     Steps run before prerendering, so statically generated documents carry the tag too.
+//   - documentHeadTags injects the `<script type="module">` loader tag - COMPOSED with whatever a previous
+//     registrar installed, since setDocumentScriptExtensions overwrites per key. The orchestrator calls
+//     this AFTER registerOtelExtensions.
+//
+// The router-side hook is surfaced through the `window.__PNEXT_ON_ROUTER_TRANSITION_START__` global the
+// bundle registers; the client router calls it at the start of push/replace/traverse navigations.
+
+import type { ResolvedConfig } from '../../config';
+import { registerBuildSteps } from '../../extensions';
+import { getDocumentScriptExtensions, setDocumentScriptExtensions } from '../../render/hooks';
+import { nextCompatEnabled } from '../index';
+import {
+  buildInstrumentationClient,
+  instrumentationClientHeadTag,
+} from '../lifecycle/instrumentation-client';
+
+export function registerInstrumentationClientExtensions(config: ResolvedConfig): void {
+  if (!nextCompatEnabled(config)) return;
+
+  registerBuildSteps(async ctx => {
+    await buildInstrumentationClient(ctx.config);
+  });
+
+  const previousHeadTags = getDocumentScriptExtensions().documentHeadTags;
+  setDocumentScriptExtensions({
+    documentHeadTags: (cfg, ctx) =>
+      `${previousHeadTags?.(cfg, ctx) ?? ''}${instrumentationClientHeadTag(cfg)}`,
+  });
+}