@wular/pnext 0.0.1

package/src/compat/metadata.ts

@@ -0,0 +1,295 @@
+import type {
+  Metadata,
+  MetadataOpenGraph,
+  PageProps,
+  RouteManifestEntry,
+  Viewport,
+} from '../types';
+import { staticMetadataForPathFromFiles, type StaticMetadataFile } from '../routing/metadata';
+import { coerceString } from '../render/metadata';
+import { readSourceText } from '../resolve/source-text';
+import { SPAN_TYPE, withChildSpan } from './otel/tracer';
+import { settledPromise } from '../render/renderer';
+import {
+  createVaryingParams,
+  createVaryingSearchParams,
+  getMetadataVaryParamsAccumulator,
+  varyTrackingInfo,
+  type VaryTrackingInfo,
+} from './segment/vary-params';
+
+type NextGenerateMetadata = (
+  props: Pick<PageProps, 'params' | 'searchParams'>,
+  parent: Promise<Metadata>,
+) => Metadata | Promise<Metadata>;
+
+type NextGenerateViewport = (
+  props: Pick<PageProps, 'params' | 'searchParams'>,
+) => Viewport | Promise<Viewport>;
+
+export async function readNextModuleMetadata(
+  module: Record<string, unknown>,
+  props: PageProps,
+  parent: Metadata,
+  modulePath?: string,
+): Promise<Metadata | undefined> {
+  if (typeof module.generateMetadata === 'function') {
+    const generate = module.generateMetadata as NextGenerateMetadata;
+    // `generateMetadata <page>` OTel span (ResolveMetadata.generateMetadata),
+    // named by the route-relative module path (e.g. `/app/[param]/layout`).
+    // Inert when otel-api is unavailable or no root span is open.
+    const headProps = headVaryTrackedProps(props);
+    const run = () =>
+      generate(
+        { params: headProps.params, searchParams: headProps.searchParams },
+        Promise.resolve(resolvedParentMetadata(parent)),
+      );
+    const name = metadataSpanName(modulePath);
+    return await (name
+      ? withChildSpan(
+          name,
+          SPAN_TYPE.generateMetadata,
+          { 'next.page': name.slice('generateMetadata '.length) },
+          run,
+        )
+      : run());
+  }
+  return module.metadata as Metadata | undefined;
+}
+
+// Route-relative module path for a `generateMetadata` span name: an absolute `<root>/app/[param]/
+// layout.tsx` becomes `generateMetadata /app/[param]/layout`. Next names the span with the app-dir-
+// relative path prefixed by the `/app` segment. Returns undefined when the path cannot be derived, in
+// which case the span is skipped rather than failing.
+function metadataSpanName(modulePath: string | undefined): string | undefined {
+  if (!modulePath) return undefined;
+  const normalized = modulePath.replace(/\\/g, '/').replace(/\.[cm]?[jt]sx?$/, '');
+  // Keep everything from the LAST `/app/` segment onward (handles src/app too).
+  const idx = normalized.lastIndexOf('/app/');
+  const rel = idx >= 0 ? normalized.slice(idx) : `/${normalized.replace(/^\/+/, '')}`;
+  return `generateMetadata ${rel}`;
+}
+
+export async function readNextModuleViewport(
+  module: Record<string, unknown>,
+  props: PageProps,
+): Promise<Viewport | undefined> {
+  if (typeof module.generateViewport === 'function') {
+    const headProps = headVaryTrackedProps(props);
+    return (module.generateViewport as NextGenerateViewport)({
+      params: headProps.params,
+      searchParams: headProps.searchParams,
+    });
+  }
+  return module.viewport as Viewport | undefined;
+}
+
+/**
+ * `generateMetadata` / `generateViewport` param access accrues to the HEAD segment's vary set, never the
+ * page's - a page that shares one payload across params but whose metadata reads `params.id` must keep
+ * the head keyed per id while the body stays shared.
+ *
+ * The incoming props already carry the PAGE's tracking view; re-wrap the raw object behind it against
+ * the head accumulator so reading here never widens the page's set. Untracked or hanging
+ * (fallback-shell) props pass through untouched - a hanging promise must keep its identity so the
+ * postpone machinery still sees it.
+ */
+function headVaryTrackedProps(props: PageProps): Pick<PageProps, 'params' | 'searchParams'> {
+  const head = getMetadataVaryParamsAccumulator();
+  if (!head) return { params: props.params, searchParams: props.searchParams };
+  return {
+    params: retrackSettled(props.params, (raw, info) =>
+      createVaryingParams(head, raw, info.optionalCatchAllParam),
+    ),
+    searchParams: retrackSettled(props.searchParams, raw => createVaryingSearchParams(head, raw)),
+  };
+}
+
+/**
+ * Re-wrap a SETTLED params/searchParams promise around a fresh tracking view
+ * built from the ORIGINAL object behind it. Anything else (a hanging promise, an
+ * untracked value) is returned as-is.
+ */
+function retrackSettled<T extends Record<string, unknown>>(
+  promise: Promise<T>,
+  wrap: (raw: T, info: VaryTrackingInfo) => T,
+): Promise<T> {
+  const settled = promise as Promise<T> & { status?: string; value?: T };
+  if (settled.status !== 'fulfilled' || settled.value === undefined) return promise;
+  const info = varyTrackingInfo(settled.value);
+  if (!info) return promise;
+  return settledPromise(wrap(info.raw as T, info));
+}
+
+export function hasRuntimeMetadata(module: Record<string, unknown>) {
+  return typeof module.generateMetadata === 'function';
+}
+
+export function shouldRenderMetadataInBody({
+  config,
+  request,
+}: {
+  config: { htmlLimitedBots?: RegExp };
+  request?: Request;
+}) {
+  const userAgent = request?.headers.get('user-agent') ?? '';
+  const limitedBot =
+    config.htmlLimitedBots ??
+    /Twitterbot|Slackbot|Bingbot|Discordbot|LinkedInBot|Google-PageRenderer|Chrome-Lighthouse|Lighthouse/i;
+  return !limitedBot.test(userAgent);
+}
+
+function resolvedParentMetadata(parent: Metadata): Metadata {
+  return {
+    ...parent,
+    metadataBase: parent.metadataBase === undefined ? undefined : coerceString(parent.metadataBase),
+    keywords: normalizeKeywordList(parent.keywords),
+    openGraph: resolvedParentOpenGraph(parent.openGraph),
+    twitter: parent.twitter ?? {},
+    robots: parent.robots ?? {},
+    alternates: parent.alternates ?? {},
+    icons: parent.icons ?? {},
+  };
+}
+
+function resolvedParentOpenGraph(openGraph: MetadataOpenGraph | undefined): MetadataOpenGraph {
+  if (!openGraph) return {};
+  return {
+    ...openGraph,
+    title:
+      openGraph.title === undefined ||
+      (typeof openGraph.title === 'object' && openGraph.title !== null)
+        ? openGraph.title
+        : { absolute: coerceString(openGraph.title) },
+    images:
+      openGraph.images === undefined
+        ? []
+        : Array.isArray(openGraph.images)
+          ? openGraph.images
+          : [openGraph.images],
+  };
+}
+
+function normalizeKeywordList(value: Metadata['keywords']): (string | number)[] | undefined {
+  if (value === undefined) return undefined;
+  return Array.isArray(value) ? value : [value];
+}
+
+export async function warnNextMetadataBuildIssues(
+  appPath: string,
+  routes: RouteManifestEntry[],
+  staticMetadataFiles: StaticMetadataFile[],
+) {
+  const warned = new Set<string>();
+  // A route's own file plus its layout chain: on a 23-route app with one shell
+  // that is the same handful of layouts 23 times over. Each file's four verdicts
+  // are derived once and reused, and the reads come from the build's shared
+  // source cache (the route-fact walk has already read every one of them).
+  const facts = new Map<string, MetadataSourceFacts>();
+  const factsFor = async (file: string) => {
+    let cached = facts.get(file);
+    if (!cached) {
+      cached = metadataSourceFacts(await readSourceTextOrEmpty(file));
+      facts.set(file, cached);
+    }
+    return cached;
+  };
+  for (const route of routes) {
+    if (route.kind !== 'page') continue;
+    const routeFacts = await Promise.all(routeSourceFiles(appPath, route).map(factsFor));
+    const some = (pick: (fact: MetadataSourceFacts) => boolean) => routeFacts.some(pick);
+    if (some(fact => fact.themeColor)) {
+      warnOnce(
+        warned,
+        `themeColor:${route.route}`,
+        `Unsupported metadata themeColor is configured in metadata export in ${route.route || '/'}. Please move it to viewport\nRead more: https://nextjs.org/docs/app/api-reference/functions/generate-viewport`,
+      );
+    }
+    if (some(fact => fact.appleTouchFullscreen)) {
+      warnOnce(
+        warned,
+        'apple-touch-fullscreen',
+        'Unsupported metadata other.apple-touch-fullscreen is configured in metadata export. Use appleWebApp instead.',
+      );
+    }
+    if (some(fact => fact.appleTouchIconPrecomposed)) {
+      warnOnce(
+        warned,
+        'apple-touch-icon-precomposed',
+        'Unsupported metadata other.apple-touch-icon-precomposed is configured in metadata export. Use icons.apple instead.',
+      );
+    }
+    if (
+      !some(fact => fact.metadataBase) &&
+      routeUsesRelativeSocialImage(route, routeFacts, staticMetadataFiles)
+    ) {
+      warnOnce(
+        warned,
+        'metadataBase',
+        'metadataBase property in metadata export is not set for resolving social open graph or twitter images, using "http://localhost:3000". See https://nextjs.org/docs/app/api-reference/functions/generate-metadata#metadatabase',
+      );
+    }
+  }
+}
+
+/** The app-dir files whose metadata exports apply to this route. */
+function routeSourceFiles(appPath: string, route: RouteManifestEntry) {
+  const root = `${appPath}/`;
+  return route.sourceFiles.filter(file => file === appPath || file.startsWith(root));
+}
+
+async function readSourceTextOrEmpty(file: string) {
+  try {
+    return await readSourceText(file);
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Every metadata verdict this pass needs from one source file. The substring
+ * gates run first: a regex over the whole source costs ~40x a `includes`, and
+ * nearly every file has none of these keys.
+ */
+interface MetadataSourceFacts {
+  themeColor: boolean;
+  appleTouchFullscreen: boolean;
+  appleTouchIconPrecomposed: boolean;
+  metadataBase: boolean;
+  relativeSocialImage: boolean;
+}
+
+function metadataSourceFacts(source: string): MetadataSourceFacts {
+  return {
+    themeColor: source.includes('themeColor') && /\bthemeColor\s*:/.test(source),
+    appleTouchFullscreen:
+      source.includes('apple-touch-fullscreen') && /['"]apple-touch-fullscreen['"]/.test(source),
+    appleTouchIconPrecomposed:
+      source.includes('apple-touch-icon-precomposed') &&
+      /['"]apple-touch-icon-precomposed['"]/.test(source),
+    metadataBase: source.includes('metadataBase') && /\bmetadataBase\s*:/.test(source),
+    relativeSocialImage: hasRelativeSocialImage(source),
+  };
+}
+
+function routeUsesRelativeSocialImage(
+  route: RouteManifestEntry,
+  facts: MetadataSourceFacts[],
+  staticMetadataFiles: StaticMetadataFile[],
+) {
+  if (facts.some(fact => fact.relativeSocialImage)) return true;
+  if (route.params.length > 0) return false;
+  const staticMetadata = staticMetadataForPathFromFiles(staticMetadataFiles, route.route);
+  return Boolean(staticMetadata.openGraphImage || staticMetadata.twitterImage);
+}
+
+function hasRelativeSocialImage(source: string) {
+  if (!source.includes('images')) return false;
+  return /(?:openGraph|twitter)\s*:\s*\{[\s\S]*?\bimages\s*:\s*['"`](?:\/|\.\.?\/)/m.test(source);
+}
+
+function warnOnce(warned: Set<string>, key: string, message: string) {
+  if (warned.has(key)) return;
+  warned.add(key);
+  console.warn(message);
+}

package/src/compat/middleware/manifest.ts

@@ -0,0 +1,210 @@
+// Middleware manifest emission (COMPAT - may import core freely).
+//
+// Writes the two Next-shaped manifests a few suites read directly from the build output:
+//   - `<out>/server/middleware-manifest.json`: the edge-middleware entry with its compiled matchers,
+//     entrypoint and files list.
+//   - `<out>/server/functions-config-manifest.json`: the node-runtime variant, when the middleware opts
+//     into `runtime: 'nodejs'`.
+//
+// Only the fields the tests read are populated. A pure-core app writes neither.
+
+import path from 'node:path';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { findProxyFile, type ProxyConfig, type ProxyModule } from '../../proxy';
+import { pathToFileHref, type ResolvedConfig } from '../../config';
+import { toPosixPath } from '../../utils/fs';
+import type { RouteManifestEntry } from '../../types';
+import { readMiddlewareWasmBindingsForOutPath } from '../bundler/wasm';
+import { preferredRegionForRoute } from '../next/preferred-region';
+
+interface ManifestMatcher {
+  regexp: string;
+  originalSource: string;
+}
+
+interface MiddlewareEntry {
+  name: string;
+  page: string;
+  matchers: ManifestMatcher[];
+  wasm: { name: string; filePath: string }[];
+  assets: never[];
+  files: string[];
+  entrypoint: string;
+  env: Record<string, string>;
+}
+
+interface MiddlewareManifest {
+  version: number;
+  sortedMiddleware: string[];
+  middleware: Record<string, MiddlewareEntry>;
+  functions: Record<string, unknown>;
+}
+
+interface FunctionsConfigManifest {
+  version: number;
+  functions: Record<string, { runtime: string; matchers: ManifestMatcher[] }>;
+}
+
+/**
+ * Emit the middleware manifests for the resolved proxy file, if any. `entryFile`
+ * is the compiled proxy module path (relative to `outPath`, posix) produced by
+ * the build; it is recorded as the manifest `entrypoint` under `server/`.
+ */
+export async function writeMiddlewareManifests(
+  config: ResolvedConfig,
+  entryFile: string | undefined,
+  routes: RouteManifestEntry[] = [],
+): Promise<void> {
+  const source = findProxyFile(config);
+  // Edge-runtime app segments are manifest `functions` entries alongside the
+  // middleware, keyed by their app path (route groups included) — an app with
+  // an edge page and no middleware still writes the manifest for them.
+  const functions = edgeFunctionEntries(config, routes);
+  if (!source || !entryFile) {
+    if (Object.keys(functions).length === 0) return;
+    const serverDir = path.join(config.outPath, 'server');
+    await mkdir(serverDir, { recursive: true });
+    await writeFile(
+      path.join(serverDir, 'middleware-manifest.json'),
+      `${JSON.stringify({ ...emptyMiddlewareManifest(), functions }, null, 2)}\n`,
+    );
+    return;
+  }
+
+  const moduleFile = path.resolve(config.outPath, entryFile);
+  const module = (await import(pathToFileHref(moduleFile))) as ProxyModule;
+  const matchers = manifestMatchers(module.config);
+  const runtime = proxyRuntime(module.config);
+  const entrypoint = toServerEntrypoint(entryFile);
+
+  const serverDir = path.join(config.outPath, 'server');
+  await mkdir(serverDir, { recursive: true });
+
+  if (runtime === 'nodejs') {
+    const functionsConfig: FunctionsConfigManifest = {
+      version: 1,
+      functions: { '/_middleware': { runtime: 'nodejs', matchers } },
+    };
+    await writeFile(
+      path.join(serverDir, 'functions-config-manifest.json'),
+      `${JSON.stringify(functionsConfig, null, 2)}\n`,
+    );
+    // A node-runtime middleware still lists an empty edge middleware manifest so
+    // consumers that always read it find a valid (empty) shape.
+    await writeFile(
+      path.join(serverDir, 'middleware-manifest.json'),
+      `${JSON.stringify({ ...emptyMiddlewareManifest(), functions }, null, 2)}\n`,
+    );
+    return;
+  }
+
+  const entry: MiddlewareEntry = {
+    name: 'middleware',
+    page: '/',
+    matchers,
+    wasm: readMiddlewareWasmBindingsForOutPath(config.outPath),
+    assets: [],
+    files: [entrypoint],
+    entrypoint,
+    env: {},
+  };
+  const manifest: MiddlewareManifest = {
+    version: 3,
+    sortedMiddleware: ['/'],
+    middleware: { '/': entry },
+    functions,
+  };
+  await writeFile(
+    path.join(serverDir, 'middleware-manifest.json'),
+    `${JSON.stringify(manifest, null, 2)}\n`,
+  );
+}
+
+function emptyMiddlewareManifest(): MiddlewareManifest {
+  return { version: 3, sortedMiddleware: [], middleware: {}, functions: {} };
+}
+
+/**
+ * Manifest `functions` entries for app segments that declared
+ * `export const runtime = 'edge'`. Next keys them by the segment's app path
+ * (route groups kept, e.g. `/(group)/group/page`) and records the URL the
+ * segment answers as its matcher.
+ */
+function edgeFunctionEntries(
+  config: ResolvedConfig,
+  routes: RouteManifestEntry[],
+): Record<string, unknown> {
+  const entries: Record<string, unknown> = {};
+  if (!config.appPath) return entries;
+  for (const route of routes) {
+    const runtime = route.segmentConfig?.runtime;
+    if (runtime !== 'edge' && runtime !== 'experimental-edge') continue;
+    const page = appManifestKey(config.appPath, route.file);
+    if (!page) continue;
+    const regions = preferredRegionForRoute(route);
+    entries[page] = {
+      files: [],
+      name: `app${page}`,
+      page,
+      matchers: [{ regexp: `^${routeMatcherRegexp(route.route)}$`, originalSource: route.route }],
+      wasm: [],
+      assets: [],
+      env: {},
+      ...(regions ? { regions } : {}),
+    };
+  }
+  return entries;
+}
+
+// `<app>/(group)/group/page.tsx` → `/(group)/group/page`.
+function appManifestKey(appPath: string, file: string): string | undefined {
+  const relative = toPosixPath(path.relative(appPath, file));
+  if (!relative || relative.startsWith('..')) return undefined;
+  return `/${relative.replace(/\.[^./]+$/, '')}`;
+}
+
+// The URL regexp Next records for a segment: literal path with each dynamic
+// segment widened to a single path part.
+function routeMatcherRegexp(route: string): string {
+  return route.replace(/[|\\{}()[\]^$+*?.]/g, '\\$&').replace(/:([^/\\]+)/g, '[^/]+');
+}
+
+// Compile config.matcher entries into { regexp, originalSource } pairs. With no
+// matcher, the middleware runs on every path: Next records the `/:path*` source
+// and its `^/.*$` regexp.
+function manifestMatchers(config: ProxyConfig | undefined): ManifestMatcher[] {
+  const matcher = config?.matcher;
+  if (!matcher) return [{ regexp: '^/.*$', originalSource: '/:path*' }];
+  const list = Array.isArray(matcher) ? matcher : [matcher];
+  return list.map(item => {
+    const originalSource = typeof item === 'string' ? item : item.source;
+    return { regexp: `^${matcherRegexp(originalSource)}$`, originalSource };
+  });
+}
+
+// Mirror src/proxy.ts matcherPattern for the manifest regexp string (kept in
+// sync with the runtime matcher). Raw regex sources pass through unchanged.
+function matcherRegexp(matcher: string): string {
+  if (matcher.includes('(')) return matcher;
+  if (matcher === '/') return '/';
+  let source = '';
+  for (const segment of matcher.split('/').filter(Boolean)) {
+    if (/^:[^/]+\*$/.test(segment)) source += '(?:/.*)?';
+    else if (/^:[^/]+$/.test(segment)) source += '/[^/]+';
+    else source += `/${segment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`;
+  }
+  return source || '/';
+}
+
+function proxyRuntime(config: ProxyConfig | undefined): 'edge' | 'nodejs' {
+  const runtime = (config as { runtime?: unknown } | undefined)?.runtime;
+  return runtime === 'nodejs' ? 'nodejs' : 'edge';
+}
+
+// Record the compiled entry under the `server/` prefix Next uses, forcing a
+// `.js` extension (the manifest tests assert `^server/.+\.(js|mjs|cjs)$`).
+function toServerEntrypoint(entryFile: string): string {
+  const posix = toPosixPath(entryFile).replace(/^\.?\//, '');
+  const withinServer = posix.startsWith('server/') ? posix : `server/${path.posix.basename(posix)}`;
+  return withinServer.replace(/\.[^./]+$/, '.js');
+}

package/src/compat/misc/action-return.ts

@@ -0,0 +1,173 @@
+// Server-action RETURN-value handling (COMPAT).
+//
+// Two Next behaviors the e2e suite asserts about what an action sends back:
+//
+// 1. temporary-references: a client passes a plain object to an action and the action returns that SAME
+//    object; the client must receive the IDENTICAL object it sent (referential ===), not a structural
+//    copy. Next threads a "temporary reference" through the flight wire. This mirrors it with a
+//    lightweight tag protocol: the client stamps each top-level object arg with a temp-ref id and
+//    remembers id -> object; the server keeps that id associated with the decoded arg object (a
+//    WeakMap), and when it serializes the return value it emits a bare marker for any object the client
+//    originally sent. The client swaps the marker back for its original object.
+//
+// 2. actions-streaming: an action may return a ReadableStream; the response must stream it to the
+//    client unbuffered. JSON cannot carry a stream, so the server responds with the raw stream body
+//    under a marker header/content type and the client returns a live ReadableStream from the call.
+//
+// These helpers are pure and node-safe. The client counterparts live inline in actions/action-client.ts.
+
+/** Marker key naming a temporary-reference id in the args / return wire. */
+export const TEMP_REF_MARKER = '$$pnext_temp_ref';
+export const ACTION_ELEMENT_MARKER = '$$pnext_element';
+/**
+ * Marker carrying the SERVER-RENDERED HTML of a React element tree an action returned (host elements /
+ * async server components - NOT a client-reference element, which uses ACTION_ELEMENT_MARKER). The
+ * client revives it into a renderable node for useActionState.
+ */
+export const ACTION_ELEMENT_HTML_MARKER = '$$pnext_element_html';
+
+const clientReferenceSymbol = Symbol.for('pnext.clientReference');
+
+/**
+ * Response content-type/marker for a streamed action return. The client detects
+ * this and returns the response body as a ReadableStream from the call instead
+ * of parsing JSON.
+ */
+export const ACTION_STREAM_CONTENT_TYPE = 'x-component/pnext-stream';
+
+/**
+ * Per-request association of a decoded arg object -> the temp-ref id the client
+ * stamped on it. A WeakMap keyed by the live object preserves identity across
+ * the action call (the action returns the same reference it received).
+ */
+export interface TempRefScope {
+  /** Record that a decoded arg object carries the client's temp-ref id. */
+  track(object: object, id: string): void;
+  /** The temp-ref id the client sent for this object, if any. */
+  idFor(value: unknown): string | undefined;
+  /** True once any temp-ref arg has been seen (skip serialization walk otherwise). */
+  readonly active: boolean;
+}
+
+export function createTempRefScope(): TempRefScope {
+  const ids = new WeakMap<object, string>();
+  let active = false;
+  return {
+    track(object, id) {
+      ids.set(object, id);
+      active = true;
+    },
+    idFor(value) {
+      if (value === null || typeof value !== 'object') return undefined;
+      return ids.get(value);
+    },
+    get active() {
+      return active;
+    },
+  };
+}
+
+/**
+ * Strip and record temp-ref markers from a decoded argument tree in place.
+ * A `{ [TEMP_REF_MARKER]: id, ...rest }` object is unwrapped to `rest` and the
+ * resulting object is tracked under `id`, so the action sees a clean object and
+ * a later return of that same object serializes back to the marker.
+ */
+export function extractTempRefs(value: unknown, scope: TempRefScope, seen = new Set<unknown>()): unknown {
+  if (value === null || typeof value !== 'object') return value;
+  if (seen.has(value)) return value;
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) value[i] = extractTempRefs(value[i], scope, seen);
+    return value;
+  }
+  const record = value as Record<string, unknown>;
+  const id = record[TEMP_REF_MARKER];
+  if (typeof id === 'string') {
+    delete record[TEMP_REF_MARKER];
+    scope.track(record, id);
+  }
+  for (const key of Object.keys(record)) {
+    record[key] = extractTempRefs(record[key], scope, seen);
+  }
+  return record;
+}
+
+/**
+ * Serialize temporary references and elements in an action return.
+ * - A client-reference element carries only its client-reference id, props and key.
+ * - A server element tree is server-rendered to island wire HTML via the injected `renderElement`;
+ *   JSON cannot carry vnode $$typeof Symbols, so without this the tree dumps as raw vnode internals and
+ *   useActionState never gets a node. Async because rendering resolves async server components; when no
+ *   renderer is injected, element trees fall through unchanged.
+ */
+export async function serializeReturnWithTempRefs(
+  value: unknown,
+  scope: TempRefScope,
+  renderElement?: (element: unknown) => Promise<string>,
+): Promise<unknown> {
+  const walk = async (input: unknown, seen: Set<unknown>): Promise<unknown> => {
+    if (input === null || typeof input !== 'object') return input;
+    const marker = scope.active ? scope.idFor(input) : undefined;
+    if (marker !== undefined) return { [TEMP_REF_MARKER]: marker };
+    if (seen.has(input)) return input;
+    seen.add(input);
+    const element = clientReferenceElement(input);
+    if (element) {
+      return {
+        [ACTION_ELEMENT_MARKER]: {
+          id: element.id,
+          props: await walk(element.props, seen),
+          ...(element.key !== undefined ? { key: element.key } : {}),
+        },
+      };
+    }
+    if (renderElement && isServerElement(input)) {
+      return { [ACTION_ELEMENT_HTML_MARKER]: await renderElement(input) };
+    }
+    if (Array.isArray(input)) return Promise.all(input.map(item => walk(item, seen)));
+    const proto = Object.getPrototypeOf(input) as object | null;
+    if (proto !== Object.prototype && proto !== null) return input;
+    const out: Record<string, unknown> = {};
+    for (const [key, item] of Object.entries(input as Record<string, unknown>)) {
+      out[key] = await walk(item, seen);
+    }
+    return out;
+  };
+  return walk(value, new Set());
+}
+
+/**
+ * True for a React element / preact vnode that is NOT a client-reference element
+ * (those are handled by clientReferenceElement first). Detects the preact vnode
+ * brand (own `constructor === undefined`) or the react.element `$$typeof`, so a
+ * plain data object that merely has `type`/`props` keys is never mistaken for an
+ * element (it stays JSON-serialized).
+ */
+function isServerElement(value: object): boolean {
+  const vnode = value as { type?: unknown; props?: unknown; $$typeof?: unknown };
+  if (!('type' in vnode) || !('props' in vnode)) return false;
+  if (vnode.$$typeof === Symbol.for('react.element')) return true;
+  return (
+    Object.prototype.hasOwnProperty.call(value, 'constructor') &&
+    (value as { constructor?: unknown }).constructor === undefined
+  );
+}
+
+function clientReferenceElement(
+  value: object,
+): { id: string; props: unknown; key?: string | number } | undefined {
+  const vnode = value as { type?: unknown; props?: unknown; key?: unknown };
+  if (typeof vnode.type !== 'function') return undefined;
+  const reference = (vnode.type as unknown as Record<symbol, unknown>)[clientReferenceSymbol] as
+    | { id?: unknown }
+    | undefined;
+  if (typeof reference?.id !== 'string') return undefined;
+  const key = typeof vnode.key === 'string' || typeof vnode.key === 'number' ? vnode.key : undefined;
+  return { id: reference.id, props: vnode.props ?? {}, ...(key !== undefined ? { key } : {}) };
+}
+
+/** True for a value the streaming action path must send as a raw stream body. */
+export function isReadableStreamReturn(value: unknown): value is ReadableStream {
+  return typeof ReadableStream !== 'undefined' && value instanceof ReadableStream;
+}