@wular/pnext 0.0.1

package/src/compat/cache-control.ts

@@ -0,0 +1,269 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { nextCompatEnabled } from '../compat';
+import type { ResolvedConfig } from '../config';
+import type { ResponseFinalizer, ResponseFinalizerContext } from '../extensions';
+import { getNextConfig } from './next/config-loader';
+import {
+  evaluateConditions,
+  parseConditions,
+  substitute,
+  type RewriteCondition,
+  type RewriteRequestContext,
+} from './next/rewrites';
+
+const DEFAULT_EXPIRE_TIME = 31536000;
+
+interface HeaderRule {
+  regex: RegExp;
+  paramNames: string[];
+  headers: [string, string][];
+  has: RewriteCondition[];
+  missing: RewriteCondition[];
+}
+
+interface HeaderEntry {
+  source?: string;
+  headers?: unknown;
+  has?: unknown;
+  missing?: unknown;
+}
+
+interface RevalidateRule {
+  regex: RegExp;
+  revalidateSeconds: number;
+}
+
+interface ConfigHeader {
+  key?: unknown;
+  value?: unknown;
+}
+
+export function cacheControlFinalizers(config: ResolvedConfig): ResponseFinalizer[] {
+  if (!nextCompatEnabled(config)) return [];
+
+  let rules: Promise<HeaderRule[]> | undefined;
+  let pagesRevalidateRules: RevalidateRule[] | undefined;
+  const finalizer: ResponseFinalizer = async ctx => {
+    rules ??= loadHeaderRules();
+    applyConfigHeaders(ctx, await rules);
+    pagesRevalidateRules ??= loadPagesRevalidateRules(config.root);
+    applyDefaultIsrHeader(ctx, pagesRevalidateRules);
+  };
+  return [finalizer];
+}
+
+async function loadHeaderRules(): Promise<HeaderRule[]> {
+  const producer = getNextConfig().headers;
+  if (typeof producer !== 'function') return [];
+
+  let entries: unknown;
+  try {
+    entries = await (producer as () => unknown)();
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(entries)) return [];
+
+  const rules: HeaderRule[] = [];
+  for (const entry of entries as HeaderEntry[]) {
+    if (!entry?.source || !Array.isArray(entry.headers)) continue;
+    const compiled = compileHeaderSource(entry.source);
+    if (!compiled) continue;
+    const has = parseConditions(entry.has);
+    const missing = parseConditions(entry.missing);
+    if (!has || !missing) continue;
+    const headers = headerPairs(entry.headers);
+    if (headers.length === 0) continue;
+    rules.push({ ...compiled, headers, has, missing });
+  }
+  return rules;
+}
+
+/**
+ * Compile a next.config `headers`/`redirects` source pattern into a pathname regex. Mirrors the
+ * rewrites source compiler for `:param` tokens but, unlike it, escapes literal regex-special characters
+ * in plain segments (the `.` in `/favicon.ico`, say) instead of rejecting the rule - Next's
+ * path-to-regexp treats those as literals. Raw regex bodies still only appear inside `:param(...)`.
+ */
+function compileHeaderSource(source: string): { regex: RegExp; paramNames: string[] } | null {
+  const paramNames: string[] = [];
+  const parts: string[] = [];
+  for (const segment of source.split('/').filter(Boolean)) {
+    const custom = /^:([A-Za-z_$][\w$]*)\((.*)\)$/.exec(segment);
+    if (custom?.[1] !== undefined && custom[2] !== undefined) {
+      paramNames.push(custom[1]);
+      parts.push(`(${custom[2]})`);
+      continue;
+    }
+    const catchAll = /^:([A-Za-z_$][\w$]*)[*+]$/.exec(segment);
+    if (catchAll?.[1]) {
+      paramNames.push(catchAll[1]);
+      parts.push('(.*)');
+      continue;
+    }
+    const optional = /^:([A-Za-z_$][\w$]*)\?$/.exec(segment);
+    if (optional?.[1]) {
+      paramNames.push(optional[1]);
+      parts.push('([^/]*)');
+      continue;
+    }
+    const param = /^:([A-Za-z_$][\w$]*)$/.exec(segment);
+    if (param?.[1]) {
+      paramNames.push(param[1]);
+      parts.push('([^/]+)');
+      continue;
+    }
+    // Plain literal segment: escape regex-special characters so `.` etc. match
+    // literally rather than acting as regex metacharacters.
+    parts.push(segment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+  }
+  return { regex: new RegExp(`^/${parts.join('/')}/?$`), paramNames };
+}
+
+function headerPairs(headers: unknown[]): [string, string][] {
+  const pairs: [string, string][] = [];
+  for (const header of headers as ConfigHeader[]) {
+    if (typeof header?.key !== 'string' || typeof header.value !== 'string') continue;
+    pairs.push([header.key, header.value]);
+  }
+  return pairs;
+}
+
+function applyConfigHeaders(ctx: ResponseFinalizerContext, rules: readonly HeaderRule[]): void {
+  if (rules.length === 0) return;
+  const url = ctx.request.url;
+  const requestCtx: RewriteRequestContext = {
+    host: url.host,
+    headers: ctx.request.headers,
+    cookies: parseCookieHeader(ctx.request.headers.get('cookie')),
+    query: url.searchParams,
+  };
+
+  // Config `Set-Cookie` headers must be appended (each entry is its own header,
+  // never overwriting) and must precede the response's own Set-Cookie headers —
+  // Next applies config headers at the router layer before the route's own
+  // cookies (set-cookies suite asserts [...nextConfigHeaders, ...cookies]).
+  const configSetCookies: string[] = [];
+  for (const rule of rules) {
+    const match = rule.regex.exec(url.pathname);
+    if (!match) continue;
+    const params: Record<string, string> = {};
+    rule.paramNames.forEach((name, index) => {
+      params[name] = match[index + 1] ?? '';
+    });
+    const conditionParams = evaluateConditions(rule, requestCtx);
+    if (conditionParams === null) continue;
+    Object.assign(params, conditionParams);
+    for (const [key, value] of rule.headers) {
+      const resolved = substitute(value, params).pathname;
+      if (key.toLowerCase() === 'set-cookie') configSetCookies.push(resolved);
+      else ctx.headers.set(key, resolved);
+    }
+  }
+  if (configSetCookies.length > 0) {
+    const existing =
+      (ctx.headers as Headers & { getSetCookie?: () => string[] }).getSetCookie?.() ?? [];
+    ctx.headers.delete('set-cookie');
+    for (const cookie of configSetCookies) ctx.headers.append('set-cookie', cookie);
+    for (const cookie of existing) ctx.headers.append('set-cookie', cookie);
+  }
+}
+
+function applyDefaultIsrHeader(
+  ctx: ResponseFinalizerContext,
+  pagesRevalidateRules: readonly RevalidateRule[],
+): void {
+  const pagesRevalidateSeconds = pagesRevalidateRules.find(rule =>
+    rule.regex.test(ctx.request.url.pathname),
+  )?.revalidateSeconds;
+  const existing = ctx.headers.get('cache-control');
+  // An RSC payload is never browser-cacheable: the flight response embeds the
+  // render's data, so a cached copy replays stale content after a revalidation
+  // (actions "should invalidate client cache when path is revalidated"). Match
+  // the RSC document path in register-segment, which stamps `private, no-store`.
+  if (isRscPayload(ctx)) {
+    if (existing === null || isBrowserCacheable(existing)) {
+      ctx.headers.set('cache-control', 'private, no-store');
+    }
+    return;
+  }
+  if (existing && (pagesRevalidateSeconds === undefined || existing !== 'no-store')) return;
+  const revalidateSeconds =
+    pagesRevalidateSeconds ??
+    (ctx.routeMode === 'isr' ? ctx.hints?.revalidateSeconds : undefined);
+  if (typeof revalidateSeconds !== 'number' || revalidateSeconds <= 0) return;
+  const config = getNextConfig();
+  const expireTime =
+    typeof config.expireTime === 'number' ? config.expireTime : DEFAULT_EXPIRE_TIME;
+  const swr = Math.max(0, expireTime - revalidateSeconds);
+  ctx.headers.set('cache-control', `s-maxage=${revalidateSeconds}, stale-while-revalidate=${swr}`);
+}
+
+/** A flight response: core's `data` route kind, or an `_rsc` cache-busted URL. */
+function isRscPayload(ctx: ResponseFinalizerContext): boolean {
+  return ctx.routeKind === 'data' || ctx.request.url.searchParams.has('_rsc');
+}
+
+/** True for a cache-control a browser may reuse (no `no-store`/`no-cache`). */
+function isBrowserCacheable(value: string): boolean {
+  return !/\bno-store\b|\bno-cache\b/i.test(value);
+}
+
+function loadPagesRevalidateRules(root: string): RevalidateRule[] {
+  const pagesDir = path.join(root, 'pages');
+  if (!existsSync(pagesDir)) return [];
+  const rules: RevalidateRule[] = [];
+  for (const file of walkFiles(pagesDir)) {
+    const source = readFileSync(file, 'utf8');
+    if (!/\bgetStaticProps\b/.test(source)) continue;
+    const match = /\brevalidate\s*:\s*(\d+)/.exec(source);
+    if (!match?.[1]) continue;
+    const regex = pagesRouteRegex(path.relative(pagesDir, file));
+    if (!regex) continue;
+    rules.push({ regex, revalidateSeconds: Number(match[1]) });
+  }
+  return rules;
+}
+
+function walkFiles(dir: string): string[] {
+  const files: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const file = path.join(dir, entry.name);
+    if (entry.isDirectory()) files.push(...walkFiles(file));
+    else if (/\.(?:tsx|ts|jsx|js|mjs)$/.test(entry.name)) files.push(file);
+  }
+  return files;
+}
+
+function pagesRouteRegex(relative: string): RegExp | undefined {
+  const withoutExt = relative.replace(/\.(?:tsx|ts|jsx|js|mjs)$/, '').split(path.sep).join('/');
+  const route = withoutExt === 'index' ? '' : withoutExt.replace(/\/index$/, '');
+  const parts = route.split('/').filter(Boolean);
+  const pattern = parts
+    .map(part => {
+      if (/^\[\[\.\.\.[^\]]+\]\]$/.test(part)) return '(?:/.*)?';
+      if (/^\[\.\.\.[^\]]+\]$/.test(part)) return '/.+';
+      if (/^\[[^\]]+\]$/.test(part)) return '/[^/]+';
+      return `/${escapeRegex(part)}`;
+    })
+    .join('');
+  return new RegExp(`^${pattern || '/'}\\/?$`);
+}
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function parseCookieHeader(header: string | null): Record<string, string> {
+  const cookies: Record<string, string> = {};
+  if (!header) return cookies;
+  for (const part of header.split(';')) {
+    const index = part.indexOf('=');
+    if (index === -1) continue;
+    const name = part.slice(0, index).trim();
+    if (!name) continue;
+    cookies[name] = decodeURIComponent(part.slice(index + 1).trim());
+  }
+  return cookies;
+}

package/src/compat/client/base-path.ts

@@ -0,0 +1,64 @@
+// Client basePath helpers (COMPAT - ships to the browser).
+//
+// The server injects `window.__PNEXT_BASE_PATH__` when `next.config.basePath` is set. The core router
+// treats every same-origin URL as soft-navigable, but under a basePath an absolute same-host URL
+// *outside* the basePath (a `basePath:false` rewrite target, say) must be a real MPA navigation, not a
+// soft swap. These helpers give the core router that boundary check without a next.config dependency.
+//
+// Core reads them through a registered hook. A pure-core app never sets the global, so basePath() is ''
+// and every same-origin URL stays soft-navigable exactly as before.
+
+declare global {
+  interface Window {
+    __PNEXT_BASE_PATH__?: string;
+  }
+  var __PNEXT_BASE_PATH__: string | undefined;
+}
+
+/**
+ * The configured basePath ('' when unset). Isomorphic: the client reads the
+ * `window` global the server injects (register-render basePathScript); the
+ * server reads the `globalThis` global set when next.config is loaded
+ * (config-loader setNextConfig). Neither branch imports the esbuild-backed
+ * config loader, so this stays safe to ship to the browser.
+ */
+export function basePath(): string {
+  if (process.browser || typeof window !== 'undefined') return window.__PNEXT_BASE_PATH__ ?? '';
+  return globalThis.__PNEXT_BASE_PATH__ ?? '';
+}
+
+/**
+ * Prefix a root-relative in-app path with the configured basePath (Next's
+ * addBasePath). Absolute URLs, protocol-relative URLs, non-root-relative
+ * strings, and paths already under the basePath are returned unchanged. A
+ * no-basePath app is always a no-op.
+ */
+export function addBasePath(path: string): string {
+  const base = basePath();
+  if (!base) return path;
+  if (!path.startsWith('/') || path.startsWith('//')) return path;
+  if (path === '/') return base;
+  if (path === base || path.startsWith(`${base}/`)) return path;
+  return `${base}${path}`;
+}
+
+/** Strip the configured basePath prefix from an in-app path (inverse of addBasePath). */
+export function stripBasePath(path: string): string {
+  const base = basePath();
+  if (!base) return path;
+  if (path === base) return '/';
+  if (path.startsWith(`${base}/`)) return path.slice(base.length);
+  return path;
+}
+
+/**
+ * True when `url` is same-origin but falls outside the configured basePath - i.e. the router must
+ * hard-navigate to it (a `basePath:false` target). Always false when no basePath is configured.
+ */
+export function isOutsideBasePath(url: URL): boolean {
+  const base = basePath();
+  if (!base) return false;
+  if ((process.browser || typeof window !== 'undefined') && url.origin !== window.location.origin) return false;
+  const path = url.pathname;
+  return path !== base && !path.startsWith(`${base}/`);
+}

package/src/compat/client/css-order.ts

@@ -0,0 +1,36 @@
+// Next preserves the incoming document's stylesheet precedence on soft nav.
+// Shared links otherwise retain their old position while newly-needed links
+// append, which reverses ties in the CSS cascade after a route transition.
+export function reconcileNextStylesheets(incoming: Document) {
+  const order = new Map<string, number>();
+  for (const link of incoming.querySelectorAll<HTMLLinkElement>('link[rel="stylesheet"][href]')) {
+    const href = absoluteHref(link);
+    if (href && nextStylesheet(href) && !order.has(href)) order.set(href, order.size);
+  }
+  if (order.size < 2) return;
+
+  const current = [...document.querySelectorAll<HTMLLinkElement>('link[rel="stylesheet"][href]')].filter(
+    link => order.has(link.href),
+  );
+  if (current.length < 2) return;
+
+  const rank = (link: HTMLLinkElement) => order.get(link.href) ?? 0;
+  if (current.every((link, index) => index === 0 || rank(current[index - 1]!) <= rank(link))) return;
+
+  const sorted = [...current].sort((left, right) => rank(left) - rank(right));
+  let previous = sorted[0]!;
+  for (const link of sorted.slice(1)) {
+    if (previous.nextSibling !== link) previous.after(link);
+    previous = link;
+  }
+}
+
+function absoluteHref(link: HTMLLinkElement) {
+  const href = link.getAttribute('href');
+  return href ? new URL(href, location.href).href : undefined;
+}
+
+function nextStylesheet(href: string) {
+  const url = new URL(href, location.href);
+  return url.origin === location.origin && url.pathname.startsWith('/assets/');
+}

package/src/compat/client/errors/control-flow.ts

@@ -0,0 +1,92 @@
+// Client-side control-flow error handling (COMPAT).
+//
+// notFound()/forbidden()/unauthorized()/redirect() called during a CLIENT-side render throw the same
+// control-flow errors the server throws. React routes them to the nearest error boundary, but - exactly
+// like Next - a boundary must NOT render its error UI for one: it must RE-THROW so the control error
+// propagates. Client-side there is no server render pass to catch it, so this runtime intercepts the
+// propagated error and drives the browser to the correct outcome:
+//
+//   - notFound / forbidden / unauthorized: soft-navigate to the CURRENT url so the server re-renders
+//     it. On that render the same control-flow call fires server-side (deterministic for the same
+//     inputs) and the server resolves the nearest boundary with the right status.
+//   - redirect / permanentRedirect: navigate to the target (soft for same-origin, hard for
+//     cross-origin), matching redirect()'s browser path.
+//
+// Detection reuses the core control-flow predicates so the digest scheme stays single-sourced.
+
+import {
+  isForbiddenError,
+  isNotFoundError,
+  isRedirectError,
+  isUnauthorizedError,
+  type PNextRedirectError,
+} from '../../../api/navigation';
+import { isPostpone } from '../../../ppr-postpone';
+import { softNavigate } from '../../../api/router';
+
+/** True for a Next control-flow error that a boundary must re-throw, not render. */
+export function isControlFlowError(error: unknown): boolean {
+  return (
+    isRedirectError(error) ||
+    isNotFoundError(error) ||
+    isForbiddenError(error) ||
+    isUnauthorizedError(error) ||
+    isPostpone(error)
+  );
+}
+
+/**
+ * Drive the browser to the outcome a client-side control-flow error demands.
+ * Returns true when the error was a control-flow error (and has been handled),
+ * false otherwise (a real error the caller must surface to a boundary).
+ */
+export function handleControlFlowError(error: unknown): boolean {
+  if (isRedirectError(error)) {
+    applyRedirect(error);
+    return true;
+  }
+  if (isNotFoundError(error) || isForbiddenError(error) || isUnauthorizedError(error)) {
+    // Re-render the current URL server-side: the same control-flow call fires
+    // during that render and the server resolves the matching boundary + status.
+    // replace:true keeps history intact (the URL did not change); scroll:false
+    // avoids a jump. Fall back to a full reload if the soft-nav itself fails.
+    if (process.browser || typeof window !== 'undefined') {
+      void softNavigate(location.href, { replace: true, scroll: false }).catch(() => {
+        location.reload();
+      });
+    }
+    return true;
+  }
+  if (isPostpone(error)) {
+    // A postpone escaping to the client has nothing to resume against here; a
+    // reload re-renders from the server. Treated as handled so it never lands
+    // in an error boundary as a "real" error.
+    if (process.browser || typeof window !== 'undefined') location.reload();
+    return true;
+  }
+  return false;
+}
+
+function applyRedirect(error: PNextRedirectError): void {
+  if (!process.browser && typeof window === 'undefined') return;
+  const target = error.location;
+  let sameOrigin = false;
+  try {
+    sameOrigin = new URL(target, location.href).origin === location.origin;
+  } catch {
+    sameOrigin = false;
+  }
+  const replace = error.status === 303 || error.status === 307 || error.status === 308;
+  if (sameOrigin) {
+    void softNavigate(target, { replace }).catch(() => {
+      hardNavigate(target, replace);
+    });
+  } else {
+    hardNavigate(target, replace);
+  }
+}
+
+function hardNavigate(target: string, replace: boolean): void {
+  if (replace) location.replace(target);
+  else location.assign(target);
+}

package/src/compat/client/errors/error-boundary.ts

@@ -0,0 +1,222 @@
+// Client-side error boundary (COMPAT).
+//
+// A preact class error boundary wrapping a hydrated route/island subtree so a CLIENT-side throw
+// post-hydration is caught and rendered by the route's `error.js` instead of tearing down the whole
+// preact tree. Mirrors Next's boundary:
+//
+//   - Control-flow errors are RE-THROWN, never rendered - the install layer's window handler drives
+//     them to the correct navigation outcome. A boundary that rendered UI for these would swallow the
+//     control flow.
+//   - Client-thrown errors have NO digest (only server errors carry one), so the error prop is a plain
+//     Error whose message is the throw's String(value); a thrown undefined/null/string passes through
+//     unwrapped, matching Next's client channel.
+//   - reset() clears the caught error and re-renders the children in place, recovering a
+//     client-component error whose failure lived in the hydrated subtree. unstable_retry() additionally
+//     soft-refreshes, which is what a data-dependent (server) failure needs.
+//
+// When no route error component is available the boundary mounts global-error.
+
+import { Component, h, type ComponentChildren, type ComponentType } from 'preact';
+import { isControlFlowError, handleControlFlowError } from './control-flow';
+import { isNotFoundError } from '../../../api/navigation';
+import { untagPrimitiveThrow } from './primitive-throw';
+
+// ---------------------------------------------------------------------------
+// KNOWN GAP (preact core, not fully fixable from an options hook): a CLIENT
+// `throw undefined` / `throw null` can arrive here as a synthetic TypeError when
+// preact dereferences `thrown.then` before boundary interception.
+// Normalize that sentinel back to raw nullish values so error UIs render as
+// `undefined`/`null`, matching Next behavior.
+// ---------------------------------------------------------------------------
+
+export type RouteErrorComponent = ComponentType<{
+  error: unknown;
+  reset: () => void;
+  unstable_retry?: () => void;
+}>;
+export type RouteNotFoundComponent = ComponentType<Record<string, never>>;
+
+interface BoundaryProps {
+  /** The route's nearest error.js component; when absent the boundary escalates. */
+  errorComponent?: RouteErrorComponent;
+  notFoundComponent?: RouteNotFoundComponent;
+  /**
+   * Next's default 404 UI, handed in by the generated runtime - and emitted by it ONLY when some route
+   * can reach this fallback (no not-found.* of its own). An app whose boundary routes all have one
+   * never ships error-ui.ts.
+   */
+  builtInNotFound?: RouteNotFoundComponent;
+  /** Soft-refresh invoked by reset() after clearing the error. */
+  onReset?: () => void;
+  children?: unknown;
+}
+
+interface BoundaryState {
+  // Raw thrown value passed to the error component. A client `throw undefined`/
+  // `null`/a string reaches error.js unwrapped (Next passes the raw value on the
+  // client channel), so `hasError` — NOT truthiness of `error` — gates rendering:
+  // a falsy `undefined`/`null` throw is still a caught error, not "no error".
+  error: unknown;
+  hasError: boolean;
+  notFound: boolean;
+}
+
+/**
+ * Normalize a client throw into the Error the boundary component receives.
+ * Client-side non-Error throws pass through unwrapped (String(value)); no digest
+ * is ever attached (digests are a server-error-only signal).
+ */
+export function toClientError(value: unknown): Error {
+  if (value instanceof Error) return value;
+  // `throw undefined` / `throw null` / `throw 'msg'` → message is String(value).
+  return new Error(String(value));
+}
+
+function normalizeBoundaryError(error: unknown): unknown {
+  // Preact-core interop tag (see primitive-throw.ts): a `throw undefined`/`null`
+  // arrives here re-thrown as a tagged Error so it survived preact's own
+  // `e.then` suspense check without crashing. Unwrap back to the raw value.
+  const untagged = untagPrimitiveThrow(error);
+  if (untagged !== error) return untagged;
+  if (error instanceof Error) {
+    // Fallback for any crash that slips through un-tagged (defense in depth).
+    if (error.message === "Cannot read properties of undefined (reading 'then')") return undefined;
+    if (error.message === "Cannot read properties of null (reading 'then')") return null;
+  }
+  return error;
+}
+
+// A boundary that catches (or escalates) a real error marks it here so the
+// window-listener last resort (install.ts) knows the error was already handled
+// by the nearest-boundary path and must NOT also drive it to global-error.
+// WeakSet-keyed (only object throws are markable; a primitive throw that reaches
+// the window is treated as unhandled, matching "the boundary couldn't hold it").
+const handledErrors = new WeakSet<object>();
+
+export function markErrorHandled(error: unknown): void {
+  if (error !== null && typeof error === 'object') handledErrors.add(error);
+}
+
+export function wasErrorHandled(error: unknown): boolean {
+  return error !== null && typeof error === 'object' && handledErrors.has(error);
+}
+
+export class ClientErrorBoundary extends Component<BoundaryProps, BoundaryState> {
+  state: BoundaryState = { error: null, hasError: false, notFound: false };
+
+  static getDerivedStateFromError(error: unknown): Partial<BoundaryState> {
+    if (isNotFoundError(error)) return { notFound: true, hasError: false, error: null };
+    // Control-flow errors must not be captured as state — let componentDidCatch
+    // re-throw so they propagate past this boundary.
+    if (isControlFlowError(error)) return {};
+    // Pass the RAW thrown value to error.js (no Error wrapping): a client
+    // `throw undefined`/`null`/'msg' renders as `${error}` = 'undefined'/'null'/'msg'.
+    return { error: normalizeBoundaryError(error), hasError: true };
+  }
+
+  componentDidCatch(error: unknown): void {
+    if (isNotFoundError(error)) {
+      markErrorHandled(error);
+      return;
+    }
+    if (isControlFlowError(error)) {
+      // Re-throw past this boundary: React/Next semantics for control errors.
+      // The install layer's window handler catches the propagated error and
+      // performs the navigation; we still throw so no error UI renders here.
+      handleControlFlowError(error);
+      throw error;
+    }
+    // A real error the boundary can render (it has a local error.js): mark it so the window-listener
+    // last resort ignores it. When there is NO errorComponent this boundary re-throws in render()
+    // instead of rendering anything - leave the error UNMARKED so an outer VDOM boundary can still
+    // catch it, and so the window-listener last resort recognizes a truly-uncaught error and mounts
+    // global-error.
+    if (this.props.errorComponent) markErrorHandled(error);
+  }
+
+  /**
+   * `reset()` re-renders the boundary's children in place - no server round trip. That is the whole
+   * difference from `unstable_retry()`, and it matters beyond the request count: a refresh swaps the
+   * body, so every node the reset subtree just rendered is replaced a moment later, and anything
+   * holding one of those nodes (a click in flight, a test's element handle) loses it.
+   */
+  reset = (): void => {
+    this.setState({ error: null, hasError: false, notFound: false });
+  };
+
+  /**
+   * Re-run the SERVER render, then re-render: recovers data-dependent failures. A CLIENT-component
+   * error carries no digest (digests are a server-only signal) - its failure lives in the hydrated
+   * tree, so re-rendering in place recovers it and a soft-refresh would only swap the body, detaching
+   * the very nodes a retry-then-interact loop reaches next. Only a server error's stale data needs the
+   * round trip.
+   */
+  unstable_retry = (): void => {
+    const digest = (this.state.error as { digest?: unknown } | null)?.digest;
+    this.setState({ error: null, hasError: false, notFound: false });
+    if (typeof digest === 'string' && digest.length > 0) this.props.onReset?.();
+  };
+
+  // A client-side notFound() that renders a LOCAL not-found.js has no server
+  // round trip, so the `<meta name="robots" content="noindex">` the server
+  // would emit for a not-found render is missing. Mirror it on the client:
+  // inject the tag while the local boundary is showing, remove it on recovery.
+  private addedNoindex = false;
+
+  private syncNotFoundRobots(): void {
+    if (typeof document === 'undefined') return;
+    const shouldShow = this.state.notFound && Boolean(this.props.notFoundComponent);
+    if (shouldShow && !this.addedNoindex) {
+      // Don't stomp an existing robots tag (SSR/metadata already set one).
+      if (!document.querySelector('meta[name="robots"]')) {
+        const meta = document.createElement('meta');
+        meta.setAttribute('name', 'robots');
+        meta.setAttribute('content', 'noindex');
+        meta.setAttribute('data-pnext-notfound-robots', '');
+        document.head.appendChild(meta);
+        this.addedNoindex = true;
+      }
+    } else if (!shouldShow && this.addedNoindex) {
+      document.querySelector('meta[name="robots"][data-pnext-notfound-robots]')?.remove();
+      this.addedNoindex = false;
+    }
+  }
+
+  componentDidMount(): void {
+    this.syncNotFoundRobots();
+  }
+
+  componentDidUpdate(): void {
+    this.syncNotFoundRobots();
+  }
+
+  componentWillUnmount(): void {
+    if (this.addedNoindex) {
+      document.querySelector('meta[name="robots"][data-pnext-notfound-robots]')?.remove();
+      this.addedNoindex = false;
+    }
+  }
+
+  render(): ComponentChildren {
+    if (this.state.notFound) {
+      const NotFoundComponent = this.props.notFoundComponent ?? this.props.builtInNotFound;
+      return NotFoundComponent ? h(NotFoundComponent, {}) : null;
+    }
+    if (!this.state.hasError) return this.props.children;
+    const { error } = this.state;
+    const ErrorComponent = this.props.errorComponent;
+    if (!ErrorComponent) {
+      // Preserve primitive throws for global-error.js directly (window `error`
+      // loses raw null/undefined/string). Bubble Error objects to the next outer
+      // ClientErrorBoundary so nearest in-tree boundary semantics stay intact.
+      if (error === null || typeof error !== 'object') {
+        // global-error rides the deferred tier (see ./lazy) — a primitive throw
+        // with no error.js is the one path that reaches it from a render.
+        void import('./global-error').then(m => m.escalateToGlobalError(error));
+        return null;
+      }
+      throw error as Error;
+    }
+    return h(ErrorComponent, { error, reset: this.reset, unstable_retry: this.unstable_retry });
+  }
+}