@thomas.f/prnext 0.1.0-alpha.1

package/runtime/app-static-params.mjs

@@ -0,0 +1,120 @@
+import { currentRequest } from '../compat/headers.cjs';
+
+const MAX_PATHS = 10_000;
+const MAX_PARAMS_BYTES = 4 * 1024 * 1024;
+const objectConstructor = Function.prototype.toString.call(Object);
+function plainParams(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype === null || prototype === Object.prototype) return true;
+  // An Edge realm has its own Object.prototype. Accept its ordinary objects,
+  // while still rejecting application class instances and custom prototypes.
+  const constructor = Object.getOwnPropertyDescriptor(prototype, 'constructor')?.value;
+  return Object.getPrototypeOf(prototype) === null && typeof constructor === 'function' && Function.prototype.toString.call(constructor) === objectConstructor;
+}
+
+function names(pattern) {
+  return new Set([...String(pattern || '').matchAll(/\[(?:\[)?(?:\.\.\.)?([^\]]+)\]\]?/g)].map(match => match[1]));
+}
+
+function publicParams(row, branchPattern, routePattern) {
+  const source = branchPattern.split('/').filter(Boolean), target = routePattern.split('/').filter(Boolean);
+  const result = {};
+  const name = part => /^\[\[?(?:\.\.\.)?([^\]]+)\]\]?$/.exec(part)?.[1];
+  for (let index = 0; index < target.length; index++) {
+    const targetName = name(target[index]);
+    if (!targetName) continue;
+    const sourceName = name(source[index] || '');
+    if (sourceName && Object.hasOwn(row, sourceName)) result[targetName] = row[sourceName];
+    else if (!sourceName && source[index]) result[targetName] = source[index];
+  }
+  return result;
+}
+
+export function validateRuntimeStaticConfig(entry) {
+  const fields = ['dynamic', 'dynamicParams', 'instant', 'revalidate', 'fetchCache', 'runtime', 'preferredRegion', 'maxDuration', 'experimental_ppr'];
+  const modules = (entry.segments || []).filter(segment => segment.staticConfig !== undefined)
+    .map(segment => [segment.layout, segment.staticConfig]);
+  if (entry.pageConfig !== undefined) modules.push([entry.page, entry.pageConfig]);
+  for (const [module, config] of modules) {
+    if (!module || module.default?.$$typeof === Symbol.for('react.client.reference')) continue;
+    for (const field of fields) {
+      if (module[field] !== undefined && (!Object.hasOwn(config, field) || JSON.stringify(module[field]) !== JSON.stringify(config[field]))) {
+        throw new Error(`Statically analyzable route config required: ${field} cannot be hidden behind wildcard re-exports`);
+      }
+    }
+  }
+}
+
+export async function collectStaticParams(entry, routePattern, memo = new Map()) {
+  validateRuntimeStaticConfig(entry);
+  if (entry.routing) {
+    const branches = [];
+    function visit(node, parents = []) {
+      if (node.interception) return;
+      const segments = [...parents, { layout: node.files.layout, staticConfig: node.config?.layout || {}, path: node.pattern }];
+      if (node.files.page) branches.push({ page: node.files.page, pageConfig: node.config?.page || {}, segments, pattern: node.pattern });
+      for (const child of [...node.children, ...Object.values(node.slots)]) visit(child, segments);
+    }
+    visit(entry.routing);
+    const params = new Map();
+    let generated = false, bytes = 0;
+    for (const branch of branches) {
+      const result = await collectStaticParams(branch, branch.pattern, memo);
+      generated ||= result.generated;
+      for (const branchRow of result.params) {
+        const row = publicParams(branchRow, branch.pattern, routePattern);
+        const key = JSON.stringify(Object.fromEntries(Object.entries(row).sort(([a], [b]) => a.localeCompare(b))));
+        if (params.has(key)) continue;
+        bytes += Buffer.byteLength(key);
+        if (params.size >= MAX_PATHS || bytes > MAX_PARAMS_BYTES) throw new Error('generateStaticParams exceeds the PRNext path generation limit');
+        params.set(key, row);
+      }
+    }
+    return { params: [...params.values()], generated };
+  }
+  let params = [{}];
+  let generated = false;
+  const generators = (entry.segments || []).map(segment => ({ module: segment.layout, scope: segment.path || segment.segment || '' }));
+  generators.push({ module: entry.page, scope: routePattern });
+  for (const { module, scope } of generators) {
+    if (module?.generateStaticParams === undefined) continue;
+    if (typeof module.generateStaticParams !== 'function') throw new Error('generateStaticParams must export a function');
+    generated = true;
+    const allowed = names(scope);
+    const expanded = [];
+    let bytes = 0;
+    for (const parent of params) {
+      let results = memo.get(module.generateStaticParams);
+      if (!results) memo.set(module.generateStaticParams, results = new Map());
+      const parentKey = JSON.stringify(parent);
+      if (!results.has(parentKey)) results.set(parentKey, Promise.resolve().then(() => module.generateStaticParams({ params: { ...parent } })));
+      const rows = await results.get(parentKey);
+      if (!Array.isArray(rows)) throw new Error('generateStaticParams must return an array of parameter objects');
+      let cacheComponents = false;
+      try { cacheComponents = currentRequest().cacheComponents === true; } catch { /* Direct inspection outside a request. */ }
+      if (cacheComponents && rows.length === 0) throw new Error(`generateStaticParams for ${scope || '/'} must return at least one parameter object when cacheComponents is enabled.`);
+      for (const row of rows) {
+        if (!plainParams(row)) {
+          throw new Error('generateStaticParams must return plain parameter objects');
+        }
+        for (const [key, value] of Object.entries(row)) {
+          if (!allowed.has(key)) throw new Error(`generateStaticParams cannot generate child or unknown parameter ${key} from segment ${scope || '/'}`);
+          const absentOptional = String(scope).includes(`[[...${key}]]`) && (value === undefined || value === null || value === false);
+          if (!absentOptional && typeof value !== 'string' && (!Array.isArray(value) || Array.from(value).some(part => typeof part !== 'string'))) {
+            throw new Error(`generateStaticParams parameter ${key} must be a string or array of strings`);
+          }
+          if (Object.hasOwn(parent, key) && JSON.stringify(parent[key]) !== JSON.stringify(value)) {
+            throw new Error(`generateStaticParams cannot overwrite parent parameter ${key}`);
+          }
+        }
+        const combined = { ...parent, ...row };
+        bytes += Buffer.byteLength(JSON.stringify(combined));
+        if (expanded.length >= MAX_PATHS || bytes > MAX_PARAMS_BYTES) throw new Error('generateStaticParams exceeds the PRNext path generation limit');
+        expanded.push(combined);
+      }
+    }
+    params = expanded;
+  }
+  return { params, generated };
+}

package/runtime/app-static.mjs

@@ -0,0 +1,86 @@
+import path from 'node:path';
+import { addBasePath, removeBasePath } from '../compat/paths.cjs';
+import { renderFlight, decodeFlight, renderHtml, completeAppHtml } from './app-render.mjs';
+import { runRequestContext, currentRequest } from '../compat/headers.cjs';
+import { flushCacheWork } from '../compat/data-cache.cjs';
+import { trackStaticDependency, staticMetadata } from '../compat/static-generation.cjs';
+import { prerenderPartialHtml } from './app-partial.mjs';
+import { partialKeyMap } from './app-partial-model.mjs';
+
+export function requestOptions(options) {
+  const route = options.route || {};
+  const canonical = new URL('http://prnext.local');
+  canonical.pathname = new URL(options.path || options.url || '/', canonical).pathname;
+  return { modulePath: options.modulePath, distDir: options.distDir || path.dirname(path.dirname(options.modulePath)),
+    routePattern: route.pattern, cacheConfig: route.cacheConfig || {}, css: route.css || [], fonts: route.fonts || [], production: options.production ?? true,
+    url: canonical.href, originalUrl: options.originalUrl ? new URL(new URL(options.originalUrl).pathname, canonical).href : undefined,
+    partialParams: options.partialParams, basePath: options.manifest?.config?.basePath || '', trailingSlash: options.manifest?.config?.trailingSlash || false, skipTrailingSlashRedirect: options.manifest?.config?.skipTrailingSlashRedirect || false, params: options.params || {}, method: 'GET', headers: {},
+    ...(options.seed ? { partialFlight: options.seed.flight, partialKeys: [...partialKeyMap(options.seed.keyScopes, options.params, removeBasePath(canonical.pathname, options.manifest?.config?.basePath || ''))] } : {}),
+    clientModules: options.manifest?.app?.clientModules || {},
+    cacheComponents: options.manifest?.config?.cacheComponents, cacheLife: options.manifest?.config?.cacheLife, cacheHandlers: options.manifest?.config?.cacheHandlers, cacheHandler: options.manifest?.config?.cacheHandler, cacheMaxMemorySize: options.manifest?.config?.cacheMaxMemorySize,
+    actions: options.manifest?.app?.actions || {}, actionKey: options.manifest?.app?.actionKey };
+}
+
+export function inspectAppStatic(options) {
+  return renderFlight({ ...requestOptions(options), operation: 'static-params' });
+}
+
+export async function prerenderAppRoute(options) {
+  const request = requestOptions(options);
+  const mode = request.cacheConfig.dynamic || 'auto';
+  if (request.cacheConfig.runtime === 'edge' || mode === 'force-dynamic' || (request.cacheConfig.revalidate === 0 && mode !== 'force-static')) {
+    return { dynamic: true, reason: request.cacheConfig.runtime === 'edge' ? 'runtime: edge' : mode === 'force-dynamic' ? 'dynamic: force-dynamic' : 'revalidate: 0' };
+  }
+  try {
+    const partial = request.cacheComponents === true && mode === 'auto';
+    const result = await renderFlight({ ...request, staticGeneration: { mode, partial } });
+    return await runRequestContext({ ...request, phase: 'render', staticGeneration: { mode } }, async () => {
+      const context = currentRequest();
+      try {
+        trackStaticDependency(result.staticMetadata, context);
+        if (result.status >= 500) throw new Error('Static App rendering failed');
+        let html;
+        if (result.navigation) html = result.navigation.body;
+        else {
+          const model = await decodeFlight(result.body, request.clientModules, request.distDir, { production: request.production });
+          if (partial) {
+            const shell = await prerenderPartialHtml(model, options.route, { strictMode: options.manifest?.config?.reactStrictMode !== false, unknownParams: request.partialParams?.length > 0 });
+            if (!shell) {
+              if (request.cacheConfig.instant === false) return { dynamic: true, reason: 'instant: false permits blocking request data outside Suspense' };
+              throw Object.assign(new Error(`Route ${request.routePattern}: uncached data was accessed outside of <Suspense>. Move request APIs, uncached fetches or unknown params into a component beneath <Suspense>, cache the data with "use cache", or explicitly permit blocking with export const instant = false.`), { code: 'PRNEXT_MISSING_SUSPENSE' });
+            }
+            if (result.staticMetadata?.metadataDynamic && !result.staticMetadata?.contentDynamic && !shell.clientDynamic) {
+              throw Object.assign(new Error(`Route ${request.routePattern}: generateMetadata() accesses uncached or request data while the page content is static. Cache the metadata with "use cache" or render a component that awaits connection() beneath <Suspense>.`), { code: 'PRNEXT_DYNAMIC_METADATA' });
+            }
+            if (shell.postponed) return { partial: { version: 1, ...shell, flight: result.body.toString('base64'),
+              ...(request.partialParams?.length ? { generic: { params: request.params, unknown: request.partialParams, path: new URL(request.url).pathname }, keyScopes: model.keyScopes || [] } : {}) },
+              metadata: { ...staticMetadata(context), generatedAt: Date.now() } };
+            if (result.staticMetadata?.dynamicReasons?.length) {
+              if (request.cacheConfig.instant === false) return { dynamic: true, reason: 'instant: false permits blocking request data outside Suspense' };
+              throw Object.assign(new Error(`Route ${request.routePattern}: request data was intercepted outside of a resumable <Suspense> boundary.`), { code: 'PRNEXT_MISSING_SUSPENSE' });
+            }
+            html = completeAppHtml(shell.shell, result.body, { ...options.route, css: [], fonts: [] });
+          } else {
+            html = completeAppHtml(await renderHtml(model.tree, model.router, { staticGeneration: true, strictMode: options.manifest?.config?.reactStrictMode !== false }), result.body, options.route);
+          }
+        }
+        if (staticMetadata(context)?.externalCache) return { dynamic: true, reason: 'External cache handlers require validation on every request' };
+        return { body: html, flight: result.body, ...staticMetadata(context), generatedAt: Date.now(),
+          status: result.status, headers: { ...result.headers, ...(result.headers?.location ? { location: addBasePath(result.headers.location, request.basePath) } : {}), 'content-type': 'text/html; charset=utf-8' } };
+      } finally { await flushCacheWork(context); }
+    });
+  } catch (error) {
+    if (error.code === 'PRNEXT_DYNAMIC_SERVER_USAGE' && mode === 'auto') return { dynamic: true, reason: error.dynamicReason || error.message };
+    throw error;
+  }
+}
+
+export async function renderAppIsrPage(options) {
+  const rendered = await prerenderAppRoute(options);
+  if (rendered.dynamic) return { status: 200, headers: {}, body: [],
+    isr: { dynamic: true, revalidate: 0, htmlLength: 0, dataLength: 0, tags: [], paths: [] } };
+  const html = Buffer.from(rendered.body);
+  return { status: rendered.status, headers: rendered.headers, body: [html, rendered.flight],
+    isr: { revalidate: rendered.revalidate, htmlLength: html.byteLength, dataLength: rendered.flight.byteLength,
+      tags: rendered.tags, paths: rendered.paths } };
+}

package/runtime/app-stream-channel.mjs

@@ -0,0 +1,92 @@
+// One initial transferable chunk, then one chunk per reader pull. The initial
+// credit removes a round trip while keeping the queue bounded to 64 KiB.
+export const APP_STREAM_CHUNK_BYTES = 64 * 1024;
+
+export function workerStreamChannel(port, id) {
+  const abort = new AbortController();
+  let credit = 0;
+  let wake;
+  let started = false;
+  let metadata;
+  let ended = false;
+  let previousSignal;
+  let combinedSignal;
+  const wait = async signal => {
+    while (!credit) {
+      signal.throwIfAborted();
+      await new Promise(resolve => {
+        wake = () => { signal.removeEventListener('abort', wake); resolve(); };
+        signal.addEventListener('abort', wake, { once: true });
+      });
+    }
+  };
+  return {
+    signal: abort.signal,
+    get started() { return started; },
+    credit() { credit = 1; wake?.(); wake = undefined; },
+    cancel() { abort.abort(new Error('App Router response was cancelled')); wake?.(); wake = undefined; },
+    start(value) { started = true; metadata = value; credit = 1; },
+    async write(bytes, signal = abort.signal, done = false) {
+      if (signal !== previousSignal) {
+        previousSignal = signal;
+        combinedSignal = signal === abort.signal ? signal : AbortSignal.any([abort.signal, signal]);
+      }
+      for (let offset = 0; offset < bytes.byteLength; offset += APP_STREAM_CHUNK_BYTES) {
+        if (!credit) await wait(combinedSignal);
+        combinedSignal.throwIfAborted();
+        credit--;
+        const length = Math.min(APP_STREAM_CHUNK_BYTES, bytes.byteLength - offset);
+        // A byte ReadableStream transfers its allocation to the reader. Keep
+        // that ownership across this bridge; Node's pooled Buffers are copied.
+        let chunk;
+        if (!Buffer.isBuffer(bytes) && offset === 0 && length === bytes.byteLength && bytes.buffer.byteLength <= APP_STREAM_CHUNK_BYTES) chunk = bytes;
+        else { chunk = new Uint8Array(length); chunk.set(bytes.subarray(offset, offset + length)); }
+        const last = offset + length === bytes.byteLength;
+        const message = { id, type: metadata ? 'start' : 'chunk', ...metadata,
+          chunk: chunk.buffer, byteOffset: chunk.byteOffset, byteLength: chunk.byteLength, done: done && last };
+        metadata = undefined;
+        port.postMessage(message, [chunk.buffer]);
+        if (message.done) ended = true;
+      }
+    },
+    end() {
+      if (ended) return;
+      ended = true;
+      if (metadata) port.postMessage({ id, type: 'start', ...metadata, done: true });
+      else port.postMessage({ id, type: 'end' });
+    },
+  };
+}
+
+export function parentStreamChannel(port, id, cancelled) {
+  let controller;
+  let settlePull;
+  let closed = false;
+  const body = new ReadableStream({
+    start(value) { controller = value; },
+    pull() {
+      return new Promise(resolve => {
+        settlePull = resolve;
+        port.postMessage({ id, type: 'credit' });
+      });
+    },
+    cancel(reason) {
+      closed = true;
+      settlePull?.();
+      port.postMessage({ id, type: 'cancel' });
+      cancelled(reason);
+    },
+  }, { highWaterMark: 0 });
+  return {
+    body,
+    chunk(buffer, offset = 0, length = buffer?.byteLength) {
+      if (closed) return;
+      if (!(buffer instanceof ArrayBuffer) || buffer.byteLength > APP_STREAM_CHUNK_BYTES ||
+          !Number.isInteger(offset) || !Number.isInteger(length) || offset < 0 || length < 0 || offset + length > buffer.byteLength) throw new Error('Invalid App Router stream chunk');
+      controller.enqueue(new Uint8Array(buffer, offset, length));
+      settlePull?.(); settlePull = undefined;
+    },
+    end() { if (!closed) { closed = true; controller.close(); } settlePull?.(); },
+    error(error) { if (!closed) { closed = true; controller.error(error); } settlePull?.(); },
+  };
+}

package/runtime/app-stream-html.mjs

@@ -0,0 +1,279 @@
+import React from 'react';
+import { fontPreloads } from './font-preload.mjs';
+import { isDynamicBailout } from '../compat/dynamic-bailout.cjs';
+import { renderToReadableStream, resume } from 'react-dom/server';
+import { AppRouterProvider } from '../compat/app-context.cjs';
+import { appContent } from './app-content.mjs';
+import { escapeHtml, MAX_RESPONSE_BYTES } from './http.mjs';
+import { appTimeoutError, appErrorDigest } from './app-errors.mjs';
+import { navigationResponse } from './navigation.mjs';
+import { addBasePath } from '../compat/paths.cjs';
+import { renderAppRecoveryShell } from './app-recovery.mjs';
+import { partialModel } from './app-partial-model.mjs';
+import { streamSelector } from './stream-select.mjs';
+
+// Do not insert bootstrap scripts inside a split HTML tag or raw-text element.
+// React may split a large inline script across arbitrary byte chunks.
+function htmlEnvelope({ resumed = false } = {}) {
+  let pending = '';
+  let closing = '';
+  let received = 0;
+  return {
+    append(text) {
+      received += Buffer.byteLength(text);
+      if (received > MAX_RESPONSE_BYTES) throw new Error('HTML response exceeds the 16 MiB PRNext limit');
+      pending += text;
+      let ready = '';
+      while (pending) {
+        const start = pending.indexOf('<');
+        if (start < 0) { ready += pending; pending = ''; break; }
+        if (start) { ready += pending.slice(0, start); pending = pending.slice(start); }
+        let end = -1;
+        if (pending.startsWith('<!--')) {
+          const comment = pending.indexOf('-->');
+          if (comment >= 0) end = comment + 2;
+        } else {
+          let quote;
+          for (let index = 1; index < pending.length; index++) {
+            const char = pending[index];
+            if (quote) { if (char === quote) quote = undefined; }
+            else if (char === '"' || char === "'") quote = char;
+            else if (char === '>') { end = index; break; }
+          }
+        }
+        if (end < 0) break;
+        const tag = pending.slice(0, end + 1);
+        const raw = /^<(script|style|textarea|title|svg|math)(?:\s|>)/i.exec(tag);
+        if (raw && !tag.endsWith('/>')) {
+          const match = new RegExp(`</${raw[1]}\\s*>`, 'i').exec(pending.slice(end + 1));
+          if (!match) break;
+          end += 1 + match.index + match[0].length;
+          ready += pending.slice(0, end); pending = pending.slice(end);
+        } else {
+          if (/^<\/(body|html)\s*>$/i.test(tag)) closing += tag;
+          else ready += tag;
+          pending = pending.slice(end + 1);
+        }
+      }
+      return ready;
+    },
+    finish() {
+      if (pending || !(resumed ? /^(?:<\/body><\/html>){1,2}$/i : /^<\/body><\/html>$/i).test(closing)) throw new Error('App Router root layout did not close its body and html elements');
+      return resumed ? '</body></html>' : closing;
+    },
+  };
+}
+
+// The SSR decoder and HTML bootstrap share each Flight allocation. Unlike
+// ReadableStream.tee(), this tap stops reading when the HTML consumer stalls.
+// Before a document shell exists, at most the overall 16 MiB response limit can
+// accumulate: an async root layout may need the complete model to produce it.
+function flightTap(source) {
+  const reader = source.getReader();
+  const queue = [];
+  let bytes = 0;
+  let done = false;
+  let failure;
+  let outputStarted = false;
+  let wakeData;
+  let wakeSpace;
+  const finish = error => {
+    done = true; failure = error;
+    wakeData?.(); wakeData = undefined;
+    wakeSpace?.(); wakeSpace = undefined;
+  };
+  const cancel = async reason => { finish(reason); await reader.cancel(reason).catch(() => {}); };
+  const body = new ReadableStream({
+    async pull(controller) {
+      try {
+        while (!done && outputStarted && bytes >= 128 * 1024) await new Promise(resolve => { wakeSpace = resolve; });
+        if (done) { if (failure) controller.error(failure); else controller.close(); return; }
+        const next = await reader.read();
+        if (next.done) { finish(); controller.close(); return; }
+        queue.push(next.value); bytes += next.value.byteLength;
+        wakeData?.(); wakeData = undefined;
+        controller.enqueue(next.value);
+      } catch (error) { finish(error); controller.error(error); }
+    },
+    cancel,
+  }, { highWaterMark: 0 });
+  return {
+    body, cancel,
+    startOutput() { outputStarted = true; },
+    async next() {
+      while (!queue.length && !done) await new Promise(resolve => { wakeData = resolve; });
+      if (queue.length) {
+        const value = queue.shift(); bytes -= value.byteLength;
+        wakeSpace?.(); wakeSpace = undefined;
+        return { value, done: false };
+      }
+      if (failure) throw failure;
+      return { done: true };
+    },
+  };
+}
+
+export async function renderProgressiveAppHtml({ result, request, route, responseHeaders, decodeFlight, signal, timeoutMs = 25_000, partial }) {
+  const nonceAttribute = request.nonce ? ` nonce="${escapeHtml(request.nonce)}"` : '';
+  const tap = flightTap(result.body);
+  const abort = new AbortController();
+  const timeout = setTimeout(() => abort.abort(appTimeoutError('HTML stream', timeoutMs)), timeoutMs);
+  const combinedSignal = signal ? AbortSignal.any([signal, abort.signal]) : abort.signal;
+  let reader;
+  let renderError;
+  let committed = Boolean(partial?.shellSent);
+  let control;
+  let model;
+  const cancel = async reason => {
+    clearTimeout(timeout);
+    combinedSignal.removeEventListener('abort', onAbort);
+    if (!abort.signal.aborted) abort.abort(reason || new Error('App Router response was cancelled'));
+    await Promise.allSettled([tap.cancel(reason), reader?.cancel(reason)]);
+  };
+  const onAbort = () => { void cancel(combinedSignal.reason); };
+  combinedSignal.addEventListener('abort', onAbort, { once: true });
+  try {
+    model = await decodeFlight(tap.body, request.clientModules, request.distDir, { production: request.production });
+    const renderOptions = {
+      signal: combinedSignal,
+      nonce: request.nonce,
+      bootstrapScriptContent: 'self.__PRNEXT_FLIGHT_STREAM__=self.__PRNEXT_FLIGHT_STREAM__||[];',
+      bootstrapModules: route.client ? [route.client] : undefined,
+      onError(error) {
+        if (isDynamicBailout(error)) return error.digest;
+        if (combinedSignal.aborted) return error?.digest;
+        const navigation = navigationResponse(error);
+        if (navigation) {
+          if (committed) control = navigation;
+          else renderError ??= error;
+        } else console.error('[prnext]', error?.stack || error);
+        return appErrorDigest(error);
+      },
+    };
+    const resumedModel = partial?.resumeKeys?.length ? partialModel(model, { keyMap: new Map(partial.resumeKeys) }) : model;
+    const element = React.createElement(request.strictMode !== false ? React.StrictMode : React.Fragment, null, React.createElement(AppRouterProvider, { router: resumedModel.router, nonce: request.nonce }, appContent(resumedModel.tree)));
+    // React owns and mutates its opaque continuation during resume. Parsed
+    // artifacts can be shared, but each HTML request needs its own continuation.
+    const html = partial ? await resume(element, structuredClone(partial.postponed), renderOptions) : await renderToReadableStream(element, renderOptions);
+    reader = html.getReader();
+    const decoder = new TextDecoder();
+    let prefix = partial?.shell || '';
+    let htmlDone = false;
+    // Validate the actual rendered root before handing headers to the transport.
+    // A Suspense shell already contains these tags, so delayed children do not
+    // block the first byte. A root that omits them fails before a 200 is sent.
+    while (!/<body(?:\s[^>]*)?>/i.test(prefix)) {
+      const next = await reader.read();
+      if (next.done) { htmlDone = true; prefix += decoder.decode(); break; }
+      prefix += decoder.decode(next.value, { stream: true });
+      if (Buffer.byteLength(prefix) > MAX_RESPONSE_BYTES) throw new Error('HTML shell exceeds the 16 MiB PRNext limit');
+    }
+    if (renderError) throw renderError;
+    if (!/<html(?:\s|>)/i.test(prefix) || !/<body(?:\s|>)/i.test(prefix) || !/<\/head>/i.test(prefix)) {
+      throw Object.assign(new Error('App Router root layout must render <html>, <head> and <body> elements'), { code: 'PRNEXT_INVALID_ROOT_LAYOUT' });
+    }
+    const styles = fontPreloads(route.fonts, request.nonce) + (route.css || []).map(href => `<link rel="stylesheet" href="${escapeHtml(href)}">`).join('');
+    if (styles && !partial) prefix = prefix.replace(/<\/head>/i, `${styles}</head>`);
+    tap.startOutput();
+    committed = true;
+    const body = (async function* () {
+      let total = 0;
+      const envelope = htmlEnvelope({ resumed: Boolean(partial) });
+      const encode = value => {
+        const bytes = Buffer.from(value);
+        total += bytes.byteLength;
+        if (total > MAX_RESPONSE_BYTES) throw new Error('Response exceeds the 16 MiB PRNext limit');
+        return bytes;
+      };
+      let flightDone = false;
+      const selection = streamSelector();
+      if (!htmlDone) selection.watch('html', reader.read());
+      selection.watch('flight', tap.next());
+      try {
+        const first = envelope.append(prefix);
+        prefix = '';
+        if (first && !partial?.shellSent) yield encode(first);
+        while (!htmlDone || !flightDone) {
+          combinedSignal.throwIfAborted();
+          const next = await selection.next();
+          if (next.type === 'html') {
+            if (next.done) {
+              htmlDone = true;
+              const text = envelope.append(decoder.decode());
+              if (text) yield encode(text);
+            } else {
+              const text = envelope.append(decoder.decode(next.value, { stream: true }));
+              selection.watch('html', reader.read());
+              if (text) yield encode(text);
+            }
+          } else {
+            if (next.done) { flightDone = true; }
+            else {
+              const encoded = Buffer.from(next.value.buffer, next.value.byteOffset, next.value.byteLength).toString('base64');
+              selection.watch('flight', tap.next());
+              yield encode(`<script${nonceAttribute}>(self.__PRNEXT_FLIGHT_STREAM__||=[]).push("${encoded}");document.currentScript.remove()</script>`);
+            }
+          }
+          if (control) {
+            const current = control; control = null;
+            if (current.headers.location) yield encode(`<meta http-equiv="refresh" content="${current.status === 308 ? 0 : 1};url=${escapeHtml(addBasePath(current.headers.location, request.basePath || ''))}">`);
+            else if (current.status === 404) yield encode('<meta name="robots" content="noindex">');
+          }
+        }
+        yield encode(`<script${nonceAttribute}>self.__PRNEXT_FLIGHT_STREAM__.push(null);document.currentScript.remove()</script>` + envelope.finish());
+      } finally {
+        selection.close();
+        combinedSignal.removeEventListener('abort', onAbort);
+        await cancel();
+      }
+    })();
+    // An error encoded in Flight may be contained by a valid Suspense shell.
+    // Ordinary GET errors select HTTP 500 only when that shell also fails.
+    const status = result.rscError && result.status === 500 && ['GET', 'HEAD'].includes(request.method) ? 200 : result.status;
+    return { status, headers: { ...responseHeaders, ...result.headers, 'content-type': 'text/html; charset=utf-8' }, body, cancel };
+  } catch (error) {
+    if (!committed && !combinedSignal.aborted && error?.statusCode !== 504 &&
+        error?.code !== 'PRNEXT_INVALID_ROOT_LAYOUT' && !isDynamicBailout(error) && (!navigationResponse(error) || (route.parallel && navigationResponse(error).status === 404))) {
+      try {
+        // Next emits an empty document after a shell failure. The original
+        // Flight stream still carries the failing subtree to client boundaries;
+        // never rerun a GET just to render an error UI on the server.
+        const shell = await renderAppRecoveryShell(model?.head, { signal: combinedSignal, timeoutMs });
+        const end = shell.lastIndexOf('</body>');
+        const bootstrap = `<script${nonceAttribute}>self.__PRNEXT_FLIGHT_STREAM__=self.__PRNEXT_FLIGHT_STREAM__||[];</script>` +
+          (route.client ? `<script type="module" async${nonceAttribute} src="${escapeHtml(route.client)}"></script>` : '');
+        const prefix = shell.slice(0, end) + bootstrap;
+        const closing = shell.slice(end);
+        tap.startOutput();
+        const body = (async function* () {
+          let total = 0;
+          const encode = value => {
+            const bytes = Buffer.from(value);
+            total += bytes.byteLength;
+            if (total > MAX_RESPONSE_BYTES) throw new Error('Response exceeds the 16 MiB PRNext limit');
+            return bytes;
+          };
+          try {
+            yield encode(prefix);
+            for (;;) {
+              combinedSignal.throwIfAborted();
+              const next = await tap.next();
+              if (next.done) break;
+              const encoded = Buffer.from(next.value.buffer, next.value.byteOffset, next.value.byteLength).toString('base64');
+              yield encode(`<script${nonceAttribute}>(self.__PRNEXT_FLIGHT_STREAM__||=[]).push("${encoded}");document.currentScript.remove()</script>`);
+            }
+            yield encode(`<script${nonceAttribute}>self.__PRNEXT_FLIGHT_STREAM__.push(null);document.currentScript.remove()</script>` + closing);
+          } finally { await cancel(); }
+        })();
+        return { status: route.parallel && navigationResponse(error)?.status === 404 ? 404 : 500, headers: { ...responseHeaders, ...result.headers, 'content-type': 'text/html; charset=utf-8' }, body, cancel };
+      } catch (recoveryError) {
+        await cancel(recoveryError);
+        throw combinedSignal.reason?.statusCode === 504 ? combinedSignal.reason : recoveryError;
+      }
+    }
+    combinedSignal.removeEventListener('abort', onAbort);
+    await cancel(error);
+    if (combinedSignal.reason?.statusCode === 504) throw combinedSignal.reason;
+    throw error;
+  }
+}

package/runtime/build-directory.mjs

@@ -0,0 +1,48 @@
+import { open, realpath, lstat, mkdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+export const OUTPUT_POINTER = '.prnext-output.json';
+const reserved = new Set(['public','node_modules','app','pages','src','components','lib','packages','target','.git','.prnext-output.json']);
+export function validateDistDir(value = '.prnext') {
+  if (typeof value !== 'string' || !value || Buffer.byteLength(value) > 1024 || path.isAbsolute(value) || /[\\\x00-\x1f\x7f:]/.test(value)) throw new TypeError('distDir must be a relative directory inside the project');
+  const segments = value.split('/');
+  if (segments.some(segment => !segment || segment === '.' || segment === '..') || reserved.has(segments[0])) throw new TypeError('distDir cannot traverse or replace project source, public, dependency or repository directories');
+  return value;
+}
+
+/** Starting a published artifact never evaluates application configuration. */
+export async function readBuildDirectory(root) {
+  let file;
+  try {
+    file = await open(path.join(root, OUTPUT_POINTER), 'r');
+    const buffer = Buffer.alloc(4097);
+    const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
+    if (bytesRead > 4096) throw new Error('Invalid PRNext output pointer: exceeds 4 KiB');
+    const pointer = JSON.parse(buffer.subarray(0, bytesRead).toString());
+    if (typeof pointer?.distDir !== 'string') throw new Error('Invalid PRNext output pointer: missing distDir');
+    return validateDistDir(pointer.distDir);
+  } catch (error) { if (error.code === 'ENOENT') return '.prnext'; throw error; }
+  finally { await file?.close(); }
+}
+
+/** Refuse symlink destinations or ancestors before any build can replace them. */
+export async function prepareBuildDirectory(root, relative) {
+  const canonical = await realpath(root);
+  let current = canonical;
+  for (const part of validateDistDir(relative).split('/')) {
+    current = path.join(current, part);
+    try {
+      const entry = await lstat(current);
+      if (entry.isSymbolicLink() || !entry.isDirectory()) throw new Error('distDir must contain only real directories, not symbolic links or files');
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  try {
+    await lstat(current);
+    const manifest = JSON.parse(await readFile(path.join(current, 'manifest.json'), 'utf8'));
+    if (manifest.version !== 1 || !Array.isArray(manifest.routes)) throw new Error('invalid manifest');
+  } catch (error) {
+    if (error.code !== 'ENOENT' || await lstat(current).then(() => true, () => false)) throw new Error('distDir already exists without a PRNext manifest; refusing to replace unrelated files');
+  }
+  await mkdir(path.dirname(current), {recursive:true});
+  return current;
+}

package/runtime/cache-arguments.mjs

@@ -0,0 +1,33 @@
+const MAX_BYTES = 2 * 1024 * 1024;
+const tooLarge = () => new Error("'use cache' arguments exceed 2 MiB");
+export async function encodeCacheArguments(body) {
+  if (typeof body === 'string') {
+    if (Buffer.byteLength(body) > MAX_BYTES) throw tooLarge();
+    return Buffer.from(body);
+  }
+  const entries = [];
+  let size = 0;
+  for (const [name, value] of body) {
+    const text = typeof value === 'string';
+    const head = JSON.stringify([name, text ? 'text' : 'blob', text ? '' : value.type, text ? '' : value.name]);
+    const headLength = Buffer.byteLength(head);
+    const length = text ? Buffer.byteLength(value) : value.size;
+    size += 8 + headLength + length;
+    if (size > MAX_BYTES) throw tooLarge();
+    if (entries.length >= 10000) throw new Error("'use cache' arguments exceed 10000 encoded fields");
+    entries.push({ head, headLength, value, length, text });
+  }
+  // Check the complete body before copying Blob bytes or invoking decodeReply.
+  const result = Buffer.allocUnsafe(size);
+  let offset = 0;
+  for (const entry of entries) {
+    result.writeUInt32BE(entry.headLength, offset);
+    result.writeUInt32BE(entry.length, offset + 4);
+    offset += 8;
+    offset += result.write(entry.head, offset);
+    if (entry.text) result.write(entry.value, offset);
+    else Buffer.from(await entry.value.arrayBuffer()).copy(result, offset);
+    offset += entry.length;
+  }
+  return result;
+}