@wular/pnext 0.0.1

package/src/compat/next/custom-server.ts

@@ -0,0 +1,236 @@
+// Custom-server `next()` entry (COMPAT).
+//
+// Next apps can drive the framework through their own HTTP server, requiring 'next' and calling
+// `app.prepare()` / `app.getRequestHandler()`. pnext has no `next` package to require, so `pnext build`
+// materializes a minimal one into the app's `node_modules/next` when the app root ships a custom server
+// entry importing 'next'.
+//
+// The shim's factory boots the real pnext server as a child process on an ephemeral internal port and
+// proxies node req/res pairs to it, so the custom server observes Next's contract while pnext serves
+// every request - basePath, server actions, after(), graceful stop included. close() SIGTERMs the child
+// and awaits its exit, which lets pending after() callbacks drain.
+//
+// Only a missing, symlinked, or previously shimmed `node_modules/next` is replaced: the e2e harness
+// links the real Next checkout for tsc typechecks, and fixtures with a genuinely installed `next` are
+// left alone.
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import type { ResolvedConfig } from '../../config';
+
+const SERVER_ENTRY_NAMES = ['server.js', 'server.mjs', 'server.cjs', 'server.ts'];
+const SHIM_VERSION = '0.0.0-pnext-custom-server';
+
+/** Whether the app root ships a custom server entry that imports 'next'. */
+export function hasCustomServerEntry(root: string): boolean {
+  for (const name of SERVER_ENTRY_NAMES) {
+    const file = path.join(root, name);
+    if (!existsSync(file)) continue;
+    try {
+      const source = readFileSync(file, 'utf8');
+      if (/(?:require\(\s*['"]next['"]\s*\)|from\s+['"]next['"])/.test(source)) return true;
+    } catch {
+      // Unreadable entry — skip.
+    }
+  }
+  return false;
+}
+
+/**
+ * Materialize the `next` custom-server shim into the app's node_modules when a
+ * custom server entry exists. No-op when `node_modules/next` is a real
+ * third-party install (absent, symlinked, or an earlier shim is replaced).
+ */
+export async function emitCustomServerShim(config: ResolvedConfig): Promise<void> {
+  if (!hasCustomServerEntry(config.root)) return;
+  const target = path.join(config.root, 'node_modules', 'next');
+  try {
+    const stat = lstatSync(target);
+    // A previously emitted shim is a real directory too — refresh it, so a
+    // rebuild in an existing test dir never keeps a stale copy.
+    if (!stat.isSymbolicLink() && !isEmittedShim(target)) return; // real install — leave it alone
+    await rm(target, { recursive: true, force: true });
+  } catch {
+    // Missing — create fresh below.
+  }
+  await mkdir(target, { recursive: true });
+  await writeFile(
+    path.join(target, 'package.json'),
+    `${JSON.stringify({ name: 'next', version: SHIM_VERSION, main: 'index.cjs' }, null, 2)}\n`,
+  );
+  await writeFile(path.join(target, 'index.cjs'), customServerShimSource());
+}
+
+/** Whether `node_modules/next` is a shim this build emitted earlier. */
+function isEmittedShim(target: string): boolean {
+  try {
+    const pkg = JSON.parse(readFileSync(path.join(target, 'package.json'), 'utf8')) as { version?: string };
+    return pkg.version === SHIM_VERSION;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The shim source. Bakes the absolute pnext CLI path so the child boots the
+ * same runtime the harness/build used, from any app directory.
+ */
+function customServerShimSource(): string {
+  const cliPath = path.resolve(import.meta.dirname, '..', '..', 'cli', 'index.ts');
+  return `'use strict';
+// pnext custom-server shim for require('next') / import next from 'next'.
+// Generated by pnext build; see src/compat/next/custom-server.ts.
+const { spawn } = require('node:child_process');
+
+const PNEXT_CLI = ${JSON.stringify(cliPath)};
+const HOP_BY_HOP = new Set([
+  'connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization',
+  'te', 'trailer', 'transfer-encoding', 'upgrade', 'host', 'accept-encoding',
+]);
+
+function createServer(options = {}) {
+  const dev = Boolean(options.dev);
+  const hostname = options.hostname || 'localhost';
+  const port = options.port || 3000;
+  let child;
+  let childExited;
+  let internalPort;
+
+  async function prepare() {
+    if (internalPort) return;
+    child = spawn(
+      'bun',
+      ['--conditions=react-server', PNEXT_CLI, dev ? 'dev' : 'start', '--port', '0', '--hostname', '127.0.0.1'],
+      {
+        cwd: process.cwd(),
+        env: { ...process.env, BROWSER: 'none', NODE_ENV: dev ? 'development' : 'production' },
+        stdio: ['ignore', 'pipe', 'pipe'],
+      }
+    );
+    childExited = new Promise((resolve) => child.once('exit', resolve));
+    internalPort = await new Promise((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new Error('pnext custom-server: timed out waiting for the pnext server to start')),
+        60000
+      );
+      let buffer = '';
+      // Echo the child's logs line by line, relabelling its "- Local: <internal>"
+      // ready banner: log scanners on THIS process's stdout (the Next e2e harness
+      // parses that exact line for the app URL) must not pick up the internal
+      // port, or every request would bypass the custom server. Line buffering
+      // keeps a coalesced/split chunk from slipping the raw banner through.
+      const echoLines = (out) => {
+        let tail = '';
+        const write = (text) => {
+          const merged = tail + text;
+          const cut = merged.lastIndexOf('\\n') + 1;
+          tail = merged.slice(cut);
+          if (cut === 0) return;
+          out.write(merged.slice(0, cut).replace(/-(\\s*)(Local|Network):/g, '[pnext internal]$1$2:'));
+        };
+        child.once('exit', () => { if (tail) { const rest = tail; tail = ''; out.write(rest); } });
+        return write;
+      };
+      const echoOut = echoLines(process.stdout);
+      const echoErr = echoLines(process.stderr);
+      const scan = (chunk, echo) => {
+        const text = chunk.toString('utf8');
+        echo(text);
+        if (internalPort) return;
+        buffer = (buffer + text).slice(-4096);
+        const match = /-\\s*Local:\\s+https?:\\/\\/[^:\\s]+:(\\d+)/.exec(buffer);
+        if (match) {
+          clearTimeout(timer);
+          resolve(Number(match[1]));
+        }
+      };
+      child.stdout.on('data', (chunk) => scan(chunk, echoOut));
+      child.stderr.on('data', (chunk) => scan(chunk, echoErr));
+      child.once('exit', (code) => {
+        clearTimeout(timer);
+        reject(new Error('pnext custom-server: the pnext server exited during startup (code ' + code + ')'));
+      });
+    });
+  }
+
+  async function handleRequest(req, res) {
+    if (!internalPort) throw new Error('pnext custom-server: prepare() must complete before handling requests');
+    const target = new URL(req.url || '/', 'http://127.0.0.1:' + internalPort);
+    const headers = {};
+    for (const [name, value] of Object.entries(req.headers)) {
+      if (value === undefined || HOP_BY_HOP.has(name)) continue;
+      headers[name] = Array.isArray(value) ? value.join(', ') : value;
+    }
+    if (req.headers.host) headers['x-forwarded-host'] = req.headers.host;
+    headers['x-forwarded-proto'] = 'http';
+    const method = (req.method || 'GET').toUpperCase();
+    const hasBody = method !== 'GET' && method !== 'HEAD';
+    const response = await fetch(target, {
+      method,
+      headers,
+      body: hasBody ? req : undefined,
+      duplex: hasBody ? 'half' : undefined,
+      redirect: 'manual',
+    });
+    res.statusCode = response.status;
+    for (const [name, value] of response.headers) {
+      if (['content-encoding', 'content-length', 'transfer-encoding', 'set-cookie'].includes(name)) continue;
+      if (name === 'location') {
+        // Rewrite child-origin absolute redirects back to a relative target so
+        // the browser stays on the custom server's host/port.
+        try {
+          const url = new URL(value);
+          if (url.hostname === '127.0.0.1' && Number(url.port) === internalPort) {
+            res.setHeader(name, url.pathname + url.search + url.hash);
+            continue;
+          }
+        } catch {}
+      }
+      res.setHeader(name, value);
+    }
+    const setCookies = typeof response.headers.getSetCookie === 'function' ? response.headers.getSetCookie() : [];
+    if (setCookies.length > 0) {
+      const existing = res.getHeader('set-cookie');
+      const merged = existing === undefined ? setCookies : [].concat(existing, setCookies);
+      res.setHeader('set-cookie', merged);
+    }
+    if (response.body) {
+      for await (const chunk of response.body) res.write(chunk);
+    }
+    res.end();
+  }
+
+  async function close() {
+    if (!child || child.exitCode !== null) return;
+    // Graceful: the pnext server stops accepting connections, drains pending
+    // after() callbacks, then exits 0. Escalate to SIGKILL only on a hang.
+    child.kill('SIGTERM');
+    await Promise.race([
+      childExited,
+      new Promise((resolve) => setTimeout(resolve, 15000).unref()),
+    ]);
+    if (child.exitCode === null) child.kill('SIGKILL');
+  }
+
+  return {
+    hostname,
+    port,
+    prepare,
+    close,
+    getRequestHandler: () => (req, res) => handleRequest(req, res).catch((error) => {
+      console.error('pnext custom-server: request failed:', error);
+      if (!res.headersSent) res.statusCode = 500;
+      res.end('Internal Server Error');
+    }),
+    getUpgradeHandler: () => (_req, socket) => { socket.destroy(); },
+    setAssetPrefix: () => {},
+    logError: (...args) => console.error(...args),
+    render: async (req, res) => { await handleRequest(req, res); },
+    renderToHTML: async () => { throw new Error('renderToHTML is not supported by the pnext custom server'); },
+  };
+}
+
+module.exports = createServer;
+module.exports.default = createServer;
+`;
+}

package/src/compat/next/dist/client/components/app-router-headers.ts

@@ -0,0 +1,32 @@
+// Header-name constants matching
+// next/src/client/components/app-router-headers.ts exactly.
+export const RSC_HEADER = 'rsc' as const;
+export const ACTION_HEADER = 'next-action' as const;
+export const NEXT_ROUTER_STATE_TREE_HEADER = 'next-router-state-tree' as const;
+export const NEXT_ROUTER_PREFETCH_HEADER = 'next-router-prefetch' as const;
+export const NEXT_ROUTER_SEGMENT_PREFETCH_HEADER = 'next-router-segment-prefetch' as const;
+export const NEXT_HMR_REFRESH_HEADER = 'next-hmr-refresh' as const;
+export const NEXT_HMR_REFRESH_HASH_COOKIE = '__next_hmr_refresh_hash__' as const;
+export const NEXT_URL = 'next-url' as const;
+export const RSC_CONTENT_TYPE_HEADER = 'text/x-component' as const;
+
+export const NEXT_INSTANT_TEST_COOKIE = 'next-instant-navigation-testing' as const;
+
+export const FLIGHT_HEADERS = [
+  RSC_HEADER,
+  NEXT_ROUTER_STATE_TREE_HEADER,
+  NEXT_ROUTER_PREFETCH_HEADER,
+  NEXT_HMR_REFRESH_HEADER,
+  NEXT_ROUTER_SEGMENT_PREFETCH_HEADER,
+] as const;
+
+export const NEXT_RSC_UNION_QUERY = '_rsc' as const;
+export const NEXT_ROUTER_STALE_TIME_HEADER = 'x-nextjs-stale-time' as const;
+export const NEXT_DID_POSTPONE_HEADER = 'x-nextjs-postponed' as const;
+export const NEXT_REWRITTEN_PATH_HEADER = 'x-nextjs-rewritten-path' as const;
+export const NEXT_REWRITTEN_QUERY_HEADER = 'x-nextjs-rewritten-query' as const;
+export const NEXT_IS_PRERENDER_HEADER = 'x-nextjs-prerender' as const;
+export const NEXT_ACTION_NOT_FOUND_HEADER = 'x-nextjs-action-not-found' as const;
+export const NEXT_REQUEST_ID_HEADER = 'x-nextjs-request-id' as const;
+export const NEXT_HTML_REQUEST_ID_HEADER = 'x-nextjs-html-request-id' as const;
+export const NEXT_ACTION_REVALIDATED_HEADER = 'x-action-revalidated' as const;

package/src/compat/next/dist/server/app-render/work-unit-async-storage.external.cjs

@@ -0,0 +1,38 @@
+// Compat shim for the deep Next internal
+// `next/dist/server/app-render/work-unit-async-storage.external`.
+//
+// Some libraries (and app code, e.g. the app-external / segment-cache e2e
+// fixtures) import this module directly to reach the SAME work-unit store the
+// framework populates during a render. Next backs that with an
+// AsyncLocalStorage whose store carries `type` ('request' | 'prerender' |
+// 'prerender-runtime') plus, for a request work unit, `cookies`/`headers`.
+// pnext keeps that state in core (src/request/context.ts, src/ppr.ts) and
+// publishes a getter onto globalThis, which this module reflects — so a direct
+// import observes the live store rather than a separate, empty instance.
+//
+// CommonJS on purpose: apps `require()` this specifier, and the server
+// runtime's onLoad transform only intercepts `[jt]sx?` (see rootFilter), so a
+// `.cjs` external is left to Bun's native loader and stays synchronously
+// requirable. The same module as a `.ts` external is forced through that
+// transform, becomes an async module, and `require()` throws
+// "require() async module ... is unsupported". Same rule as constants.cjs /
+// navigation.cjs — see the note in src/compat/index.ts.
+const WORK_UNIT_EXTERNAL = Symbol.for('pnext.workUnitExternal')
+/** @type {Record<PropertyKey, unknown>} */
+const root = globalThis
+
+const workUnitAsyncStorage = {
+  // Never undefined: fixtures do `getStore().type` during build prerenders as
+  // well as live requests. Core's getter always answers with a store.
+  getStore: () =>
+    /** @type {(() => unknown) | undefined} */ (root[WORK_UNIT_EXTERNAL])?.(),
+  /**
+   * @param {unknown} _store
+   * @param {(...args: unknown[]) => unknown} callback
+   * @param {unknown[]} args
+   */
+  run: (_store, callback, ...args) => callback(...args),
+}
+
+exports.workUnitAsyncStorage = workUnitAsyncStorage
+exports.default = workUnitAsyncStorage

package/src/compat/next/dist/server/web/spec-extension/revalidate.ts

@@ -0,0 +1 @@
+export { revalidatePath, revalidateTag } from '../../../../cache';

package/src/compat/next/dist/server/web/spec-extension/unstable-cache.ts

@@ -0,0 +1 @@
+export { unstable_cache } from '../../../../cache';

package/src/compat/next/dist/server/web/spec-extension/unstable-no-store.ts

@@ -0,0 +1 @@
+export { unstable_noStore } from '../../../../cache';

package/src/compat/next/dynamic.tsx

@@ -0,0 +1,46 @@
+import { h, type ComponentType } from 'preact';
+import { lazy, Suspense } from 'preact/compat';
+import {
+  dynamic as pnextDynamic,
+  dynamicReferenceSymbol,
+  type DynamicLoader,
+  type DynamicModule,
+  type DynamicOptions,
+  type DynamicReference,
+  type DynamicTarget,
+} from '../../api/dynamic';
+
+export type { DynamicLoader, DynamicModule, DynamicOptions };
+
+export default function dynamic<Props extends object = object>(
+  loader: DynamicLoader<Props>,
+  options: DynamicOptions<Props> = {},
+  // Injected by the server compile; see rewriteDynamicCallTargets.
+  target?: DynamicTarget,
+) {
+  if (typeof loader === 'string') return pnextDynamic(loader, options, target);
+
+  const coreDynamic = pnextDynamic(loader, options, target) as DynamicWithReference<Props>;
+  const Lazy = lazy(() => loader().then(module => ({ default: componentFromModule(module) })));
+  const DynamicComponent = ((props: Props) => {
+    const Loading = options.loading;
+    const content = h(Suspense, { fallback: Loading ? h(Loading, props) : null }, h(Lazy, props));
+    return options.ssr === false
+      ? h('pnext-dynamic', { style: { display: 'contents' } },
+          (!process.browser && typeof window === 'undefined') ? null : content)
+      : content;
+  }) as DynamicWithReference<Props>;
+
+  DynamicComponent[dynamicReferenceSymbol] = coreDynamic[dynamicReferenceSymbol];
+  return DynamicComponent;
+}
+
+export { dynamic };
+
+type DynamicWithReference<Props extends object> = ComponentType<Props> & {
+  [dynamicReferenceSymbol]?: DynamicReference<Props>;
+};
+
+function componentFromModule<Props>(module: DynamicModule<Props>) {
+  return typeof module === 'function' ? module : module.default;
+}

package/src/compat/next/error.tsx

@@ -0,0 +1,148 @@
+'use client';
+
+import { Component, Fragment, h, type ComponentChildren, type ComponentType } from 'preact';
+import { isControlFlowError } from '../client/errors/control-flow';
+import { untagPrimitiveThrow } from '../client/errors/primitive-throw';
+
+export interface ErrorInfo {
+  error: unknown;
+  reset: () => void;
+  unstable_retry: () => void;
+}
+
+// Island error-boundary protocol (see render/renderer.ts): when a Server Component inside this
+// boundary's children throws during the SSR resolve walk, the renderer serializes the error into this
+// prop on the island - used twice. On SSR the initial state is the caught state, so the fallback renders
+// inline; on hydration the prop rides `data-pnext-props`, so the client mount re-creates the SAME caught
+// state and the server-rendered fallback hydrates interactive. Without this handoff the client would
+// remount with "no error" and blank out the fallback. The renderer only performs the handoff for
+// components carrying `Symbol.for('pnext.islandErrorBoundary')`, stamped below.
+const ISLAND_BOUNDARY_ERROR_PROP = '__pnextBoundaryError';
+const islandErrorBoundarySymbol = Symbol.for('pnext.islandErrorBoundary');
+
+interface IslandBoundaryErrorMarker {
+  name?: string;
+  message?: string;
+  digest?: string;
+}
+
+interface CatchErrorProps {
+  children?: ComponentChildren;
+  clearError?: () => void;
+  [ISLAND_BOUNDARY_ERROR_PROP]?: IslandBoundaryErrorMarker;
+}
+
+interface CatchErrorState {
+  error: unknown;
+  hasError: boolean;
+  version: number;
+}
+
+function reviveBoundaryError(marker: IslandBoundaryErrorMarker): Error & { digest?: string } {
+  const error = new Error(String(marker.message ?? '')) as Error & { digest?: string };
+  if (marker.name) error.name = String(marker.name);
+  if (typeof marker.digest === 'string') error.digest = marker.digest;
+  return error;
+}
+
+function initialCatchErrorState(props: CatchErrorProps): CatchErrorState {
+  const marker = props[ISLAND_BOUNDARY_ERROR_PROP];
+  if (marker && typeof marker === 'object') {
+    return { error: reviveBoundaryError(marker), hasError: true, version: 0 };
+  }
+  return { error: undefined, hasError: false, version: 0 };
+}
+
+export function unstable_catchError<Props extends Record<string, unknown>>(
+  Fallback: (props: Props, info: ErrorInfo) => ComponentChildren,
+): ComponentType<Props & CatchErrorProps> {
+  class CatchError extends Component<Props & CatchErrorProps, CatchErrorState> {
+    state: CatchErrorState = initialCatchErrorState(this.props);
+
+    static getDerivedStateFromError(error: unknown): Partial<CatchErrorState> {
+      // Router signals belong to their owning route boundary. Capturing one
+      // here turns a redirect/notFound into a stale local fallback instead of
+      // letting the client control-flow handler complete the navigation.
+      if (isControlFlowError(error)) throw error;
+      return { error: normalizeBoundaryError(error), hasError: true };
+    }
+
+    reset = () => {
+      this.props.clearError?.();
+      this.setState(state => ({
+        error: undefined,
+        hasError: false,
+        version: state.version + 1,
+      }));
+    };
+
+    unstable_retry = () => {
+      // App-Router only: `unstable_retry` re-runs the server render, which the Pages Router has no
+      // equivalent of. The discriminator is the rendering context, NOT the user-supplied `clearError`
+      // prop (the Pages fixture passes it too) - App-Router documents always render the segment tree as
+      // <pnext-layout>/[data-pnext-root] elements; Pages ones never do.
+      if (!isAppRouterDocument()) {
+        throw new Error(
+          '`unstable_retry()` can only be used in the App Router. Use `reset()` in the Pages Router.',
+        );
+      }
+      if (!process.browser && typeof window === 'undefined') {
+        this.reset();
+        return;
+      }
+      // Refresh FIRST, reset when it settles. Resetting immediately re-renders the children while the
+      // refresh response is still in flight; anything the user does in that window is wiped when the
+      // body swap lands, so a rapid retry-then-interact cycle loses the new state. Deferring the reset
+      // closes that window (if the swap remounted this boundary the setState is a no-op on an unmounted
+      // instance, which preact ignores). A failed refresh still resets.
+      const refreshed = routerRefresh();
+      void Promise.resolve(refreshed)
+        .catch(() => undefined)
+        .then(() => this.reset());
+    };
+
+    render(props: Props & CatchErrorProps, state: CatchErrorState) {
+      if (state.hasError) {
+        // Strip the internal handoff marker; the user's fallback gets the
+        // component's own props (title, clearError, ...), matching Next.
+        const { [ISLAND_BOUNDARY_ERROR_PROP]: _marker, ...rest } = props;
+        return Fallback(rest as unknown as Props, {
+          error: state.error,
+          reset: this.reset,
+          unstable_retry: this.unstable_retry,
+        });
+      }
+      return h(Fragment, { key: state.version }, props.children);
+    }
+  }
+  // Opt in to the renderer's island error-boundary handoff (see above).
+  (CatchError as unknown as Record<symbol, boolean>)[islandErrorBoundarySymbol] = true;
+  return CatchError;
+}
+
+function isAppRouterDocument(): boolean {
+  if (typeof document === 'undefined') return false;
+  return Boolean(document.querySelector('pnext-layout, [data-pnext-root]'));
+}
+
+function routerRefresh() {
+  const global = window as unknown as {
+    __PNEXT_ROUTER__?: { refresh?: () => Promise<void> | void };
+  };
+  return global.__PNEXT_ROUTER__?.refresh?.();
+}
+
+function normalizeBoundaryError(error: unknown): unknown {
+  // Preact-core interop tag (see client/errors/primitive-throw.ts): a client
+  // `throw undefined`/`null` arrives here re-thrown as a tagged Error so it
+  // survived preact's own `e.then` suspense check without crashing. Unwrap
+  // back to the raw value Next passes to error UIs.
+  const untagged = untagPrimitiveThrow(error);
+  if (untagged !== error) return untagged;
+  if (error instanceof Error) {
+    // Fallback for any crash that slips through un-tagged (defense in depth).
+    if (error.message === "Cannot read properties of undefined (reading 'then')") return undefined;
+    if (error.message === "Cannot read properties of null (reading 'then')") return null;
+  }
+  return error;
+}