@wular/pnext 0.0.1

package/src/compat/register/proxy.ts

@@ -0,0 +1,127 @@
+import path from 'node:path';
+import { type ResolvedConfig } from '../../config';
+import { setProxyExtensions, setProxyResponseProtocol } from '../../extensions';
+import { findProxyFiles, setProxyRewriteObserver } from '../../proxy';
+import { moduleExportNames } from '../../resolve/scan-facts';
+import { readText, toPosixPath } from '../../utils/fs';
+import { recordRewrite } from '../protocol';
+import { recordCanonicalUrl } from '../next/canonical-url';
+import { getNextConfig } from '../next/config-loader';
+import { activateTestProxy } from '../lifecycle/testmode';
+
+export function registerProxyExtensions(_config: ResolvedConfig): void {
+  setProxyResponseProtocol({
+    nextHeader: 'x-middleware-next',
+    rewriteHeader: 'x-middleware-rewrite',
+  });
+  setProxyExtensions({
+    names: ['proxy', 'middleware'],
+    validateFiles: validateNextProxyFiles,
+    handlerExport: module => module.proxy ?? module.default ?? module.middleware,
+    skipUrlNormalize: () => getNextConfig().skipProxyUrlNormalize === true,
+    locale: proxyLocale,
+    onExternalRewrite: request => activateTestProxy(request.headers),
+    clientMaxBodySize: proxyClientMaxBodySize,
+  });
+  // A same-origin middleware rewrite feeds the Next rewrite-tracking channel so
+  // RSC responses carry x-nextjs-rewritten-path/query (identical to next.config
+  // rewrites; the RSC-only emission gate lives in compat/protocol.ts). The
+  // ORIGINAL url is stashed too so usePathname/useSearchParams stay canonical.
+  setProxyRewriteObserver((from, to) => {
+    recordCanonicalUrl(from);
+    recordRewrite(from, to);
+  });
+}
+
+const DEFAULT_PROXY_CLIENT_MAX_BODY_SIZE = 10 * 1024 * 1024;
+
+// experimental.proxyClientMaxBodySize accepts bytes (2097152) or a size string
+// ('5mb'); experimental.middlewareClientMaxBodySize is the deprecated alias.
+function proxyClientMaxBodySize(): number {
+  const experimental = (getNextConfig().experimental ?? {}) as Record<string, unknown>;
+  const raw = experimental.proxyClientMaxBodySize ?? experimental.middlewareClientMaxBodySize;
+  if (typeof raw === 'number' && raw > 0) return raw;
+  if (typeof raw === 'string') {
+    const match = /^(\d+(?:\.\d+)?)\s*(b|kb|mb|gb)?$/i.exec(raw.trim());
+    if (match?.[1]) {
+      const unit = (match[2] ?? 'b').toLowerCase();
+      const multiplier =
+        unit === 'gb' ? 1024 ** 3 : unit === 'mb' ? 1024 ** 2 : unit === 'kb' ? 1024 : 1;
+      const bytes = Math.floor(Number(match[1]) * multiplier);
+      if (bytes > 0) return bytes;
+    }
+  }
+  return DEFAULT_PROXY_CLIENT_MAX_BODY_SIZE;
+}
+
+function proxyLocale(url: URL): string {
+  const i18n = getNextConfig().i18n as { locales?: unknown } | undefined;
+  if (!Array.isArray(i18n?.locales)) return '';
+  const locales = i18n.locales.filter((locale): locale is string => typeof locale === 'string');
+  const dataLocale = /^\/_next\/data\/[^/]+\/([^/]+)(?:\/|$)/.exec(url.pathname)?.[1];
+  const candidate = dataLocale ?? url.pathname.split('/')[1];
+  return locales.find(locale => locale.toLowerCase() === candidate?.toLowerCase()) ?? '';
+}
+
+async function validateNextProxyFiles(config: ResolvedConfig) {
+  const files = findProxyFiles(config, ['proxy', 'middleware']);
+  const middleware = files.find(file => path.basename(file).startsWith('middleware.'));
+  const proxy = files.find(file => path.basename(file).startsWith('proxy.'));
+  if (middleware && proxy) {
+    throw new Error(
+      `Both middleware file "${relativeProxyPath(config, middleware)}" and proxy file "${relativeProxyPath(config, proxy)}" are detected. Please use "${relativeProxyPath(config, proxy)}" only.`,
+    );
+  }
+  if (middleware && !proxy) {
+    console.warn(
+      'The "middleware" file convention is deprecated. Please use "proxy" instead.',
+    );
+  }
+  await Promise.all(files.map(file => validateNextProxyFile(config, file)));
+}
+
+async function validateNextProxyFile(config: ResolvedConfig, file: string) {
+  const source = await readText(file);
+  const name = path.basename(file).split('.')[0];
+  const exports = moduleExportNames(source, file);
+  const validExport =
+    exports.includes('default') ||
+    (name === 'proxy' ? exports.includes('proxy') : exports.includes('middleware'));
+  if (!validExport) {
+    throw new Error(proxyMissingExportError(config, file));
+  }
+  if (name === 'proxy' && hasRuntimeConfig(source)) {
+    throw new Error(
+      `Route segment config is not allowed in Proxy file at "${relativeProxyPath(config, file)}". Proxy always runs on Node.js runtime. Learn more: https://nextjs.org/docs/messages/middleware-to-proxy`,
+    );
+  }
+}
+
+function proxyMissingExportError(config: ResolvedConfig, file: string) {
+  const name = path.basename(file).split('.')[0] === 'middleware' ? 'middleware' : 'proxy';
+  const migrationReason =
+    name === 'proxy'
+      ? "- You are migrating from `middleware` to `proxy`, but haven't updated the exported function.\n"
+      : '';
+  const target = name === 'proxy' ? 'proxy (previously called middleware)' : 'middleware';
+  return `The file "${relativeProxyPath(config, file)}" must export a function, either as a default export or as a named "${name}" export.
+This function is what Next.js runs for every request handled by this ${target}.
+
+Why this happens:
+${migrationReason}- The file exists but doesn't export a function.
+- The export is not a function (e.g., an object or constant).
+- There's a syntax error preventing the export from being recognized.
+
+To fix it:
+- Ensure this file has either a default or "${name}" function export.
+
+Learn more: https://nextjs.org/docs/messages/middleware-to-proxy`;
+}
+
+function hasRuntimeConfig(source: string) {
+  return /\bexport\s+const\s+config\s*=/.test(source) && /\bruntime\s*:/.test(source);
+}
+
+function relativeProxyPath(config: ResolvedConfig, file: string) {
+  return `./${toPosixPath(path.relative(config.root, file))}`;
+}

package/src/compat/register/render.ts

@@ -0,0 +1,268 @@
+// Render extension registration (COMPAT - may import core freely).
+//
+// Wires the react/next render behaviors into the core render registries at the gated bootstrap seam. Two
+// homes:
+//
+//   src/extensions.ts (shared render registry):
+//     - wrapServerComponentInvoke <- invokeServerComponentWithUse (use()-thenable replay for synchronous
+//       server components).
+//     - onRenderInit              <- optional compat one-time render init.
+//
+//   src/render/hooks.ts (render-only companion registry):
+//     - fontExtensions     <- runWithFontScope + fontAssets (next/font CSS + preloads). Next-compat only.
+//     - suspenseExtensions <- the preact/compat Suspense identity the streaming walker treats as a
+//       boundary. React-compat, loaded lazily.
+//
+// serializeServerActionProp, collectRenderMeta and the server-action module tagging hooks are populated
+// by the actions and cache sub-registrars; this file owns the react and font/suspense hooks.
+
+import type { ResolvedConfig } from '../../config';
+import { onExtensionHostReset, setRenderExtensions } from '../../extensions';
+import { setReactCompatActive } from '../react/preact';
+
+// preact's global vnode hook cannot be uninstalled, so it follows the host.
+onExtensionHostReset(() => setReactCompatActive(false));
+import {
+  nextCompatEnabled,
+  reactCompatEnabled,
+  setDocumentScriptExtensions,
+  setFontExtensions,
+  setMetadataExtensions,
+  setStaticParamsExtensions,
+  setStreamRouteExtensions,
+  setSuspenseExtensions,
+} from '../../render/hooks';
+import { withAssetPrefix } from '../../css';
+import { polyfillsChunkPath } from '../bundler/polyfill';
+import { nextRouterShimScript } from '../react/router-shim';
+import { renderPartytownHeadScripts } from '../next/script';
+import { ensureCompatSuspense, compatSuspenseType } from '../../compat';
+import { invokeServerComponentWithUse } from '../react/server-component-use';
+import { fontAssets, fontPreloadDomScript, prewarmFonts, runWithFontScope } from '../next/font/runtime';
+import {
+  hasRuntimeMetadata,
+  readNextModuleMetadata,
+  readNextModuleViewport,
+  shouldRenderMetadataInBody,
+} from '../metadata';
+import { aliasGenerateStaticParams } from '../static-params';
+import { getNextConfig } from '../next/config-loader';
+import {
+  renderServerInsertedHTML,
+  setServerInsertedHTMLScope,
+} from '../react/server-inserted-html';
+import { nextClientRouteState } from '../next/optimistic-route-state';
+import { earlySubmitCaptureScript } from '../actions/early-submit';
+import { getWorkUnit } from '../../request/context';
+import {
+  createVaryParamsAccumulator,
+  createVaryingParams,
+  createVaryingSearchParams,
+  normalizeOptionalCatchAllParams,
+} from '../segment/vary-params';
+import type { VaryParamsTrackingContext } from '../../extensions';
+
+export function registerRenderExtensions(config: ResolvedConfig): void {
+  // The react layer only matters when react/next compat is on. A next-only
+  // predicate would miss react-compat-only apps (which still render server
+  // components with use() and need the compat Suspense identity for streaming).
+  if (!reactCompatEnabled(config)) return;
+
+  setReactCompatActive(true);
+
+  setServerInsertedHTMLScope(() => {
+    const workUnit = getWorkUnit();
+    if (!workUnit) return undefined;
+    return (workUnit.compat ??= {});
+  });
+
+  setRenderExtensions({
+    wrapServerComponentInvoke: invokeServerComponentWithUse,
+    genericErrorTitle: ({ dev }) => (dev ? undefined : 'This page couldn\u2019t load'),
+  });
+
+  setSuspenseExtensions({ ensureCompatSuspense, compatSuspenseType });
+
+  // next/font is a next-compat feature; a react-only app renders no fonts.
+  if (nextCompatEnabled(config)) {
+    setStreamRouteExtensions({
+      canStreamRoute: canStreamNextRoute,
+      inlineSuspenseStream: needsInlineSuspenseStream,
+    });
+    setMetadataExtensions({
+      enabled: nextCompatEnabled,
+      hasRuntimeMetadata,
+      readModuleMetadata: readNextModuleMetadata,
+      readModuleViewport: readNextModuleViewport,
+      shouldRenderMetadataInBody,
+    });
+    setStaticParamsExtensions({ normalizeModule: aliasGenerateStaticParams });
+    setRenderExtensions({
+      clientRouteState: nextClientRouteState,
+      trackVaryParams: trackRenderVaryParams,
+      // Next asserts structural selectors (`body > p`) against the live DOM, so
+      // island hosts and the page slot travel as comment pairs and the inline
+      // bootstrap materializes them. Core ships the elements as final.
+      islandCommentWireFormat: () => true,
+    });
+    setDocumentScriptExtensions({
+      stylesheetPrecedence: cfg => (nextCompatEnabled(cfg) ? 'next' : undefined),
+    });
+    setFontExtensions({ runWithFontScope, collectFontAssets: fontAssets, prewarmFontAssets: prewarmFonts });
+    setDocumentScriptExtensions({
+      documentBodyScripts: cfg =>
+        `${flightDataBootstrapScript()}${renderPartytownHeadScripts()}${basePathScript(cfg.basePath)}${trailingSlashScript(cfg.trailingSlash)}${skipTrailingSlashScript(cfg.skipTrailingSlashRedirect)}${staleTimesScript()}${segmentSchedulerScript()}${appShellsScript()}${optimisticRoutingScript()}${nextRouterShimScript()}<script>${earlySubmitCaptureScript()}</script>${fontPreloadDomScript()}`,
+      documentHeadTags: () => `${polyfillsScript(config)}${renderServerInsertedHTML()}`,
+      streamInsertedHTML: renderServerInsertedHTML,
+    });
+  }
+}
+
+/**
+ * Hand a render's `params`/`searchParams` back wrapped in a tracking view when a vary-params scope is
+ * open (a segment-prefetch render). Each call allocates its OWN body-segment accumulator, tagged with the
+ * caller's segment kind so the response publishes the layout and page vary sets side by side instead of
+ * one union. Outside a scope the accumulator is null and the original object passes through untouched, so
+ * ordinary document renders pay nothing.
+ */
+function trackRenderVaryParams<T extends Record<string, unknown>>(
+  value: T,
+  context: VaryParamsTrackingContext,
+): T {
+  const accumulator = createVaryParamsAccumulator(context.segment ?? 'page');
+  if (!accumulator) {
+    // Segment-M2 deliverable 5: Next's params shape (an EMPTY optional catch-all
+    // carries no key) applies to every render, not just tracked ones.
+    return context.kind === 'searchParams'
+      ? value
+      : normalizeOptionalCatchAllParams(value, context.optionalCatchAllParam ?? null);
+  }
+  return context.kind === 'searchParams'
+    ? createVaryingSearchParams(accumulator, value)
+    : createVaryingParams(accumulator, value, context.optionalCatchAllParam ?? null);
+}
+
+/**
+ * Next's flight transport inlines its RSC payload as `self.__next_f.push(...)` chunks, and app code (plus
+ * Next's own e2e assertions) treats the presence of that global as "this document carries inlined server
+ * data". pnext streams its payload through a different global, so nothing here reads `__next_f` - this
+ * declares the array and pushes an empty marker so the documented global exists with Next's shape. Inert
+ * by construction.
+ */
+function flightDataBootstrapScript(): string {
+  return `<script>(self.__next_f=self.__next_f||[]).push([0])</script>`;
+}
+
+// Next emits a `<script noModule>` tag referencing the polyfills chunk in the
+// document head. It never executes in module-capable browsers; it exists so the
+// served HTML carries the same polyfills tag Next does (the emitted chunk is
+// written by the client build's static-chunk seam). assetPrefix is applied so a
+// CDN-hosted asset base still resolves.
+function polyfillsScript(config: ResolvedConfig): string {
+  return `<script src="${withAssetPrefix(config, polyfillsChunkPath())}" noModule=""></script>`;
+}
+
+function canStreamNextRoute(input: {
+  config: ResolvedConfig;
+  route: { client?: boolean; stream?: unknown };
+}) {
+  if (!nextCompatEnabled(input.config)) return true;
+  // Whole-page client routes stream through a single Preact render, preserving
+  // ancestor provider context across their Suspense boundaries.
+  if (input.route.client) return true;
+  const stream = input.route.stream as
+    | { hasLoadingBoundary?: boolean; ancestorClientReferences?: string[] }
+    | undefined;
+  // No stream metadata means a non-page route (handlers never reach the page
+  // renderer) — nothing to stream.
+  if (!stream) return false;
+  // Out-of-order streaming isolates each Suspense boundary and drops client-provider context inherited
+  // from ancestor layouts/templates. When no ancestor ships a client reference there is nothing to lose;
+  // when one does, the route still streams through the single-render inline-suspense path, which keeps the
+  // whole tree in one preact render so ancestor providers stay in scope.
+  return true;
+}
+
+// A route whose ancestor layouts/templates ship client references streams in
+// place (one preact render that suspends at each boundary) instead of flushing
+// replacement chunks rendered from a fresh root, which would drop the ancestor
+// islands' provider context around the boundary's content.
+function needsInlineSuspenseStream(input: {
+  config: ResolvedConfig;
+  route: { client?: boolean; stream?: unknown };
+}) {
+  if (!nextCompatEnabled(input.config) || input.route.client) return false;
+  const stream = input.route.stream as { ancestorClientReferences?: string[] } | undefined;
+  return (stream?.ancestorClientReferences?.length ?? 0) > 0;
+}
+
+// Inline script exposing experimental.staleTimes so the client prefetch cache
+// honors config overrides (defaults 30s dynamic / 300s static apply otherwise).
+function staleTimesScript(): string {
+  const experimental = getNextConfig().experimental as
+    | { staleTimes?: { dynamic?: number; static?: number } }
+    | undefined;
+  const staleTimes = experimental?.staleTimes;
+  if (!staleTimes) return '';
+  return `<script>window.__PNEXT_STALE_TIMES__=${JSON.stringify(staleTimes)};</script>`;
+}
+
+// The client prefetch bandwidth scheduler (concurrency limits + hover-reserved lanes) reproduces Next's
+// SEGMENT-CACHE scheduler, which only exists under cacheComponents. A classic prefetch app must fire all
+// visible prefetches without throttling - the app-client-cache full-prefetch tests clear their request
+// listener between two staggered prefetches and would see the delayed one land as an unexpected request.
+function segmentSchedulerScript(): string {
+  const config = getNextConfig() as { cacheComponents?: unknown };
+  return config.cacheComponents === true
+    ? `<script>window.__PNEXT_SEGMENT_SCHEDULER__=true;</script>`
+    : '';
+}
+
+// `experimental.appShells`: the client fires a SECOND, param-stripped prefetch
+// per params-reading route to prime that route's shared App Shell (compat/
+// client/segment-prefetch.ts). Strictly opt-in — without the flag the extra
+// request would break the request-count contracts of every other suite.
+function appShellsScript(): string {
+  const experimental = getNextConfig().experimental as { appShells?: unknown } | undefined;
+  return experimental?.appShells === true
+    ? `<script>window.__PNEXT_APP_SHELLS__=true;</script>`
+    : '';
+}
+
+// `experimental.optimisticRouting` defaults ON, so this is an OPT-OUT marker:
+// only an app that explicitly disabled it stamps the document, and the client
+// segment cache then stops letting one URL's entry satisfy another URL's
+// PREFETCH (compat/client/segment-cache.ts). Navigation reuse is unaffected.
+function optimisticRoutingScript(): string {
+  const experimental = getNextConfig().experimental as
+    | { optimisticRouting?: unknown }
+    | undefined;
+  return experimental?.optimisticRouting === false
+    ? `<script>window.__PNEXT_NO_OPTIMISTIC_ROUTING__=true;</script>`
+    : '';
+}
+
+/**
+ * Inline script exposing the configured basePath to the client. `next/form` and other compat client code
+ * read `window.__PNEXT_BASE_PATH__` to prefix soft-nav targets. Emitted only when a basePath is set - a
+ * bare app keeps the global undefined, treated as ''.
+ */
+function basePathScript(basePath: string): string {
+  if (!basePath) return '';
+  return `<script>window.__PNEXT_BASE_PATH__=${JSON.stringify(basePath)};</script>`;
+}
+
+/**
+ * Inline script exposing skipTrailingSlashRedirect to the client so Link hrefs and client navigation
+ * preserve the author's exact trailing slash. Emitted only when the flag is set - a normal app keeps the
+ * global undefined, treated as false.
+ */
+function skipTrailingSlashScript(skip: boolean | undefined): string {
+  if (!skip) return '';
+  return `<script>window.__PNEXT_SKIP_TRAILING_SLASH__=true;</script>`;
+}
+
+function trailingSlashScript(trailingSlash: boolean | undefined): string {
+  if (trailingSlash !== true) return '';
+  return `<script>window.__PNEXT_TRAILING_SLASH__=true;</script>`;
+}