@wular/pnext 0.0.1

package/src/compat/protocol.ts

@@ -0,0 +1,202 @@
+// HTTP protocol conformance finalizers (COMPAT - may import core freely).
+//
+// Registered as core responseFinalizers when compat.next is on. Each runs before the first flush and
+// mutates the outgoing headers in place to emit the Next wire-protocol headers pnext core deliberately
+// does not know about:
+//   - `Vary` merge: append Next's router vary tokens to any existing Vary (user- or middleware-set)
+//     instead of overwriting.
+//   - `x-nextjs-rewritten-path` / `-query`: on responses whose URL a compat rewrite changed, so the
+//     client router can set the canonical URL.
+//
+// Core owns the generic "merge, do not overwrite" discipline; compat owns the exact Next header
+// names and values. A pure-core app registers none of this.
+
+import type { ResolvedConfig } from '../config';
+import { getWorkUnit, type WorkUnit } from '../request/context';
+import type {
+  RequestInterceptor,
+  ResponseFinalizer,
+  ResponseFinalizerContext,
+} from '../extensions';
+import { nextCompatEnabled } from '../compat';
+
+// Next's router vary tokens appended to every app-router response so a CDN
+// keys its cache on the RSC negotiation headers. Order + spelling match Next.
+const ROUTER_VARY = [
+  'rsc',
+  'next-router-state-tree',
+  'next-router-prefetch',
+  'next-router-segment-prefetch',
+];
+
+/** Rewrite tracking recorded per request by the compat rewrite interceptor. */
+interface RewriteInfo {
+  /** Destination pathname, only when it differs from the requested one. */
+  path?: string;
+  /** Destination query (without leading `?`), only when non-empty. */
+  query?: string;
+}
+
+// Keyed on the request's work unit (stable for the whole response lifecycle);
+// the interceptor writes it, the finalizer reads it. A WeakMap so completed
+// requests are collected without any explicit teardown.
+const rewrites = new WeakMap<WorkUnit, RewriteInfo>();
+
+/**
+ * Record that a compat rewrite changed the request URL from `from` to `to`.
+ * The response finalizer emits `x-nextjs-rewritten-path/query` from this. A
+ * no-op outside a request work unit or when the URL did not actually change.
+ */
+export function recordRewrite(from: URL, to: URL): void {
+  const unit = getWorkUnit();
+  if (!unit) return;
+  if (from.pathname === to.pathname && from.search === to.search) return;
+  const query = to.search.replace(/^\?/, '');
+  // Next reports the path header only when the pathname actually changed, and
+  // the query header only when the destination carries a query (a query-only
+  // rewrite reports query alone; a path-only rewrite reports path alone).
+  rewrites.set(unit, {
+    ...(to.pathname !== from.pathname ? { path: to.pathname } : {}),
+    ...(query ? { query } : {}),
+  });
+}
+
+/**
+ * Internal marker set by the segment responder's `_rsc` cache-busting 307 so
+ * this module's redirect normalization leaves it alone. Never reaches a client.
+ */
+export const CACHE_BUSTING_REDIRECT_HEADER = 'x-pnext-cache-bust';
+
+const APP_ROUTE_KINDS = new Set<ResponseFinalizerContext['routeKind']>([
+  'html',
+  'data',
+  'route-handler',
+]);
+
+const protocolFinalizer: ResponseFinalizer = ctx => {
+  if (!APP_ROUTE_KINDS.has(ctx.routeKind)) return;
+  mergeVary(ctx.headers, ROUTER_VARY);
+  normalizeRscRedirectStatus(ctx);
+  applyRewrittenHeaders(ctx);
+  applyEdgeRuntimeHeader(ctx);
+};
+
+// Next's edge SSR/route wrappers stamp `x-edge-runtime: 1` on every response
+// from a route whose segment config selects the edge runtime (edge-ssr-app.ts).
+// The matched route's runtime rides on the work-unit response hints.
+function applyEdgeRuntimeHeader(ctx: ResponseFinalizerContext): void {
+  const runtime = ctx.hints?.runtime;
+  if (runtime === 'edge' || runtime === 'experimental-edge') {
+    ctx.headers.set('x-edge-runtime', '1');
+  }
+}
+
+// Append `values` to the response's Vary header, preserving any existing tokens
+// (user- or middleware-set) and never duplicating (case-insensitive).
+function mergeVary(headers: Headers, values: readonly string[]): void {
+  const existing = headers.get('vary');
+  const present = new Set(
+    (existing ?? '')
+      .split(',')
+      .map(token => token.trim().toLowerCase())
+      .filter(Boolean),
+  );
+  const merged = existing ? existing.split(',').map(token => token.trim()).filter(Boolean) : [];
+  for (const value of values) {
+    if (present.has(value.toLowerCase())) continue;
+    present.add(value.toLowerCase());
+    merged.push(value);
+  }
+  if (merged.length > 0) headers.set('vary', merged.join(', '));
+}
+
+// Emit x-nextjs-rewritten-path/query when a compat rewrite changed this
+// request's URL. Next emits these only on RSC requests (the client router
+// restores the canonical URL from them); plain HTML/navigation responses omit
+// them. Each header is set only when the rewrite recorded that part. Absent on
+// non-rewritten responses (the WeakMap has no entry).
+function applyRewrittenHeaders(ctx: ResponseFinalizerContext): void {
+  if (ctx.request.headers.get('rsc') !== '1') return;
+  const unit = getWorkUnit();
+  if (!unit) return;
+  const info = rewrites.get(unit);
+  if (!info) return;
+  if (info.path !== undefined) ctx.headers.set('x-nextjs-rewritten-path', info.path);
+  if (info.query !== undefined) ctx.headers.set('x-nextjs-rewritten-query', info.query);
+}
+
+function normalizeRscRedirectStatus(ctx: ResponseFinalizerContext): void {
+  // A `_rsc` cache-busting bounce (register-segment) is a CDN key rotation, not
+  // an app redirect(): Next sends it as a real 307 that every client follows,
+  // so it must survive this normalization. The marker is internal — strip it.
+  if (ctx.headers.has(CACHE_BUSTING_REDIRECT_HEADER)) {
+    ctx.headers.delete(CACHE_BUSTING_REDIRECT_HEADER);
+    return;
+  }
+  if (ctx.routeKind !== 'html') return;
+  if (ctx.request.headers.get('rsc') !== '1') return;
+  // pnext's own soft-nav client sends rsc:1 but follows real redirects via
+  // fetch (it reads response.url as the final URL); rewriting 307/308 to 200
+  // would strand it on the source URL. The 200+Location wire form is only
+  // meaningful to Next's client, which never sends x-pnext-soft-nav.
+  if (ctx.request.headers.has('x-pnext-soft-nav')) return;
+  if (!ctx.headers.has('location')) return;
+  if (ctx.status !== 307 && ctx.status !== 308) return;
+  ctx.status = 200;
+}
+
+// next-router-state-tree validation (Next's parseAndValidateFlightRouterState).
+//
+// Next parses the RSC navigation's router state tree against a schema and lets a parse failure escape as
+// a 500 - a malformed tree is a protocol violation, not something to render around. pnext's renderer
+// ignores the header, so the check lives here, in front of route matching, and is deliberately narrow:
+// only a tree that is unparseable, not an array, or whose parallel-routes slot is not an object is
+// rejected. Anything Next's own client can send passes untouched.
+
+function isValidFlightRouterState(value: unknown): boolean {
+  if (!Array.isArray(value)) return false;
+  const [segment, parallelRoutes] = value as unknown[];
+  if (typeof segment !== 'string' && !Array.isArray(segment)) return false;
+  if (typeof parallelRoutes !== 'object' || parallelRoutes === null) return false;
+  if (Array.isArray(parallelRoutes)) return false;
+  return Object.values(parallelRoutes as Record<string, unknown>).every(isValidFlightRouterState);
+}
+
+const routerStateTreeInterceptor: RequestInterceptor = request =>
+  Promise.resolve(validateRouterStateTree(request));
+
+function validateRouterStateTree(request: Request): Response | undefined {
+  if (request.headers.get('rsc') !== '1') return undefined;
+  // pnext's own client mirrors its richer nav-state object into this header for
+  // wire compat (api/router.ts); that object is not a FlightRouterState and is
+  // never what this check is about.
+  if (request.headers.has('x-pnext-soft-nav')) return undefined;
+  const header = request.headers.get('next-router-state-tree');
+  if (header === null) return undefined;
+
+  let tree: unknown;
+  try {
+    tree = JSON.parse(decodeURIComponent(header));
+  } catch {
+    try {
+      tree = JSON.parse(header);
+    } catch {
+      return new Response('Internal Server Error', { status: 500 });
+    }
+  }
+  return isValidFlightRouterState(tree)
+    ? undefined
+    : new Response('Internal Server Error', { status: 500 });
+}
+
+/** The compat request interceptors this module owns, gated on compat.next. */
+export function protocolInterceptors(config: ResolvedConfig): RequestInterceptor[] {
+  if (!nextCompatEnabled(config)) return [];
+  return [routerStateTreeInterceptor];
+}
+
+/** The compat protocol finalizers, gated on compat.next. */
+export function protocolFinalizers(config: ResolvedConfig): ResponseFinalizer[] {
+  if (!nextCompatEnabled(config)) return [];
+  return [protocolFinalizer];
+}

package/src/compat/react/client.ts

@@ -0,0 +1,59 @@
+export {
+  Children,
+  Component,
+  Fragment,
+  PureComponent,
+  StrictMode,
+  Suspense,
+  SuspenseList,
+  cloneElement,
+  createContext,
+  createElement,
+  createFactory,
+  createPortal,
+  createRef,
+  default,
+  findDOMNode,
+  flushSync,
+  forwardRef,
+  hydrate,
+  isFragment,
+  isMemo,
+  isValidElement,
+  lazy,
+  memo,
+  render,
+  startTransition,
+  unmountComponentAtNode,
+  unstable_batchedUpdates,
+  useCallback,
+  useContext,
+  useDebugValue,
+  useDeferredValue,
+  useEffect,
+  useId,
+  useImperativeHandle,
+  useInsertionEffect,
+  useLayoutEffect,
+  useMemo,
+  useReducer,
+  useRef,
+  useState,
+  use,
+  useActionState,
+  useOptimistic,
+  useSyncExternalStore,
+  useTransition,
+  version,
+} from './preact';
+export { ViewTransition, addTransitionType } from './view-transition';
+
+export function cache<Args extends unknown[], Result>(
+  fn: (...args: Args) => Result,
+): (...args: Args) => Result {
+  return (...args: Args) => fn(...args);
+}
+
+export function cacheSignal() {
+  return null;
+}

package/src/compat/react/compiler-runtime.ts

@@ -0,0 +1,60 @@
+// React Compiler runtime shim (COMPAT).
+//
+// React Compiler-compiled code - both the app's own source and pre-compiled node_modules libraries -
+// imports the memo-cache helper `c` from `react/compiler-runtime` (React 19 built-in) or the standalone
+// `react-compiler-runtime` npm package (React 17/18 target).
+//
+// The npm `react-compiler-runtime` does `require('react')` and calls `React.useMemo`. Under pnext that
+// bare require resolves to the REAL react package, whose `useMemo` reads a null dispatcher during
+// preact's SSR and throws. So BOTH runtime specifiers are aliased to this shim, which implements the
+// identical memo-cache over preact's own `useMemo` - no real-react dependency, works in SSR and in the
+// browser.
+//
+// `c(size)` returns a per-render array seeded with a sentinel, exactly the fallback path in the upstream
+// runtime. The remaining exports are only emitted in development/validation builds; pnext ships the
+// production runtime, so they are minimal stubs to keep any stray import resolvable.
+
+import { useMemo } from 'preact/compat';
+
+const $empty = Symbol.for('react.memo_cache_sentinel');
+
+/** React Compiler memo-cache allocator (production fallback over preact useMemo). */
+export function c(size: number): unknown[] {
+  return useMemo<unknown[]>(() => {
+    const cache: unknown[] = new Array<unknown>(size);
+    for (let index = 0; index < size; index++) cache[index] = $empty;
+    (cache as unknown as Record<symbol, boolean>)[$empty] = true;
+    return cache;
+  }, []);
+}
+
+/** Reset a memo-cache array back to sentinels (dev-only in upstream). */
+export function $reset(cache: unknown[]): void {
+  for (let index = 0; index < cache.length; index++) cache[index] = $empty;
+}
+
+export function $makeReadOnly<T>(value: T): T {
+  return value;
+}
+
+// Dispatcher guards / structural check are dev-only validation hooks; ship as
+// no-ops so a stray import in a mixed build stays resolvable.
+export function $dispatcherGuard(_kind: number): void {
+  /* no-op: dev-only dispatcher guard */
+}
+
+export function $structuralCheck(): void {
+  /* no-op: dev-only structural equality check */
+}
+
+export const renderCounterRegistry = new Map<string, Set<{ count: number }>>();
+
+export function clearRenderCounterRegistry(): void {
+  for (const counters of renderCounterRegistry.values()) {
+    for (const counter of counters) counter.count = 0;
+  }
+}
+
+export function useRenderCounter(_name: string): void {
+  /* no-op: dev-only render counter */
+}

package/src/compat/react/dom-client.ts

@@ -0,0 +1,115 @@
+/**
+ * `react-dom` client-only compat surface.
+ *
+ * This variant omits any `request/context` dependency so esbuild can compile pure
+ * browser bundles. Resource hints are no-ops here; they are only meaningful in the
+ * server response-finalization pipeline.
+ */
+import ReactCompat from 'preact/compat';
+import { useActionState } from './preact';
+
+const ReactDomCompat = Object.assign(ReactCompat, {
+  preload,
+  preconnect,
+  prefetchDNS,
+  preinit,
+});
+
+export default ReactDomCompat;
+
+// The react-dom surface preact/compat provides (named, because preact/compat's
+// types use `export =` which blocks `export *`).
+export const render = ReactCompat.render;
+export const hydrate = ReactCompat.hydrate;
+export const createPortal = ReactCompat.createPortal;
+export const findDOMNode = ReactCompat.findDOMNode;
+export const flushSync = ReactCompat.flushSync;
+export const unmountComponentAtNode = ReactCompat.unmountComponentAtNode;
+export const unstable_batchedUpdates = ReactCompat.unstable_batchedUpdates;
+export const version = ReactCompat.version;
+
+function noOpRecordResourceHint() {
+  // intentionally empty: client bundles do not build response headers.
+}
+
+export function preload(_href: string, _options?: { as?: string; crossOrigin?: string }) {
+  noOpRecordResourceHint();
+  // no-op on client; header collection happens in server response finalizers.
+}
+
+export function preconnect(_href: string, _options?: { crossOrigin?: string }) {
+  noOpRecordResourceHint();
+  // no-op on client; header collection happens in server response finalizers.
+}
+
+export function prefetchDNS(_href: string) {
+  noOpRecordResourceHint();
+  // no-op on client; header collection happens in server response finalizers.
+}
+
+export function preinit(_href: string, _options?: { as?: string; crossOrigin?: string }) {
+  noOpRecordResourceHint();
+  // no-op on client; header collection happens in server response finalizers.
+}
+
+export const useFormState = useActionState;
+
+export interface FormStatusNotPending {
+  pending: false;
+  data: null;
+  method: null;
+  action: null;
+}
+
+export interface FormStatusPending {
+  pending: true;
+  data: FormData;
+  method: string;
+  action: string | ((formData: FormData) => void | Promise<void>);
+}
+
+export type FormStatus = FormStatusPending | FormStatusNotPending;
+
+const NOT_PENDING: FormStatusNotPending = {
+  pending: false,
+  data: null,
+  method: null,
+  action: null,
+};
+
+// Form-status store, fed by the client entry's function-form-action runtime.
+const pendingStack: FormStatusPending[] = [];
+const listeners = new Set<() => void>();
+let storeVersion = 0;
+
+/** Called by the client runtime when a function form action starts/finishes. */
+export function __pnextPushFormStatus(status: FormStatusPending): () => void {
+  pendingStack.push(status);
+  notify();
+  return () => {
+    const index = pendingStack.indexOf(status);
+    if (index !== -1) pendingStack.splice(index, 1);
+    notify();
+  };
+}
+
+function notify() {
+  storeVersion += 1;
+  for (const listener of [...listeners]) listener();
+}
+
+function subscribe(listener: () => void) {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function useFormStatus(): FormStatus {
+  ReactCompat.useSyncExternalStore(subscribe, () => storeVersion);
+  return pendingStack.length > 0 ? pendingStack[pendingStack.length - 1]! : NOT_PENDING;
+}
+
+export function requestFormReset(form: HTMLFormElement) {
+  if (form && typeof form.reset === 'function') form.reset();
+}

package/src/compat/react/dom-react-server.ts

@@ -0,0 +1,20 @@
+import ReactDomCompat, {
+  preconnect,
+  prefetchDNS,
+  preinit,
+  preload,
+  version,
+} from './dom';
+
+const ReactDomServer = { ...ReactDomCompat } as typeof ReactDomCompat & {
+  useFormState?: unknown;
+  useFormStatus?: unknown;
+  requestFormReset?: unknown;
+};
+
+delete ReactDomServer.useFormState;
+delete ReactDomServer.useFormStatus;
+delete ReactDomServer.requestFormReset;
+
+export { preconnect, prefetchDNS, preinit, preload, version };
+export default ReactDomServer;

package/src/compat/react/dom-server.ts

@@ -0,0 +1,40 @@
+/**
+ * `react-dom/server` compat surface (also aliased for `react-dom/server.edge`
+ * and `react-dom/server.browser`). Next fixtures import react-dom/server inside
+ * client components for the synchronous string renderers (renderToStaticMarkup,
+ * renderToString). preact-render-to-string provides those; the streaming
+ * server APIs (renderToReadableStream / renderToPipeableStream) have no direct
+ * preact equivalent that fits a browser bundle, so they throw if invoked.
+ */
+import ReactCompat from 'preact/compat';
+import {
+  renderToStaticMarkup as preactRenderToStaticMarkup,
+  renderToString as preactRenderToString,
+  renderToStringAsync as preactRenderToStringAsync,
+} from 'preact-render-to-string';
+
+export const version = ReactCompat.version;
+export const renderToString = preactRenderToString;
+export const renderToStaticMarkup = preactRenderToStaticMarkup;
+export const renderToStringAsync = preactRenderToStringAsync;
+
+function unsupportedStream(name: string): never {
+  throw new Error(`react-dom/server ${name} is not supported under pnext's preact runtime`);
+}
+
+export function renderToReadableStream(): never {
+  return unsupportedStream('renderToReadableStream');
+}
+
+export function renderToPipeableStream(): never {
+  return unsupportedStream('renderToPipeableStream');
+}
+
+export default {
+  version,
+  renderToString,
+  renderToStaticMarkup,
+  renderToStringAsync,
+  renderToReadableStream,
+  renderToPipeableStream,
+};

package/src/compat/react/dom.ts

@@ -0,0 +1,154 @@
+/**
+ * `react-dom` compat surface. preact/compat provides almost everything; this
+ * wrapper adds the form-action hooks React ships in react-dom:
+ *
+ * - useFormState: the deprecated alias of React.useActionState (identical
+ *   signature); implemented in ./preact.
+ * - useFormStatus: pending status of the nearest enclosing <form action={fn}>.
+ *   Approximated: the pnext client runtime reports in-flight function form
+ *   actions to a module store and the hook subscribes to it. When exactly one
+ *   submission is in flight (the overwhelmingly common case) the status is
+ *   exact; concurrent submissions from different forms all read as pending.
+ *   On the server it reports not-pending (matching React SSR).
+ * - requestFormReset: passthrough to form.reset(); the client runtime resets
+ *   uncontrolled forms after a successful action itself.
+ */
+import ReactCompat from 'preact/compat';
+import { useActionState } from './preact';
+import { registerResourceHint } from '../../render/resource-hints';
+
+const ReactDomCompat = Object.assign(ReactCompat, {
+  preload,
+  preconnect,
+  prefetchDNS,
+  preinit,
+});
+
+export default ReactDomCompat;
+
+// The react-dom surface preact/compat provides (named, because preact/compat's
+// types use `export =` which blocks `export *`).
+export const render = ReactCompat.render;
+export const hydrate = ReactCompat.hydrate;
+export const createPortal = ReactCompat.createPortal;
+export const findDOMNode = ReactCompat.findDOMNode;
+export const flushSync = ReactCompat.flushSync;
+export const unmountComponentAtNode = ReactCompat.unmountComponentAtNode;
+export const unstable_batchedUpdates = ReactCompat.unstable_batchedUpdates;
+export const version = ReactCompat.version;
+
+export function preload(
+  href: string,
+  options?: {
+    as?: string;
+    crossOrigin?: string;
+    type?: string;
+    fetchPriority?: string;
+    media?: string;
+    nonce?: string;
+  },
+) {
+  registerResourceHint({
+    rel: 'preload',
+    url: href,
+    ...(options?.as ? { as: options.as } : {}),
+    ...(options?.type ? { type: options.type } : {}),
+    ...(options?.fetchPriority
+      ? { fetchPriority: options.fetchPriority as 'high' | 'low' | 'auto' }
+      : {}),
+    ...(options?.media ? { media: options.media } : {}),
+    ...(options?.nonce ? { nonce: options.nonce } : {}),
+    ...(options?.crossOrigin
+      ? { crossOrigin: options.crossOrigin as 'anonymous' | 'use-credentials' | '' }
+      : {}),
+  });
+}
+
+export function preconnect(href: string, options?: { crossOrigin?: string }) {
+  registerResourceHint({
+    rel: 'preconnect',
+    url: href,
+    ...(options?.crossOrigin
+      ? { crossOrigin: options.crossOrigin as 'anonymous' | 'use-credentials' | '' }
+      : {}),
+  });
+}
+
+export function prefetchDNS(href: string) {
+  registerResourceHint({ rel: 'dns-prefetch', url: href });
+}
+
+export function preinit(href: string, options?: { as?: string; crossOrigin?: string }) {
+  registerResourceHint({
+    rel: 'preload',
+    url: href,
+    ...(options?.as ? { as: options.as } : {}),
+    ...(options?.crossOrigin
+      ? { crossOrigin: options.crossOrigin as 'anonymous' | 'use-credentials' | '' }
+      : {}),
+  });
+}
+
+export const useFormState = useActionState;
+
+export interface FormStatusNotPending {
+  pending: false;
+  data: null;
+  method: null;
+  action: null;
+}
+
+export interface FormStatusPending {
+  pending: true;
+  data: FormData;
+  method: string;
+  action: string | ((formData: FormData) => void | Promise<void>);
+}
+
+export type FormStatus = FormStatusPending | FormStatusNotPending;
+
+const NOT_PENDING: FormStatusNotPending = {
+  pending: false,
+  data: null,
+  method: null,
+  action: null,
+};
+
+// Form-status store, fed by the client entry's function-form-action runtime.
+const pendingStack: FormStatusPending[] = [];
+const listeners = new Set<() => void>();
+let storeVersion = 0;
+
+/** Called by the client runtime when a function form action starts/finishes. */
+export function __pnextPushFormStatus(status: FormStatusPending): () => void {
+  pendingStack.push(status);
+  notify();
+  return () => {
+    const index = pendingStack.indexOf(status);
+    if (index !== -1) pendingStack.splice(index, 1);
+    notify();
+  };
+}
+
+function notify() {
+  storeVersion += 1;
+  for (const listener of [...listeners]) listener();
+}
+
+function subscribe(listener: () => void) {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function useFormStatus(): FormStatus {
+  ReactCompat.useSyncExternalStore(subscribe, () => storeVersion);
+  return pendingStack.length > 0 ? pendingStack[pendingStack.length - 1]! : NOT_PENDING;
+}
+
+export function requestFormReset(form: HTMLFormElement) {
+  if (form && typeof form.reset === 'function') form.reset();
+}
+
+Object.assign(ReactDomCompat, { useFormState, useFormStatus, requestFormReset });