@wular/pnext 0.0.1

package/src/compat/register/lifecycle.ts

@@ -0,0 +1,86 @@
+// Request-lifecycle extension registration (COMPAT).
+//
+// Wires after()/onRequestError/instrumentation/testmode onto the core seams:
+//   - initHooks (build + start): load instrumentation.ts and run its register() once; install the
+//     testmode fetch patch once (a no-op until a request carries Next-Test-* headers).
+//   - RequestExtensions.onRequestError: the error funnel (classify control-flow, dedupe, forward).
+//   - a request interceptor: await the instrumentation register() gate so async register() completes
+//     before the first request is served, and activate the testmode proxy for Next-Test-* requests.
+//
+// after() itself needs no registration - it is exported from the next/server alias and builds directly on
+// the core work-unit after-queue.
+//
+// Split across the two registration tiers: the hooks core runs at server start register eagerly via
+// registerLifecycleBootHooks(), while the request interceptor registers with the rest of the graph so its
+// position in the interceptor chain is unchanged.
+
+import type { ResolvedConfig } from '../../config';
+import {
+  registerInitHooks,
+  registerRequestInterceptors,
+  setRequestExtensions,
+  type RequestInterceptor,
+} from '../../extensions';
+import { nextCompatEnabled } from '../index';
+import { getNextConfig } from '../next/config-loader';
+import { instrumentationReady, loadInstrumentation } from '../lifecycle/instrumentation';
+import {
+  installUnhandledRejectionGuard,
+  reportRequestErrorToUser,
+} from '../lifecycle/error-funnel';
+import { activateTestProxy, installTestProxyFetch } from '../lifecycle/testmode';
+import { recordRequestPath } from '../lifecycle/after-scope';
+import { installNodeConsoleFormat } from '../lifecycle/node-console';
+
+/** experimental.testProxy from the loaded next.config. */
+function testProxyEnabled(): boolean {
+  const experimental = getNextConfig().experimental as { testProxy?: boolean } | undefined;
+  return experimental?.testProxy === true;
+}
+
+/** Boot tier: everything that must be installed before the server starts. */
+export function registerLifecycleBootHooks(config: ResolvedConfig): void {
+  if (!nextCompatEnabled(config)) return;
+  installNodeConsoleFormat();
+
+  // The user's onRequestError hook (once instrumentation has loaded) receives
+  // every real request error; control-flow errors are filtered in the funnel.
+  setRequestExtensions({ onRequestError: reportRequestErrorToUser });
+
+  // Keep the server alive when an SSR error escapes as an unhandled rejection
+  // (a client component that throws during server render — preact resolves the
+  // string pass to '' and floats the rejection). Without this the process
+  // crashes and every later request in the shared harness server fails.
+  installUnhandledRejectionGuard();
+
+  // Load instrumentation and patch fetch at server start. The fetch patch is a no-op until a request
+  // activates the test proxy. Instrumentation register() must NOT run during a build: Next only detects
+  // the file at build and runs register() at server boot, so build prerenders see a noop tracer - a live
+  // TracerProvider at build would bake real span ids into the static shell and 'use cache' entries.
+  registerInitHooks((cfg, context) => {
+    if (!context.build) loadInstrumentation(cfg);
+    installTestProxyFetch();
+  });
+}
+
+export function registerLifecycleExtensions(config: ResolvedConfig): void {
+  if (!nextCompatEnabled(config)) return;
+
+  const lifecycleInterceptor: RequestInterceptor = async request => {
+    // Block the very first requests until instrumentation register() settles.
+    await instrumentationReady();
+    // Remember the route pathname so an after() callback that runs detached
+    // (after a page render) can name the route in its "used ... inside after()"
+    // error, matching Next's message.
+    try {
+      recordRequestPath(new URL(request.url).pathname);
+    } catch {
+      // ignore malformed URLs
+    }
+    // Route this request's outgoing fetch through the test proxy when it carries
+    // Next-Test-* headers (gated on experimental.testProxy in next.config).
+    if (testProxyEnabled()) activateTestProxy(request.headers);
+    return undefined;
+  };
+  registerRequestInterceptors(lifecycleInterceptor);
+}

package/src/compat/register/mdx.ts

@@ -0,0 +1,48 @@
+// MDX extension registration (COMPAT).
+//
+// Wires the MDX esbuild plugin into the client and server build graphs so `.mdx`/`.md` modules compile
+// via the JS pipeline. Two integration points:
+//
+// 1. BUNDLER: the MDX plugin is appended to clientEsbuildPlugins and serverEsbuildPlugins.
+//    `setBundlerExtensions` REPLACES the factory and register-actions already sets clientEsbuildPlugins,
+//    so this COMPOSES with any previously-registered factory rather than clobbering it. Note that
+//    `serverEsbuildPlugins` is defined but not yet applied at every server compile site, so until that
+//    seam is threaded MDX compiles in the CLIENT graph only; the server factory is registered here so it
+//    activates for free once it lands.
+//
+// 2. PAGE EXTENSIONS: core derives its page/convention extension list lazily from a base plus whatever
+//    compat registers, so the route scanner discovers `page.mdx` and top-level `.mdx` pages once `mdx`/
+//    `md` are registered. `pageExtensions` in next.config (as set by @next/mdx's createMDX) is the single
+//    source of truth: when the app sets it, exactly the listed extensions core does not already carry are
+//    registered, so `.mdx` routes only when the app opted in - matching Next. When none is configured,
+//    nothing extra is registered.
+//
+//    The seam is additive-only, so core's base `mjs` cannot be removed even if a configured
+//    `pageExtensions` omits it - a documented, harmless divergence. The route scanner needs these
+//    extensions at boot, so the registration itself lives in register-boot.ts; only the compilation
+//    wiring is here.
+
+import type { Plugin } from 'esbuild';
+import type { ResolvedConfig } from '../../config';
+import { getBundlerExtensions, setBundlerExtensions } from '../../extensions';
+import { nextCompatEnabled } from '../../render/hooks';
+import { mdxEsbuildPlugin } from '../mdx/plugin';
+
+export function registerMdxExtensions(config: ResolvedConfig): void {
+  if (!nextCompatEnabled(config)) return;
+
+  const existing = getBundlerExtensions();
+  const priorClient = existing.clientEsbuildPlugins;
+  const priorServer = existing.serverEsbuildPlugins;
+
+  setBundlerExtensions({
+    clientEsbuildPlugins: (cfg: ResolvedConfig): Plugin[] => [
+      ...priorClient(cfg),
+      mdxEsbuildPlugin(config.root),
+    ],
+    serverEsbuildPlugins: (cfg: ResolvedConfig, opts?): Plugin[] => [
+      ...priorServer(cfg, opts),
+      mdxEsbuildPlugin(config.root),
+    ],
+  });
+}

package/src/compat/register/middleware.ts

@@ -0,0 +1,36 @@
+// Middleware extension registration (COMPAT - may import core freely). Registers the build step that
+// emits the Next-shaped middleware manifests (middleware-manifest.json +
+// functions-config-manifest.json). The middleware runtime itself is the existing proxy machinery; this
+// module owns only the build-time manifest output.
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { registerBuildSteps } from '../../extensions';
+import { nextCompatEnabled } from '../../compat';
+import { findProxyFile, proxyExternalLoadTarget } from '../../proxy';
+import { devServerModuleHref } from '../../dev/imports';
+import { toPosixPath } from '../../utils/fs';
+import type { RouteManifestEntry } from '../../types';
+import { writeMiddlewareManifests } from '../middleware/manifest';
+
+export function registerMiddlewareExtensions(): void {
+  registerBuildSteps(async ({ config, routes }) => {
+    if (!nextCompatEnabled(config)) return;
+    const file = findProxyFile(config);
+    let relative: string | undefined;
+    if (file) {
+      // Must name the SAME artifact buildProxyModule emits (the build copies it to
+      // .next/server/middleware.js), so every option that keys the compile profile is spelled out here - a
+      // divergence would be a second full compile of the proxy AND a manifest entrypoint pointing at a copy
+      // the build never emitted. Same href, so this joins that build's promise.
+      const href = await devServerModuleHref(config, file, 'prod', {
+        conditionTarget: 'edge',
+        externalLoadTarget: proxyExternalLoadTarget(file),
+        reactServerLayer: true,
+      });
+      relative = toPosixPath(path.relative(config.outPath, fileURLToPath(href)));
+    }
+    // Edge-runtime segments produce manifest entries even with no middleware.
+    await writeMiddlewareManifests(config, relative, routes as RouteManifestEntry[]);
+  });
+}

package/src/compat/register/misc.ts

@@ -0,0 +1,44 @@
+// Misc long-tail compat cluster registration (COMPAT).
+//
+// The misc singletons in this cluster (temporary-references, actions-streaming) hook the server-action
+// return path directly through the shared action endpoint, and their client counterparts live inline in
+// the action-client runtime bundle - there is no core registry seam to populate for them. The rest of the
+// cluster is satisfied by existing core/compat behavior, so this registrar is a stable no-op hook.
+//
+// Kept as an explicit registrar rather than nothing, so future misc features that DO need a registry
+// have an owned place to register without touching another file.
+
+import type { ResolvedConfig } from '../../config';
+import { taintObjectReference } from '../../utils/serialize';
+import { getNextConfig } from '../next/config-loader';
+
+// Next's `experimental.taint` message for a `process.env` reference reaching a
+// client component (asserted verbatim by test/e2e/app-dir/taint in dev; prod
+// sees the redacted React #441 text via the normal boundary error path).
+const PROCESS_ENV_TAINT_MESSAGE =
+  'Do not pass process.env to Client Components since it will leak sensitive data';
+
+// Prod redacts every RSC serialization error to React's minified #441 text
+// (test/e2e/app-dir/taint asserts this verbatim for a production build).
+const REDACTED_RSC_ERROR_MESSAGE =
+  'Minified React error #441; visit https://react.dev/errors/441 for the full message or use the non-minified dev environment for full errors and additional helpful warnings.';
+
+export function registerMiscExtensions(_config: ResolvedConfig): void {
+  // No registry wiring required for the current misc cluster; behavior is
+  // activated via direct imports in the action endpoint + client runtime.
+  registerTaintedReferences();
+}
+
+/**
+ * `experimental.taint`: React's taint APIs do not exist under preact, so the client-props serializer
+ * enforces the same contract by identity - registering `process.env` makes any client-component prop that
+ * IS that object throw.
+ */
+function registerTaintedReferences(): void {
+  const experimental = getNextConfig().experimental as { taint?: unknown } | undefined;
+  if (experimental?.taint !== true) return;
+  taintObjectReference(
+    { dev: PROCESS_ENV_TAINT_MESSAGE, prod: REDACTED_RSC_ERROR_MESSAGE },
+    process.env,
+  );
+}

package/src/compat/register/otel.ts

@@ -0,0 +1,288 @@
+// OpenTelemetry extension registration (COMPAT).
+//
+// Wires the Next span taxonomy onto core seams without any core edit:
+//   - initHooks (build + start): remember the app root (for @opentelemetry/api resolution) and install
+//     the AppRender.fetch span wrapper.
+//   - requestExtensions.interceptors: open the root BaseServer.handleRequest span (extracting an incoming
+//     traceparent) and set its `next.route`/`http.route` from the matched route pattern. Runs late so it
+//     observes the request after action-dispatch and rewrites.
+//   - requestExtensions.responseFinalizers: close the root span with the final `http.status_code`,
+//     pre-flush.
+//   - requestExtensions.onRequestError: mark the root span errored for anything the funnel catches.
+//
+// Child spans are emitted from their own compat call sites. The root span alone satisfies the bulk of the
+// opentelemetry suite. Everything is inert unless next compat is on AND @opentelemetry/api resolves from
+// the app.
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import type { ResolvedConfig } from '../../config';
+import type { RouteManifestEntry } from '../../types';
+import {
+  registerInitHooks,
+  registerRequestInterceptors,
+  registerRequestWarmHooks,
+  registerResponseFinalizers,
+  getRequestExtensions,
+  setRequestExtensions,
+  type RequestInterceptor,
+  type ResponseFinalizer,
+} from '../../extensions';
+import { nextCompatEnabled } from '../index';
+import { getRequestRuntime } from '../../routing/request-runtime';
+import { selectRouteForRequest } from '../../routing/routes';
+import { queueAfterTask } from '../../request/context';
+import {
+  getDocumentScriptExtensions,
+  setRenderSpanExtensions,
+  setDocumentScriptExtensions,
+  setStreamBoundaryExtensions,
+} from '../../render/hooks';
+import { setProxyRunObserver } from '../../proxy';
+import {
+  SPAN_TYPE,
+  emitClientComponentLoadingSpan,
+  emitLeafSpan,
+  emitStartResponseSpan,
+  endRootSpan,
+  endRootSpanIfUnclosed,
+  markRenderSpanError,
+  setOtelAppRoot,
+  setRootSpanRoute,
+  startRootSpan,
+  withChildSpan,
+  withMiddlewareSpan,
+  withPagesApiHandlerSpan,
+  withPagesDataSpan,
+  withRenderBodySpan,
+  withRouteHandlerSpan,
+} from '../otel/tracer';
+import { getOtelApi } from '../otel/api';
+import { installFetchSpan } from '../otel/fetch-span';
+import { clientTraceMetadataTags } from '../otel/client-trace-metadata';
+import { instrumentationReady } from '../lifecycle/instrumentation';
+
+/**
+ * The ROOT-span interceptor. Registered FIRST, before every other sub-registrar, so the
+ * `BaseServer.handleRequest` span is open before any short-circuiting interceptor (segment `_tree`
+ * prefetches, the RSC protocol responder, action dispatch) produces a response - those responses still
+ * flow through the response finalizer, which closes the span. The route attributes are stamped
+ * immediately from the pre-rewrite match; the LATE interceptor re-stamps them after rewrites.
+ */
+export function registerOtelRootInterceptor(config: ResolvedConfig): void {
+  if (!nextCompatEnabled(config)) return;
+  setOtelAppRoot(config.root);
+
+  const rootInterceptor: RequestInterceptor = async request => {
+    try {
+      // Instrumentation register() installs the app's TracerProvider; opening
+      // the root span before it completes would produce a non-recording span.
+      await instrumentationReady();
+      const url = new URL(request.url);
+      startRootSpan({
+        method: request.method.toUpperCase(),
+        target: url.pathname + url.search,
+        rsc: request.headers.get('rsc') === '1',
+        headers: request.headers,
+      });
+      stampMatchedRoute(url.pathname);
+      // Safety net for the synchronous-500 error path: core's top-level catch
+      // returns a bare 500 WITHOUT running responseFinalizers, so the finalizer
+      // never closes the root span there. The work-unit after-queue DOES flush
+      // on that path (flushWorkUnit in the catch), so end the span as 500 from
+      // an after-task. Idempotent: on success paths the finalizer ends it first.
+      queueAfterTask(() => endRootSpanIfUnclosed(500));
+    } catch {
+      // Never let tracing break the request.
+    }
+    return undefined;
+  };
+  registerRequestInterceptors(rootInterceptor);
+  // Resolving @opentelemetry/api out of the app loads the whole package inside this interceptor on
+  // the first request. The result is memoized, so paying it in the dev warm just moves it off that
+  // request.
+  registerRequestWarmHooks(() => void getOtelApi(config.root));
+}
+
+/** Resolve the matched route for `pathname` and stamp it on the root span. */
+function stampMatchedRoute(pathname: string): void {
+  const runtime = getRequestRuntime();
+  if (!runtime) return;
+  const matched = selectRouteForRequest(runtime.routes, pathname, undefined);
+  if (!matched) return;
+  const routeRuntime = matched.route.segmentConfig?.runtime;
+  setRootSpanRoute(routeEntryToDisplay(matched.route), {
+    edge: routeRuntime === 'edge' || routeRuntime === 'experimental-edge',
+    kind: matched.route.kind === 'handler' ? 'handler' : 'page',
+    params: matched.params,
+  });
+}
+
+export function registerOtelExtensions(config: ResolvedConfig): void {
+  if (!nextCompatEnabled(config)) return;
+
+  const appRoot = config.root;
+  setOtelAppRoot(appRoot);
+
+  // Install the fetch span wrapper at server (and build) start, AFTER the cache
+  // fetch-patch has wrapped globalThis.fetch (register order: cache before otel).
+  registerInitHooks(() => {
+    installFetchSpan(appRoot);
+  });
+
+  // Materialized pages wrappers (compat/pages wrapperSource) call this global —
+  // when present — around their getServerSideProps/getStaticProps invocation so
+  // the `Render.<kind>` span lands beside the document render span. A global
+  // (not an import) keeps the generated bundles pnext-agnostic.
+  (
+    globalThis as { __PNEXT_PAGES_DATA_SPAN__?: typeof withPagesDataSpan }
+  ).__PNEXT_PAGES_DATA_SPAN__ = withPagesDataSpan;
+
+  // Render-internal spans (nest under the request root span via the work-unit
+  // ALS the tracer threads): the render-body span (`render route (app)`), the
+  // route-resolution span (`resolve page components`), and cheap leaf
+  // segment-module spans. All inert when no root span is open.
+  setRenderSpanExtensions({
+    withRenderBodySpan: (route, fn) => {
+      const displayRoute = routePatternToDisplay(route);
+      // A materialized pages route renders through the app pipeline, but Next
+      // reports it as the pages-router document render span.
+      if (isPagesCompatRoute(route)) {
+        return withRenderBodySpan(
+          `render route (pages) ${displayRoute}`,
+          displayRoute,
+          fn,
+          SPAN_TYPE.renderDocument,
+        );
+      }
+      return withRenderBodySpan(
+        `render route (app) ${displayRoute}`,
+        displayRoute,
+        fn,
+      );
+    },
+    withFindPageComponentsSpan: (route, fn) => {
+      const entry = routeEntryFor(route);
+      // A materialized pages-API route reports ONLY its Node.runHandler span
+      // (Next's pages-api dispatch has no findPageComponents phase).
+      if (entry?.kind === 'handler' && isPagesCompatEntry(entry)) return fn();
+      const displayRoute = routePatternToDisplay(route);
+      return withChildSpan(
+        'resolve page components',
+        SPAN_TYPE.findPageComponents,
+        { 'next.route': displayRoute },
+        fn,
+      );
+    },
+    emitResolveSegmentSpan: segment =>
+      emitLeafSpan('resolve segment modules', SPAN_TYPE.getLayoutOrPageModule, {
+        'next.segment': segment,
+      }),
+    withRouteHandlerSpan: (route, fn) =>
+      isPagesCompatRoute(route)
+        ? withPagesApiHandlerSpan(routePatternToDisplay(route), fn)
+        : withRouteHandlerSpan(routePatternToDisplay(route), fn),
+  });
+  setStreamBoundaryExtensions({ onStreamBoundaryError: markRenderSpanError });
+
+  // clientTraceMetadata meta tags injected once into the document head (dynamic pages only; a production
+  // start skips static). Composed with register-render's documentBodyScripts under a separate key.
+  // The renderer's `ctx.dynamic` already encodes Next's gating: dev renders are always dynamic, a prod
+  // STATIC page is dynamic:false, a prod DYNAMIC page is dynamic:true. So isNextStart:true is safe -
+  // clientTraceMetadataTags only drops when isNextStart && !dynamic, exactly the prod-static case.
+  const previousHeadTags = getDocumentScriptExtensions().documentHeadTags;
+  setDocumentScriptExtensions({
+    documentHeadTags: (cfg, ctx) =>
+      `${previousHeadTags?.(cfg, ctx) ?? ''}${clientTraceMetadataTags({ dynamic: ctx.dynamic, isNextStart: true, rsc: ctx.rsc })}`,
+  });
+
+  // Middleware.execute span around the proxy/middleware handler run. Parents
+  // under the incoming traceparent (top-level trace), NOT the request root span.
+  setProxyRunObserver((request, fn) => withMiddlewareSpan(request, fn));
+
+  const previousOnRequestError = getRequestExtensions().onRequestError;
+  setRequestExtensions({
+    onRequestError: async (error, requestInfo, context) => {
+      markRenderSpanError(error);
+      await previousOnRequestError(error, requestInfo, context);
+    },
+  });
+
+  // Late interceptor: re-stamp the route attributes after the rewrite/action
+  // interceptors ran, so a rewritten request reports its DESTINATION route
+  // (the root span itself was opened by the early interceptor with the
+  // original target — see registerOtelRootInterceptor).
+  const otelRouteInterceptor: RequestInterceptor = request => {
+    try {
+      stampMatchedRoute(new URL(request.url).pathname);
+    } catch {
+      // Never let tracing break the request.
+    }
+    return Promise.resolve(undefined);
+  };
+  registerRequestInterceptors(otelRouteInterceptor);
+
+  // Close the root span pre-flush with the final status. Runs on every response-producing path (page
+  // render, route handler, static file, redirect, 404). Before closing, emit the pre-flush leaf spans Next
+  // nests in the tree: `clientComponentLoading` (page renders only) and `start response` under the open
+  // render span for pages, or the root for handlers.
+  const otelFinalizer: ResponseFinalizer = ctx => {
+    try {
+      if (ctx.routeKind === 'html') emitClientComponentLoadingSpan(0);
+      if (ctx.routeKind === 'html' || ctx.routeKind === 'route-handler') {
+        emitStartResponseSpan();
+      }
+      endRootSpan(ctx.status);
+    } catch {
+      // ignore
+    }
+  };
+  registerResponseFinalizers(otelFinalizer);
+}
+
+/** The runtime route entry matching a raw route pattern. */
+function routeEntryFor(routePattern: string): RouteManifestEntry | undefined {
+  return getRequestRuntime()?.routes.find(r => r.route === routePattern);
+}
+
+// A hybrid app materializes BOTH trees under `pnext-pages-compat`: native app
+// files become `source-app/...` shims, pages files become `source-pages/...`
+// wrappers. Only the latter are pages-router routes. The import specifier is a
+// stable generator-owned marker; cache per file (routes don't change at start).
+const pagesCompatFileCache = new Map<string, boolean>();
+function isPagesCompatEntry(entry: RouteManifestEntry | undefined): boolean {
+  if (!entry?.file.includes(`${path.sep}pnext-pages-compat${path.sep}`)) return false;
+  let cached = pagesCompatFileCache.get(entry.file);
+  if (cached === undefined) {
+    try {
+      cached = readFileSync(entry.file, 'utf8').includes('source-pages/');
+    } catch {
+      cached = false;
+    }
+    pagesCompatFileCache.set(entry.file, cached);
+  }
+  return cached;
+}
+
+/** Whether `routePattern` matches a route materialized from `pages/`. */
+function isPagesCompatRoute(routePattern: string): boolean {
+  return isPagesCompatEntry(routeEntryFor(routePattern));
+}
+
+function routeEntryToDisplay(route: RouteManifestEntry): string {
+  let value = route.route || '/';
+  if (route.catchAll) {
+    const token = route.catchAllOptional
+      ? `[[...${route.catchAll}]]`
+      : `[...${route.catchAll}]`;
+    value = value.replace(`:${route.catchAll}*`, token);
+  }
+  for (const param of route.params) value = value.replace(`:${param}`, `[${param}]`);
+  return value;
+}
+
+function routePatternToDisplay(route: string): string {
+  return route
+    .replace(/:([A-Za-z0-9_]+)\*/g, '[...$1]')
+    .replace(/:([A-Za-z0-9_]+)/g, '[$1]');
+}