@wular/pnext 0.0.1

package/src/utils/ansi.ts

@@ -0,0 +1,9 @@
+function color(open: string, close: string) {
+  return (value: string) => (process.stdout.isTTY ? `${open}${value}${close}` : value);
+}
+
+/** Mid-gray for subordinate text. Readable on both light and dark terminals. */
+export const dim = color('\x1b[38;5;244m', '\x1b[39m');
+export const bold = color('\x1b[1m', '\x1b[22m');
+export const cyan = color('\x1b[36m', '\x1b[39m');
+export const green = color('\x1b[32m', '\x1b[39m');

package/src/utils/content-type.ts

@@ -0,0 +1,31 @@
+import path from 'node:path';
+
+const contentTypes: Record<string, string> = {
+  '.avif': 'image/avif',
+  '.bmp': 'image/bmp',
+  '.css': 'text/css; charset=utf-8',
+  '.eot': 'application/vnd.ms-fontobject',
+  '.gif': 'image/gif',
+  '.htm': 'text/html; charset=utf-8',
+  '.html': 'text/html; charset=utf-8',
+  '.ico': 'image/x-icon',
+  '.jpeg': 'image/jpeg',
+  '.jpg': 'image/jpeg',
+  '.js': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.otf': 'font/otf',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.tif': 'image/tiff',
+  '.tiff': 'image/tiff',
+  '.ttf': 'font/ttf',
+  '.wasm': 'application/wasm',
+  '.webp': 'image/webp',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+};
+
+export function contentType(file: string): string {
+  return contentTypes[path.extname(file).toLowerCase()] ?? 'application/octet-stream';
+}

package/src/utils/decode.ts

@@ -0,0 +1,7 @@
+export function safeDecode(value: string) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}

package/src/utils/dev-profile.ts

@@ -0,0 +1,31 @@
+/**
+ * Buffered sink for PNEXT_DEV_PROFILE lines. A warm request emits many phase lines, and writing each
+ * straight to stdout inflated every enclosing span it sat inside - the measurement changed what it
+ * measured. Lines accumulate here and the request handler flushes them in one write.
+ */
+const SINK = Symbol.for('pnext.devProfileSink');
+
+function sink(): string[] {
+  const store = globalThis as Record<PropertyKey, unknown>;
+  return (store[SINK] ??= []) as string[];
+}
+
+export function recordDevProfileLine(line: string) {
+  sink().push(line);
+}
+
+/** Emit and clear everything buffered so far (one write per request). */
+export function flushDevProfileLines() {
+  const lines = sink();
+  if (lines.length === 0) return;
+  const out = lines.join('\n');
+  lines.length = 0;
+  console.log(out);
+}
+
+export function formatProfileDuration(durationMs: number) {
+  const ms = Math.max(0, durationMs);
+  if (ms < 10) return `${ms.toFixed(2)}ms`;
+  if (ms < 1000) return `${ms.toFixed(1)}ms`;
+  return `${(ms / 1000).toFixed(ms < 10000 ? 2 : 1)}s`;
+}

package/src/utils/error-log.ts

@@ -0,0 +1,29 @@
+// Once-per-error server log guard. An SSR error can reach several log sites in one request (the renderer's
+// inline report, then the top-level start/dev-server catch). Tag the error object the first time it is
+// logged so the downstream catch skips its own `console.error` and each error surfaces once.
+//
+// The tag lives on the error itself (a non-enumerable symbol property), so it survives across log sites
+// without a WeakSet keyed to a work unit - an error thrown outside any work-unit scope is still deduped. A
+// non-Error throw cannot carry the tag; those are always logged.
+
+const ERROR_LOGGED = Symbol.for('pnext.errorLogged');
+
+/**
+ * Mark `error` as logged. Returns true when this call was the FIRST to mark it (the caller should log), false
+ * when it was already marked (skip the log). Non-object throws always return true - they cannot be tagged, so
+ * they are never deduped.
+ */
+export function markErrorLogged(error: unknown): boolean {
+  if (error === null || (typeof error !== 'object' && typeof error !== 'function')) {
+    return true;
+  }
+  const holder = error as Record<symbol, unknown>;
+  if (holder[ERROR_LOGGED]) return false;
+  Object.defineProperty(error, ERROR_LOGGED, {
+    value: true,
+    enumerable: false,
+    configurable: true,
+    writable: true,
+  });
+  return true;
+}

package/src/utils/fs-cache.ts

@@ -0,0 +1,31 @@
+import { existsSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+
+const NODE_MODULES = `${path.sep}node_modules${path.sep}`;
+
+// One cached dirent listing per directory replaces per-file stat probes.
+// node_modules only: installed layouts are process-immutable, app paths are not.
+const dirents = new Map<string, Set<string> | undefined>();
+
+function direntsFor(dir: string) {
+  if (dirents.has(dir)) return dirents.get(dir);
+  let names: Set<string> | undefined;
+  try {
+    names = new Set(readdirSync(dir));
+  } catch {
+    names = undefined;
+  }
+  dirents.set(dir, names);
+  return names;
+}
+
+/** `existsSync`, served from the dirent cache for node_modules paths. */
+export function cachedExistsSync(file: string): boolean {
+  if (!file.includes(NODE_MODULES)) return existsSync(file);
+  return direntsFor(path.dirname(file))?.has(path.basename(file)) ?? false;
+}
+
+/** Structural-save invalidation: a file added or deleted changes the answers. */
+export function clearNodeModulesFsCache(): void {
+  dirents.clear();
+}

package/src/utils/fs.ts

@@ -0,0 +1,119 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { mkdir, readdir, rename, rm, stat, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+// Write-then-rename so a concurrent import never observes a truncated file; Bun caches a failed load for the
+// life of the process. The temp name must be unique per CALL, not per process: two writers of the same output
+// (two routes demanding one vendor bundle, a re-write after a cache eviction) otherwise share a name and the
+// second rename hits ENOENT once the first moved it away. Losing that race is harmless - both wrote the same
+// content-keyed bytes - so a rename whose temp is gone only fails if the destination is missing too.
+let atomicWriteSequence = 0;
+export async function writeFileAtomic(file: string, contents: string) {
+  const temp = `${file}.${process.pid.toString(36)}.${(++atomicWriteSequence).toString(36)}.tmp`;
+  await writeFile(temp, contents);
+  try {
+    await rename(temp, file);
+  } catch (error) {
+    if (!existsSync(file)) throw error;
+  }
+}
+
+export async function listFiles(root: string): Promise<string[]> {
+  if (!existsSync(root)) return [];
+  const entries = await readdir(root, { withFileTypes: true });
+  // Subdirectories are walked concurrently — a depth-first await chain spends
+  // the whole walk waiting on one readdir at a time (0.6 s on a ~1k-file app).
+  // Results stay in readdir order so callers keep a stable file order.
+  const branches = await Promise.all(
+    entries.map(entry => {
+      const entryPath = path.join(root, entry.name);
+      if (entry.isDirectory()) return listFiles(entryPath);
+      return Promise.resolve(entry.isFile() ? [entryPath] : []);
+    }),
+  );
+  return branches.flat();
+}
+
+interface DirListing {
+  files: Set<string>;
+  dirs: string[];
+}
+
+let dirListings: Map<string, DirListing> | undefined;
+
+/**
+ * Memoize directory listings for the duration of `run`. A route scan asks the
+ * same handful of directories for every convention file of every route, and the
+ * answers cannot change mid-scan. Outside a `withDirCache` scope every lookup
+ * reads the directory fresh, so request-time callers never see a stale tree.
+ */
+export function withDirCache<T>(run: () => T): T {
+  if (dirListings) return run();
+  dirListings = new Map();
+  try {
+    return run();
+  } finally {
+    dirListings = undefined;
+  }
+}
+
+/** File and subdirectory names of `dir` (both empty when it does not exist). */
+export function readDirListing(dir: string): DirListing {
+  const cached = dirListings?.get(dir);
+  if (cached) return cached;
+  let listing: DirListing;
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    listing = {
+      files: new Set(entries.filter(entry => !entry.isDirectory()).map(entry => entry.name)),
+      dirs: entries
+        .filter(entry => entry.isDirectory())
+        .map(entry => entry.name)
+        .sort(),
+    };
+  } catch {
+    listing = { files: new Set(), dirs: [] };
+  }
+  dirListings?.set(dir, listing);
+  return listing;
+}
+
+/** listFiles for callers already running synchronously (route fact scans). */
+export function listFilesSync(root: string): string[] {
+  if (!existsSync(root)) return [];
+  const out: string[] = [];
+
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    const entryPath = path.join(root, entry.name);
+    if (entry.isDirectory()) out.push(...listFilesSync(entryPath));
+    else if (entry.isFile()) out.push(entryPath);
+  }
+
+  return out;
+}
+
+export async function ensureEmptyDir(dir: string) {
+  await rm(dir, { recursive: true, force: true });
+  await mkdir(dir, { recursive: true });
+}
+
+export async function ensureDir(dir: string) {
+  await mkdir(dir, { recursive: true });
+}
+
+export async function writeText(file: string, value: string) {
+  await ensureDir(path.dirname(file));
+  await writeFile(file, value);
+}
+
+export async function readText(file: string) {
+  return readFile(file, 'utf8');
+}
+
+export async function fileMtime(file: string) {
+  return (await stat(file)).mtimeMs;
+}
+
+export function toPosixPath(value: string) {
+  return value.split(path.sep).join('/');
+}

package/src/utils/html.ts

@@ -0,0 +1,46 @@
+export function escapeHtml(value: unknown) {
+  return stringifyHtmlValue(value).replace(/[&<>"']/g, char => {
+    switch (char) {
+      case '&':
+        return '&amp;';
+      case '<':
+        return '&lt;';
+      case '>':
+        return '&gt;';
+      case '"':
+        return '&quot;';
+      case "'":
+        return '&#39;';
+      default:
+        return char;
+    }
+  });
+}
+
+export function stringifyHtmlValue(value: unknown) {
+  if (value === undefined || value === null) return '';
+  if (typeof value === 'string') return value;
+  if (
+    typeof value === 'number' ||
+    typeof value === 'boolean' ||
+    typeof value === 'bigint'
+  ) {
+    return String(value);
+  }
+  if (value instanceof URL) return value.href;
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value !== 'object') return '';
+
+  const stringifier = (value as { toString?: (this: object) => unknown }).toString;
+  if (!stringifier || stringifier === Object.prototype.toString) return '';
+  const stringified = stringifier.call(value);
+  if (typeof stringified === 'string') return stringified;
+  if (
+    typeof stringified === 'number' ||
+    typeof stringified === 'boolean' ||
+    typeof stringified === 'bigint'
+  ) {
+    return String(stringified);
+  }
+  return '';
+}

package/src/utils/serialize.ts

@@ -0,0 +1,378 @@
+// Typed-array / ArrayBuffer wire markers. Binary values are not JSON-native, so
+// serializeProps marker-encodes them (base64 payload, same $$pnext_* convention
+// as the action wire's $$pnext_date) instead of throwing; the client/server
+// revive the marker back into the original view. assertSerializable accepts
+// them (they are "serializable" via the marker path) rather than rejecting.
+const TYPED_ARRAY_MARKER = '$$pnext_typed_array';
+const ARRAY_BUFFER_MARKER = '$$pnext_array_buffer';
+// Map/Set are part of React's flight wire vocabulary (client components can receive them as props); pnext
+// does not stream them as distinct RSC row types yet, so they ride as ordinary marker objects, entries
+// encoded recursively like the binary markers above, instead of throwing "must be a plain object". Client
+// code that only round-trips the value sees a marker object rather than a live Map/Set instance - a known
+// gap, not a full flight-protocol Map/Set.
+const MAP_MARKER = '$$pnext_map';
+const SET_MARKER = '$$pnext_set';
+// Cyclic props (a client component receiving `obj.self === obj`) are part of React's flight vocabulary:
+// flight emits a BACK-REFERENCE to the row/path the value was first written at rather than expanding it
+// forever. Same idea here, scoped to the ancestor chain: an object that reappears INSIDE ITSELF is written as
+// `{$$pnext_ref: [...path from the props root]}` and the client patches the original object back in,
+// restoring identity. Only true cycles are encoded this way - a value that merely appears twice in different
+// branches is still expanded, so every acyclic payload is byte-identical to what it was before.
+const REF_MARKER = '$$pnext_ref';
+
+type TypedArray =
+  | Int8Array
+  | Uint8Array
+  | Uint8ClampedArray
+  | Int16Array
+  | Uint16Array
+  | Int32Array
+  | Uint32Array
+  | Float32Array
+  | Float64Array
+  | BigInt64Array
+  | BigUint64Array;
+
+function isTypedArray(value: unknown): value is TypedArray {
+  return ArrayBuffer.isView(value) && !(value instanceof DataView);
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  if (typeof Buffer !== 'undefined') return Buffer.from(bytes).toString('base64');
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+function encodeTypedArray(value: TypedArray) {
+  const bytes = new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  return { [TYPED_ARRAY_MARKER]: { type: value.constructor.name, data: bytesToBase64(bytes) } };
+}
+
+function encodeArrayBuffer(value: ArrayBuffer) {
+  return { [ARRAY_BUFFER_MARKER]: bytesToBase64(new Uint8Array(value)) };
+}
+
+/**
+ * Deep-copy `value`, replacing typed arrays / ArrayBuffers with wire markers
+ * and self-references (cycles) with `$$pnext_ref` back-references.
+ *
+ * `ancestors` maps every object on the CURRENT path to the path it was written
+ * at; it is unwound on the way back out, so only a value that contains itself
+ * becomes a reference.
+ */
+function encodeBinary(
+  value: unknown,
+  ancestors = new Map<object, string[]>(),
+  path: string[] = [],
+): unknown {
+  if (value === null || typeof value !== 'object') return value;
+  if (isTypedArray(value)) return encodeTypedArray(value);
+  if (value instanceof ArrayBuffer) return encodeArrayBuffer(value);
+  const ancestorPath = ancestors.get(value);
+  if (ancestorPath) return { [REF_MARKER]: ancestorPath };
+  ancestors.set(value, path);
+  const encoded = encodeContainer(value, ancestors, path);
+  ancestors.delete(value);
+  return encoded;
+}
+
+function encodeContainer(
+  value: object,
+  ancestors: Map<object, string[]>,
+  path: string[],
+): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item, index) => encodeBinary(item, ancestors, [...path, String(index)]));
+  }
+  if (value instanceof Map) {
+    return {
+      [MAP_MARKER]: [...value.entries()].map(([k, v]) => [
+        encodeBinary(k, ancestors),
+        encodeBinary(v, ancestors),
+      ]),
+    };
+  }
+  if (value instanceof Set) {
+    return { [SET_MARKER]: [...value].map(item => encodeBinary(item, ancestors)) };
+  }
+  if (Object.getPrototypeOf(value) !== Object.prototype) return value;
+  const out: Record<string, unknown> = {};
+  for (const [key, item] of Object.entries(value)) {
+    out[key] = encodeBinary(item, ancestors, [...path, key]);
+  }
+  return out;
+}
+
+// Errors reach `error.tsx` as props and ride the same marker convention (the
+// encoder for this one lives on the render side, with the boundary props).
+const ERROR_MARKER = '$$pnextError';
+
+/**
+ * Revive the wire markers `serializeProps` wrote, IN PLACE:
+ *
+ * - `$$pnext_ref` back-references, restoring the identity the server saw. Paths are relative to the root
+ *   passed in - the same root serializeProps encoded - and always point at an ancestor, so the target is
+ *   already materialized when the marker is hit.
+ * - typed arrays / ArrayBuffers, back into the original view.
+ * - Errors, via `extra` - see `reviveSerializedErrorRefs`.
+ *
+ * The action runtime revives all of these for apps that have it, but an app with no server actions never
+ * loads it - and its islands would then hydrate with marker objects where the server rendered real values.
+ */
+export function reviveSerializedRefs<T>(
+  root: T,
+  extra?: (node: Record<string, unknown>) => unknown,
+): T {
+  if (root === null || typeof root !== 'object') return root;
+  const visit = (node: Record<string, unknown>): void => {
+    for (const key of Object.keys(node)) {
+      const item = node[key];
+      if (item === null || typeof item !== 'object' || ArrayBuffer.isView(item)) continue;
+      const child = item as Record<string, unknown>;
+      const revived = refTarget(root, child) ?? extra?.(child) ?? binaryTarget(child);
+      if (revived !== undefined) {
+        node[key] = revived;
+        continue;
+      }
+      visit(child);
+    }
+  };
+  visit(root as Record<string, unknown>);
+  return root;
+}
+
+/**
+ * The above plus `$$pnextError`. Kept as its own export so the error branch
+ * tree-shakes out of core/react client entries: `$$pnextError` is a
+ * next-compat-only marker (the renderer's `serializeActionProps` returns props
+ * untouched when compat is off), and only compat entries import this name.
+ */
+export function reviveSerializedErrorRefs<T>(root: T): T {
+  return reviveSerializedRefs(root, errorTarget);
+}
+
+function errorTarget(node: Record<string, unknown>): Error | undefined {
+  const marker = node[ERROR_MARKER];
+  if (marker === null || typeof marker !== 'object') return undefined;
+  const data = marker as { name?: unknown; message?: unknown; digest?: unknown };
+  const error = new Error(typeof data.message === 'string' ? data.message : '');
+  if (typeof data.name === 'string') error.name = data.name;
+  if (typeof data.digest === 'string') (error as Error & { digest?: string }).digest = data.digest;
+  return error;
+}
+
+// The wire carries the view's constructor NAME. Resolved off the global rather than a name-to-constructor
+// table (the table is first-paint client code): `BYTES_PER_ELEMENT` exists only on typed-array constructors,
+// so any other name - including one that resolves to something else entirely - resolves to undefined and the
+// marker is left alone.
+function typedArrayConstructor(name: string) {
+  const constructor = (globalThis as unknown as Record<string, unknown>)[name];
+  return typeof constructor === 'function' && 'BYTES_PER_ELEMENT' in constructor
+    ? (constructor as unknown as new (buffer: ArrayBuffer) => TypedArray)
+    : undefined;
+}
+
+// Decode side is client-only (the encoder is what runs on the server), so no
+// Buffer fast path — `atob` is global in every runtime that reaches this.
+function base64ToBytes(data: string): Uint8Array {
+  return Uint8Array.from(atob(data), character => character.charCodeAt(0));
+}
+
+function binaryTarget(node: Record<string, unknown>): TypedArray | ArrayBuffer | undefined {
+  const buffer = node[ARRAY_BUFFER_MARKER];
+  if (typeof buffer === 'string') return base64ToBytes(buffer).buffer as ArrayBuffer;
+  const typed = node[TYPED_ARRAY_MARKER];
+  if (typed === null || typeof typed !== 'object') return undefined;
+  const { type, data } = typed as { type?: unknown; data?: unknown };
+  if (typeof type !== 'string' || typeof data !== 'string') return undefined;
+  const Constructor = typedArrayConstructor(type);
+  return Constructor ? new Constructor(base64ToBytes(data).buffer as ArrayBuffer) : undefined;
+}
+
+function refTarget(root: unknown, node: Record<string, unknown>): unknown {
+  const path = node[REF_MARKER];
+  if (!Array.isArray(path)) return undefined;
+  let current: unknown = root;
+  for (const key of path) {
+    if (current === null || typeof current !== 'object') return undefined;
+    current = (current as Record<string, unknown>)[String(key)];
+  }
+  return current;
+}
+
+/** A preact vnode: `h` sets `constructor` to undefined on every one it makes. */
+export function isElementLike(value: unknown): boolean {
+  if (value === null || typeof value !== 'object') return false;
+  return (
+    (value as { constructor?: unknown }).constructor === undefined &&
+    'type' in value &&
+    'props' in value
+  );
+}
+
+export function assertSerializable(
+  value: unknown,
+  path = 'props',
+  seen = new Set<unknown>(),
+  // Island props only: element values are replaced by `$$pnext_slot` markers upstream (islands/
+  // static-slots), so they are serializable there. Server-action args/returns keep throwing.
+  allowElements = false,
+) {
+  if (value == null) return;
+  if (allowElements && isElementLike(value)) return;
+  const type = typeof value;
+  if (type === 'string' || type === 'number' || type === 'boolean') return;
+  if (type === 'function' || type === 'symbol' || type === 'bigint' || type === 'undefined') {
+    throw new Error(`${path} is not serializable: ${type}`);
+  }
+  // Typed arrays / ArrayBuffers are serializable via the binary marker path.
+  if (isTypedArray(value) || value instanceof ArrayBuffer) return;
+  if (value instanceof Date || value instanceof URL) {
+    throw new Error(`${path} must be a plain JSON value`);
+  }
+  if (typeof value !== 'object') return;
+  // A value that contains ITSELF is serializable: encodeBinary writes it as a
+  // `$$pnext_ref` back-reference (React flight does the same), so stop walking
+  // rather than rejecting the props.
+  if (seen.has(value)) return;
+  seen.add(value);
+
+  if (Array.isArray(value)) {
+    value.forEach((item, index) =>
+      assertSerializable(item, `${path}[${index}]`, seen, allowElements),
+    );
+    return;
+  }
+
+  // The slot walk (islands/static-slots) never enters Map/Set, so elements inside them must
+  // still throw rather than ship mangled.
+  if (value instanceof Map) {
+    let index = 0;
+    for (const [key, item] of value.entries()) {
+      assertSerializable(key, `${path}<Map key ${index}>`, seen);
+      assertSerializable(item, `${path}<Map value ${index}>`, seen);
+      index++;
+    }
+    return;
+  }
+
+  if (value instanceof Set) {
+    let index = 0;
+    for (const item of value) {
+      assertSerializable(item, `${path}<Set item ${index}>`, seen);
+      index++;
+    }
+    return;
+  }
+
+  if (Object.getPrototypeOf(value) !== Object.prototype) {
+    throw new Error(`${path} must be a plain object`);
+  }
+
+  for (const [key, item] of Object.entries(value)) {
+    assertSerializable(item, `${path}.${key}`, seen, allowElements);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tainted object references (COMPAT `experimental.taint` opts in; the registry
+// itself is inert until something registers a value).
+//
+// React's taint APIs (taintObjectReference) don't exist under preact, so the
+// client-props serializer enforces the same contract with an IDENTITY check:
+// compat registers `process.env` when `experimental.taint` is set, and any
+// client-component prop that IS that object (at any depth) throws the
+// registered message. The throw travels the normal render-error path, so dev
+// shows the message in the nearest error.tsx boundary and prod shows React's
+// redacted #441 text.
+//
+// The registry is anchored on globalThis: a module loaded twice (built copy vs
+// original) must not split the tainted set.
+// ---------------------------------------------------------------------------
+
+const TAINT_REGISTRY_KEY = '__pnext_tainted_values__';
+
+/** Dev message plus the redacted text prod shows in its place. */
+export interface TaintMessages {
+  dev: string;
+  prod: string;
+}
+
+function taintRegistry(): Map<object, TaintMessages> {
+  const host = globalThis as { [TAINT_REGISTRY_KEY]?: Map<object, TaintMessages> };
+  const existing = host[TAINT_REGISTRY_KEY];
+  if (existing) return existing;
+  const created = new Map<object, TaintMessages>();
+  host[TAINT_REGISTRY_KEY] = created;
+  return created;
+}
+
+/** Register `value` as unsafe to pass to a client component. */
+export function taintObjectReference(messages: TaintMessages, value: object): void {
+  taintRegistry().set(value, messages);
+}
+
+/**
+ * Throw if a tainted object reference appears anywhere in `value`. Must run on
+ * the RAW props (before any serializer copies plain objects and drops the
+ * identity the check relies on).
+ */
+export function assertNotTainted(value: unknown, seen = new Set<unknown>()): void {
+  const registry = taintRegistry();
+  if (registry.size === 0) return;
+  if (value === null || typeof value !== 'object') return;
+  const messages = registry.get(value);
+  if (messages !== undefined) {
+    // Next surfaces the explanatory message in dev only; prod renders React's
+    // redacted RSC error text in the nearest error boundary.
+    throw new Error(
+      // eslint-disable-next-line turbo/no-undeclared-env-vars
+      process.env.NODE_ENV === 'development' ? messages.dev : messages.prod,
+    );
+  }
+  if (seen.has(value)) return;
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (const item of value) assertNotTainted(item, seen);
+    return;
+  }
+  if (value instanceof Map) {
+    for (const [key, item] of value.entries()) {
+      assertNotTainted(key, seen);
+      assertNotTainted(item, seen);
+    }
+    return;
+  }
+  if (value instanceof Set) {
+    for (const item of value) assertNotTainted(item, seen);
+    return;
+  }
+  const proto = Object.getPrototypeOf(value) as object | null;
+  if (proto !== Object.prototype && proto !== null) return;
+  for (const item of Object.values(value)) assertNotTainted(item, seen);
+}
+
+export function serializeProps(value: unknown, options?: { allowElements?: boolean }) {
+  assertNotTainted(value);
+  assertSerializable(value, 'props', new Set(), options?.allowElements);
+  return JSON.stringify(encodeBinary(value)).replace(
+    /[<>&\u2028\u2029]/g,
+    char => {
+      switch (char) {
+        case '<':
+          return '\\u003c';
+        case '>':
+          return '\\u003e';
+        case '&':
+          return '\\u0026';
+        case '\u2028':
+          return '\\u2028';
+        case '\u2029':
+          return '\\u2029';
+        default:
+          return char;
+      }
+    },
+  );
+}