@wular/pnext 0.0.1

package/src/compat/actions/action-router.ts

@@ -0,0 +1,40 @@
+// Installs the client-side server-action machinery for Next-compat entries:
+// - `window.__PNEXT_ROUTER__`: minimal navigate/refresh global bridging the soft-navigation runtime,
+//   used after action redirects and refresh signals.
+// - `window.__PNEXT_ACTIONS__`: the action RPC runtime - argument encoding, the POST wire,
+//   redirect/refresh/error semantics, island prop revival, and <form action={fn}> interception.
+// Only imported into client entries when Next compat is enabled.
+
+import { softNavigate } from '../../api/router';
+import { installActionRuntime } from './action-client';
+
+interface PNextRouterGlobal {
+  navigate: (href: string) => Promise<void>;
+  refresh: () => Promise<void>;
+}
+
+declare global {
+  interface Window {
+    __PNEXT_ROUTER__?: PNextRouterGlobal;
+  }
+}
+
+export function installActionRouter() {
+  if (!process.browser && typeof window === 'undefined') return;
+  installActionRuntime();
+  const existing = window.__PNEXT_ROUTER__;
+  if (
+    existing &&
+    typeof existing.navigate === 'function' &&
+    typeof existing.refresh === 'function'
+  ) {
+    return;
+  }
+  window.__PNEXT_ROUTER__ = {
+    navigate: (href: string) => softNavigate(href),
+    // A refresh re-fetches the current URL and swaps the body in place, which
+    // re-runs the server render (picking up any revalidated data). replace:true
+    // keeps history intact; scroll:false avoids jumping to the top.
+    refresh: () => softNavigate(location.href, { replace: true, scroll: false }),
+  };
+}

package/src/compat/actions/action-shared.ts

@@ -0,0 +1,95 @@
+/**
+ * The sliver of the client action runtime both tiers need: the install-time half (action-client.ts)
+ * and the dispatch half (action-dispatch.ts, loaded on the first action call). Keep this module small
+ * - every byte here ships at first paint on any page that uses a server action.
+ */
+import type { ComponentType } from 'preact';
+
+// Progressive-enhancement form fields: written by the server renderer, read by
+// the submit listener (initial) and stripped off the wire by the encoder.
+export const ACTION_ID_FIELD = '$pnext_action_id';
+export const SUBMIT_ACTION_ID_FIELD = '$pnext_submit_action_id';
+export const FORM_STATE_FIELD = '$pnext_form_state';
+
+// Binary wire markers: encoded by the dispatch half, revived by both (island
+// props can carry typed arrays before any action has run).
+export const TYPED_ARRAY_MARKER = '$$pnext_typed_array';
+export const ARRAY_BUFFER_MARKER = '$$pnext_array_buffer';
+
+export interface ActionFunction {
+  (...args: unknown[]): Promise<unknown>;
+  $$pnextActionId?: string;
+}
+
+export interface ActionRuntime {
+  call(id: string, args: unknown[]): Promise<unknown>;
+  createAction(id: string): ActionFunction;
+  registerClientReference(id: string, component: ComponentType<Record<string, unknown>>): void;
+  reviveProps<T>(value: T): T;
+}
+
+declare global {
+  interface Window {
+    __PNEXT_ACTIONS__?: ActionRuntime;
+  }
+}
+
+interface PNextActionError extends Error {
+  $$pnextActionError?: boolean;
+}
+
+export function tagActionError(error: unknown): unknown {
+  if (error instanceof Error) (error as PNextActionError).$$pnextActionError = true;
+  return error;
+}
+
+/** True for errors produced by an action dispatch (boundary channel filter). */
+export function isActionError(error: unknown): boolean {
+  return Boolean(error instanceof Error && (error as PNextActionError).$$pnextActionError);
+}
+
+/** Client components an action return may reference by id (element markers). */
+export const actionReturnClientReferences = new Map<
+  string,
+  ComponentType<Record<string, unknown>>
+>();
+
+const TYPED_ARRAY_CTORS: Record<string, new (buffer: ArrayBuffer) => ArrayBufferView> = {
+  Int8Array,
+  Uint8Array,
+  Uint8ClampedArray,
+  Int16Array,
+  Uint16Array,
+  Int32Array,
+  Uint32Array,
+  Float32Array,
+  Float64Array,
+  BigInt64Array,
+  BigUint64Array,
+};
+
+export function base64ToArrayBuffer(base64: string): ArrayBuffer {
+  if (typeof atob === 'function') {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    return bytes.buffer;
+  }
+  const buf = Buffer.from(base64, 'base64');
+  return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+}
+
+/** Revive a typed-array / ArrayBuffer wire marker, else undefined. */
+export function reviveBinaryMarker(record: Record<string, unknown>): unknown {
+  const typed = record[TYPED_ARRAY_MARKER];
+  if (typed && typeof typed === 'object') {
+    const { type, data } = typed as { type?: string; data?: string };
+    const Ctor = type ? TYPED_ARRAY_CTORS[type] : undefined;
+    if (Ctor && typeof data === 'string') {
+      return new Ctor(base64ToArrayBuffer(data));
+    }
+  }
+  const buffer = record[ARRAY_BUFFER_MARKER];
+  if (typeof buffer === 'string') return base64ToArrayBuffer(buffer);
+  return undefined;
+}

package/src/compat/actions/client-plugin.ts

@@ -0,0 +1,135 @@
+import path from 'node:path';
+import { realpathSync } from 'node:fs';
+import type { Plugin } from 'esbuild';
+import { readText } from '../../utils/fs';
+import { escapeRegex } from '../../utils/source';
+import { actionId } from './ids';
+import { moduleActionExports, moduleLevelUseCache, moduleLevelUseServer } from './detect';
+import { clientStubSource } from './client-stub';
+
+/**
+ * Process-level set of `'use server'` module source paths (absolute) that the
+ * client bundler must replace with the generated RPC stub. Populated by the
+ * build/dev discovery pass before client bundling runs, and consulted by the
+ * esbuild plugin below (wired through compatAliasPlugin so it participates in
+ * every client build without editing the client build pipeline directly).
+ *
+ * Keyed by the workspace/project root the ids were computed against so the stub
+ * emits ids that match the server registry.
+ */
+interface ClientActionState {
+  root: string;
+  /** Original (as-discovered) absolute paths — used for import identity. */
+  files: Set<string>;
+  /** Realpath-canonical paths — used to match esbuild's resolved paths. */
+  canonicalFiles: Set<string>;
+}
+
+let clientActionState: ClientActionState | undefined;
+
+export function setClientActionModules(root: string, files: Iterable<string>) {
+  const originals = new Set<string>();
+  const canonicalFiles = new Set<string>();
+  for (const file of files) {
+    originals.add(path.resolve(file));
+    canonicalFiles.add(canonical(file));
+  }
+  clientActionState =
+    originals.size > 0 ? { root, files: originals, canonicalFiles } : undefined;
+}
+
+// esbuild reports resolved paths through the OS realpath (e.g. /private on
+// macOS), so both the stored set and the lookup canonicalize to match. Also
+// used for id computation so the build, the client stub, and the render-side
+// form tagging all derive the same wire id from the same (realpath) basis.
+export function canonical(file: string) {
+  const abs = path.resolve(file);
+  try {
+    return realpathSync.native(abs);
+  } catch {
+    return abs;
+  }
+}
+
+export function clearClientActionModules() {
+  clientActionState = undefined;
+}
+
+export function hasClientActionModules() {
+  return clientActionState !== undefined && clientActionState.files.size > 0;
+}
+
+function isActionModule(file: string) {
+  if (!clientActionState) return false;
+  // Match both the original and the realpath-canonical form: render passes the
+  // original path; esbuild passes the realpath.
+  return (
+    clientActionState.files.has(path.resolve(file)) ||
+    clientActionState.canonicalFiles.has(canonical(file))
+  );
+}
+
+/** True when `file` is a discovered client-replaced action module. */
+export function isClientActionModule(file: string) {
+  return isActionModule(file);
+}
+
+/** Root the client action ids were computed against (for stub id parity). */
+export function clientActionModulesRoot() {
+  return clientActionState?.root;
+}
+
+/** All discovered action module source paths (absolute). */
+export function clientActionModuleFiles(): string[] {
+  return clientActionState ? [...clientActionState.files] : [];
+}
+
+/** Generate the client fetch-stub source for an action module file. */
+export function actionStubSourceFor(file: string, root?: string) {
+  return stubSourceFor(file, root ?? clientActionState?.root);
+}
+
+/**
+ * esbuild plugin that swaps a client import of a `'use server'` module for the generated fetch stub.
+ * It hooks LOAD, not resolve: the filter is the exact discovered action paths, so esbuild's own
+ * resolver decides what a specifier points at and this plugin only sees the handful of files it
+ * replaces. A catch-all onResolve here used to re-resolve every import in the graph through
+ * `build.resolve`, and perturbed esbuild's CJS-interop decisions on the way.
+ */
+export function actionClientStubPlugin(): Plugin {
+  const paths = clientActionState
+    ? [...clientActionState.files, ...clientActionState.canonicalFiles]
+    : [];
+  const filter = new RegExp(`^(?:${[...new Set(paths)].map(escapeRegex).join('|')})$`);
+  return {
+    name: 'pnext-action-client-stub',
+    setup(build) {
+      if (paths.length === 0) return;
+      build.onLoad({ filter, namespace: 'file' }, async args => {
+        if (!isActionModule(args.path)) return undefined;
+        return {
+          contents: await stubSourceFor(args.path, clientActionState?.root),
+          loader: 'js',
+        };
+      });
+    },
+  };
+}
+
+async function stubSourceFor(file: string, root?: string) {
+  const source = await readText(file);
+  if (!moduleLevelUseServer(source) && !moduleLevelUseCache(source)) return 'export {};';
+  const exports = moduleActionExports(source);
+  const actionIds: Record<string, string> = {};
+  for (const name of exports) actionIds[name] = canonicalActionId(file, name, root);
+  return clientStubSource({ modulePath: file, exports, actionIds });
+}
+
+/**
+ * Compute an action wire id from a realpath-canonical (file, root) basis so every producer -
+ * discovery/registry, the client stub, and render-side form tagging - agrees regardless of
+ * symlink/realpath differences (e.g. /private on macOS temp dirs).
+ */
+export function canonicalActionId(file: string, exportName: string, root?: string): string {
+  return actionId(canonical(file), exportName, root ? canonical(root) : undefined);
+}

package/src/compat/actions/client-stub.ts

@@ -0,0 +1,65 @@
+/**
+ * Description of one action module, as the discovery pass hands it to the stub
+ * generator: the module's path (for reference/debug), the action export names,
+ * and the precomputed wire id for each.
+ */
+export interface ClientStubModule {
+  modulePath: string;
+  exports: readonly string[];
+  actionIds: Record<string, string>;
+}
+
+/**
+ * Generate the CLIENT stub SOURCE for a server-action module. On the client, a `'use server'` import
+ * is replaced by this module: each export becomes an async function that dispatches through the shared
+ * pnext action runtime, installed on `window.__PNEXT_ACTIONS__` by the client entry before any user
+ * interaction can call an action.
+ *
+ * The runtime owns argument encoding, the POST to the current page URL with the next-action header,
+ * and redirect/refresh/error handling, keeping every stub tiny. The generated source is a
+ * self-contained ES module with no imports, so it can be emitted to disk and bundled as-is.
+ */
+export function clientStubSource(module: ClientStubModule): string {
+  const lines: string[] = [];
+
+  lines.push(`// Generated pnext server-action client stub.`);
+  lines.push(`// Module: ${sanitizeComment(module.modulePath)}`);
+  lines.push(RUNTIME);
+
+  for (const name of module.exports) {
+    const id = module.actionIds[name];
+    if (!id) continue;
+    const decl = name === 'default' ? 'export default' : `export const ${name} =`;
+    lines.push(`${decl} __pnextAction(${JSON.stringify(id)});`);
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+const RUNTIME = `
+function __pnextAction(id) {
+  const action = async function (...args) {
+    const runtime = (process.browser || typeof window !== 'undefined') ? window.__PNEXT_ACTIONS__ : undefined;
+    if (runtime) {
+      return runtime.call(id, args);
+    }
+    // Called on the SERVER: a client-imported 'use server' function invoked during a server
+    // render/action (a bound action a client page's useActionState registered, dispatched in the no-JS
+    // progressive path). Route it through the endpoint's server-side dispatcher, which resolves the id
+    // to the real compiled action and runs it in the active request scope, instead of throwing as if
+    // the browser runtime were missing.
+    const server =
+      typeof globalThis !== 'undefined' ? globalThis.__PNEXT_SERVER_ACTIONS__ : undefined;
+    if (server) {
+      return server.call(id, args);
+    }
+    throw new Error('pnext action runtime is not installed (is Next compat enabled?)');
+  };
+  action.$$pnextActionId = id;
+  return action;
+}
+`;
+
+function sanitizeComment(value: string): string {
+  return value.replace(/\*\//g, '*\\/').replace(/[\r\n]/g, ' ');
+}

package/src/compat/actions/config.ts

@@ -0,0 +1,164 @@
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathToFileHref } from '../../config';
+import { DEFAULT_BODY_LIMIT_BYTES } from './endpoint';
+
+/**
+ * Server-actions options read from the app's next.config in compat mode:
+ * `experimental.serverActions.bodySizeLimit` (also accepted at the top-level `serverActions` key,
+ * where newer Next versions moved it). Invalid limits fail server startup with Next's exact error
+ * message - the size-limit e2e suite asserts the text.
+ */
+export const SIZE_LIMIT_ERROR =
+  'Server Actions Size Limit must be a valid number or filesize format larger than 1MB';
+
+export interface ServerActionsConfig {
+  bodySizeLimitBytes: number;
+}
+
+export interface NextConfigShape {
+  serverActions?: { bodySizeLimit?: unknown };
+  experimental?: { serverActions?: { bodySizeLimit?: unknown } | boolean };
+  rewrites?: () => unknown;
+  redirects?: () => unknown;
+}
+
+export async function loadServerActionsConfig(root: string): Promise<ServerActionsConfig> {
+  const config = await loadResolvedNextConfig(root);
+  const experimental = config?.experimental;
+  const limit =
+    config?.serverActions?.bodySizeLimit ??
+    (experimental && typeof experimental === 'object' && experimental.serverActions
+      ? (experimental.serverActions as { bodySizeLimit?: unknown }).bodySizeLimit
+      : undefined);
+  if (limit === undefined) return { bodySizeLimitBytes: DEFAULT_BODY_LIMIT_BYTES };
+  return { bodySizeLimitBytes: parseBodySizeLimit(limit) };
+}
+
+export async function loadResolvedNextConfig(root: string): Promise<NextConfigShape | undefined> {
+  return (await loadNextConfigFromStore()) ?? (await loadNextConfig(root));
+}
+
+/**
+ * Read the next.config already loaded by the compat config-loader. At runtime that loader has bundled
+ * the app's config with esbuild and stored the fully-evaluated object, so it reflects every authoring
+ * style (CJS/ESM/TS) correctly. Prefer it over re-importing next.config.js here: a bare import() of a
+ * CommonJS config runs through pnext's runtime module hooks and comes back as an empty object, which
+ * silently dropped the configured bodySizeLimit. Returns undefined when the store is empty so the
+ * caller falls back to a direct file read.
+ */
+async function loadNextConfigFromStore(): Promise<NextConfigShape | undefined> {
+  try {
+    const { getNextConfig } = await import('../next/config-loader');
+    const store: NextConfigShape = getNextConfig();
+    return store && Object.keys(store).length > 0 ? store : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function loadNextConfig(root: string): Promise<NextConfigShape | undefined> {
+  for (const name of ['next.config.js', 'next.config.mjs', 'next.config.cjs']) {
+    const file = path.join(root, name);
+    if (!existsSync(file)) continue;
+    try {
+      if (name.endsWith('.js') || name.endsWith('.cjs')) {
+        const requireFrom = createRequire(path.join(root, 'noop.js'));
+        delete requireFrom.cache[requireFrom.resolve(file)];
+        const required: unknown = requireFrom(file);
+        let value =
+          required && typeof required === 'object' && 'default' in required
+            ? required.default
+            : required;
+        if (typeof value === 'function') {
+          value = await (value as (phase: string, ctx: { defaultConfig: object }) => unknown)(
+            'phase-production-server',
+            { defaultConfig: {} },
+          );
+        }
+        return value ?? undefined;
+      }
+      const loaded = (await import(`${pathToFileHref(file)}?v=${Date.now()}`)) as {
+        default?: unknown;
+      };
+      let value: unknown = loaded.default ?? loaded;
+      if (typeof value === 'function') {
+        value = await (value as (phase: string, ctx: { defaultConfig: object }) => unknown)(
+          'phase-production-server',
+          { defaultConfig: {} },
+        );
+      }
+      return (value ?? undefined);
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Startup validation of `serverActions.bodySizeLimit`, matching Next's behavior of failing start (and
+ * build) with the exact size-limit error when the configured limit is malformed - the suite asserts
+ * the message on cliOutput, before any action request is made.
+ *
+ * Loads the app's CommonJS next.config synchronously (createRequire) so an invalid limit throws inline
+ * from the init hook. ESM-only configs and configs that fail to load for any unrelated reason are
+ * skipped here - the lazy per-request path still validates.
+ */
+export function validateServerActionsConfigSync(root: string): void {
+  let config: NextConfigShape | undefined;
+  const requireFrom = createRequire(path.join(root, 'noop.js'));
+  for (const name of ['next.config.js', 'next.config.cjs']) {
+    const file = path.join(root, name);
+    if (!existsSync(file)) continue;
+    try {
+      delete requireFrom.cache[requireFrom.resolve(file)];
+      let value: unknown = requireFrom(file);
+      if (value && typeof value === 'object' && 'default' in value) {
+        value = (value as { default?: unknown }).default;
+      }
+      if (typeof value === 'function') {
+        value = (value as (phase: string, ctx: { defaultConfig: object }) => unknown)(
+          'phase-production-server',
+          { defaultConfig: {} },
+        );
+      }
+      config = value as NextConfigShape | undefined;
+    } catch (error) {
+      // A malformed limit surfaced synchronously from require's module eval is
+      // unlikely; any load failure means we can't validate here — defer.
+      if (error instanceof Error && error.message === SIZE_LIMIT_ERROR) throw error;
+      return;
+    }
+    break;
+  }
+  if (!config) return;
+  const experimental = config.experimental;
+  const limit =
+    config.serverActions?.bodySizeLimit ??
+    (experimental && typeof experimental === 'object' && experimental.serverActions
+      ? (experimental.serverActions as { bodySizeLimit?: unknown }).bodySizeLimit
+      : undefined);
+  if (limit === undefined) return;
+  parseBodySizeLimit(limit);
+}
+
+/** Parse '2mb' / '500kb' / bytes number into bytes; throw SIZE_LIMIT_ERROR. */
+export function parseBodySizeLimit(value: unknown): number {
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value) || value <= 0) throw new Error(SIZE_LIMIT_ERROR);
+    return Math.floor(value);
+  }
+  if (typeof value === 'string') {
+    const match = /^(\d+(?:\.\d+)?)\s*(b|kb|mb|gb)?$/i.exec(value.trim());
+    if (!match) throw new Error(SIZE_LIMIT_ERROR);
+    const amount = Number(match[1]);
+    if (!Number.isFinite(amount) || amount <= 0) throw new Error(SIZE_LIMIT_ERROR);
+    const unit = (match[2] ?? 'b').toLowerCase();
+    const factor =
+      unit === 'gb' ? 1024 ** 3 : unit === 'mb' ? 1024 ** 2 : unit === 'kb' ? 1024 : 1;
+    return Math.floor(amount * factor);
+  }
+  throw new Error(SIZE_LIMIT_ERROR);
+}