From 2a9a1026dca876b1bca8cb42349fa06eed3e6ea3 Mon Sep 17 00:00:00 2001
From: Nathan Nguyen <146415969+NathanDrake2406@users.noreply.github.com>
Date: Fri, 12 Jun 2026 17:06:00 +1000
Subject: [PATCH 01/11] fix(plugin): resolve vinext/shims/* package subpaths to
 local shim files

Runtime helper modules embedded into generated entries import vinext's
own shims by package subpath (e.g. `vinext/shims/headers`), while source
checkouts alias userland `next/*` imports to the local shim files. The
two specifiers resolved to different module instances, so request-scoped
singleton state (navigation context, headers) split between the source
shim copy and the package export copy.

The violated invariant is that every shim module must be a per-request
singleton regardless of import specifier. Resolve `vinext/shims/*`
through the same plugin path as the `next/*` aliases so both forms land
on the local shim files.

Exercised by the SSR shell-error recovery browser spec, whose fixture
imports vinext from the source checkout and depends on shared
navigation state across both import forms.
---
 packages/vinext/src/index.ts | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/packages/vinext/src/index.ts b/packages/vinext/src/index.ts
index 6e97af368..abc0e6722 100644
--- a/packages/vinext/src/index.ts
+++ b/packages/vinext/src/index.ts
@@ -2578,6 +2578,17 @@ export default function vinext(options: VinextOptions = {}): PluginOption[] {
             );
           }
 
+          // Runtime helper modules embedded into generated entries import
+          // vinext's own shims by package subpath (for example
+          // `vinext/shims/headers`). Source checkouts also alias userland
+          // `next/*` imports to the local shim files. Resolve both forms
+          // through this plugin so request-scoped singleton state is not split
+          // between source shims and the package export copy.
+          const vinextShimPrefix = "vinext/shims/";
+          if (cleanId.startsWith(vinextShimPrefix)) {
+            return resolveShimModulePath(_shimsDir, cleanId.slice(vinextShimPrefix.length));
+          }
+
           // Shims with react-server variants — resolve per-environment.
           // These are NOT in resolve.alias (Vite's alias plugin runs
           // before enforce:"pre" plugins and can't be overridden).

From 99789d7ff7226ea474df09ddc671c0141466f9d1 Mon Sep 17 00:00:00 2001
From: Nathan Nguyen <146415969+NathanDrake2406@users.noreply.github.com>
Date: Fri, 12 Jun 2026 17:06:23 +1000
Subject: [PATCH 02/11] fix(app-router): recover SSR shell render errors via
 __next_error__ document
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When the HTML (Fizz) render rejects during SSR, vinext re-rendered a
server-side global-error page whose flight payload encodes the error
tree. For an app without a custom global-error.tsx that meant the
default error card with no path back to the real page: an SSR-phase-only
throw (e.g. a client component using the "throw to opt out of server
rendering" pattern) left the browser stuck on the card even though the
client render would succeed.

The violated expectation is Next.js's shell-error semantics: a failed
HTML shell is served as the default `__next_error__` error document
carrying the ORIGINAL flight payload and the bootstrap module, and the
browser re-renders the real tree from that payload with createRoot
instead of hydrating. Local error.tsx boundaries still win — they ship
inside the flight payload and catch the re-thrown error client-side.

handleSsr now resolves to that recovery document instead of rejecting,
but only when both hold:
- the error did not originate in the RSC render (no string `digest`),
  so flight errors, redirect()/notFound(), and server-component throws
  keep driving the existing rejection-based boundary machinery, and
- the app has no custom global-error.tsx (the generated entry knows at
  build time and threads hasCustomGlobalError through dispatch/render
  options); apps with one keep the server-rendered boundary re-render.

The browser entry switches from hydrateRoot to createRoot when the
document root carries id="__next_error__", dropping the error-shell
styles first.

Covered by the new ssr-error-shell-recovery browser spec (recovery to
real content, local error.tsx for SSR-only and unconditional client
throws) and the existing tests/nextjs-compat/global-error.test.ts
boundary-semantics suite.
---
 packages/vinext/src/entries/app-rsc-entry.ts  |   1 +
 .../vinext/src/server/app-browser-entry.ts    |  32 +-
 .../vinext/src/server/app-page-dispatch.ts    |   6 +
 packages/vinext/src/server/app-page-render.ts |   5 +
 packages/vinext/src/server/app-page-stream.ts |  11 +
 packages/vinext/src/server/app-ssr-entry.ts   |  87 +++++-
 .../ssr-error-shell-recovery.browser.spec.ts  | 287 ++++++++++++++++++
 7 files changed, 415 insertions(+), 14 deletions(-)
 create mode 100644 tests/e2e/app-router/nextjs-compat/ssr-error-shell-recovery.browser.spec.ts

diff --git a/packages/vinext/src/entries/app-rsc-entry.ts b/packages/vinext/src/entries/app-rsc-entry.ts
index a73404b88..1a3488fc8 100644
--- a/packages/vinext/src/entries/app-rsc-entry.ts
+++ b/packages/vinext/src/entries/app-rsc-entry.ts
@@ -678,6 +678,7 @@ export default __createAppRscHandler({
       getSourceRoute(sourceRouteIndex) {
         return routes[sourceRouteIndex];
       },
+      hasCustomGlobalError: ${globalErrorVar ? `Boolean(${globalErrorVar}?.default)` : "false"},
       hasGenerateStaticParams: __generateStaticParams.length > 0,
       hasPageDefaultExport: !!PageComponent,
       hasPageModule: !!route.page,
diff --git a/packages/vinext/src/server/app-browser-entry.ts b/packages/vinext/src/server/app-browser-entry.ts
index 34f796554..25562ec6b 100644
--- a/packages/vinext/src/server/app-browser-entry.ts
+++ b/packages/vinext/src/server/app-browser-entry.ts
@@ -18,7 +18,7 @@ import {
   setServerCallback,
 } from "@vitejs/plugin-rsc/browser";
 import { flushSync } from "react-dom";
-import { hydrateRoot } from "react-dom/client";
+import { createRoot, hydrateRoot } from "react-dom/client";
 import "../client/instrumentation-client.js";
 import { notifyAppRouterTransitionStart } from "../client/instrumentation-client-state.js";
 import {
@@ -1603,16 +1603,28 @@ function bootstrapHydration(rscStream: ReadableStream<Uint8Array>): void {
         onCaughtError: prodOnCaughtError,
         onUncaughtError,
       });
-  window.__VINEXT_RSC_ROOT__ = hydrateRootInTransition({
-    children: createElement(BrowserRoot, {
-      initialElements: root,
-      initialNavigationSnapshot,
-    }),
-    container: document,
-    hydrateRoot,
-    options: hydrateRootOptions,
-    startTransition,
+  const children = createElement(BrowserRoot, {
+    initialElements: root,
+    initialNavigationSnapshot,
   });
+  if (document.documentElement.id === "__next_error__") {
+    for (const style of document.querySelectorAll("style[data-vinext-error-shell-style]")) {
+      style.remove();
+    }
+    startTransition(() => {
+      const clientRoot = createRoot(document, hydrateRootOptions);
+      clientRoot.render(children);
+      window.__VINEXT_RSC_ROOT__ = clientRoot;
+    });
+  } else {
+    window.__VINEXT_RSC_ROOT__ = hydrateRootInTransition({
+      children,
+      container: document,
+      hydrateRoot,
+      options: hydrateRootOptions,
+      startTransition,
+    });
+  }
 
   const navigateRsc: NavigationRuntimeNavigate = async function navigateRsc(
     href: string,
diff --git a/packages/vinext/src/server/app-page-dispatch.ts b/packages/vinext/src/server/app-page-dispatch.ts
index 2c6c9474a..2c3325e22 100644
--- a/packages/vinext/src/server/app-page-dispatch.ts
+++ b/packages/vinext/src/server/app-page-dispatch.ts
@@ -267,6 +267,11 @@ type DispatchAppPageOptions<TRoute extends AppPageDispatchRoute> = {
   probeLayoutAt: (layoutIndex: number, layoutParamAccess?: AppLayoutParamAccessTracker) => unknown;
   probePage: () => unknown;
   expireSeconds?: number;
+  /** True when the app supplies a custom global-error.tsx (generated entry
+   *  knows this at build time). Gates SSR shell-error recovery: without a
+   *  custom global-error, shell errors serve the default `__next_error__`
+   *  recovery document instead of a server-side boundary re-render. */
+  hasCustomGlobalError?: boolean;
   renderErrorBoundaryPage: (error: unknown) => Promise<Response | null>;
   renderHttpAccessFallbackPage: (
     statusCode: number,
@@ -979,6 +984,7 @@ async function dispatchAppPageInner<TRoute extends AppPageDispatchRoute>(
       return renderPageSpecialError(options, specialError);
     },
     renderToReadableStream: options.renderToReadableStream,
+    hasCustomGlobalError: options.hasCustomGlobalError,
     routePattern: route.pattern,
     runWithSuppressedHookWarning(probe) {
       return options.runWithSuppressedHookWarning(probe);
diff --git a/packages/vinext/src/server/app-page-render.ts b/packages/vinext/src/server/app-page-render.ts
index 27239e408..9e5b8b51b 100644
--- a/packages/vinext/src/server/app-page-render.ts
+++ b/packages/vinext/src/server/app-page-render.ts
@@ -170,6 +170,10 @@ type RenderAppPageLifecycleOptions = {
     element: ReactNode | AppOutgoingElements,
     options: { onError: AppPageBoundaryOnError },
   ) => ReadableStream<Uint8Array>;
+  /** True when the app supplies a custom global-error.tsx. When false, SSR
+   *  shell render errors fall back to the default `__next_error__` recovery
+   *  document instead of a server-side boundary re-render. */
+  hasCustomGlobalError?: boolean;
   routePattern: string;
   runWithSuppressedHookWarning<T>(probe: () => Promise<T>): Promise<T>;
   scriptNonce?: string;
@@ -836,6 +840,7 @@ export async function renderAppPageLifecycle(
         rscStream: rscForResponse,
         scriptNonce: options.scriptNonce,
         sideStream: rscCapture.sideStream,
+        hasCustomGlobalError: options.hasCustomGlobalError,
         ssrHandler,
         waitForAllReady: options.isPrerender,
       });
diff --git a/packages/vinext/src/server/app-page-stream.ts b/packages/vinext/src/server/app-page-stream.ts
index a0b46eaae..2d8500474 100644
--- a/packages/vinext/src/server/app-page-stream.ts
+++ b/packages/vinext/src/server/app-page-stream.ts
@@ -132,6 +132,10 @@ export type AppPageSsrHandler = {
       waitForAllReady?: boolean;
       /** Dev-only: original server error to surface in the browser overlay. */
       initialDevServerError?: unknown;
+      /** When true, an SSR-phase-only shell render error resolves to the
+       *  default `__next_error__` error-document shell (with the original
+       *  flight payload and bootstrap) instead of rejecting. See handleSsr. */
+      fallbackToErrorDocumentOnShellError?: boolean;
     },
   ) => Promise<ReadableStream<Uint8Array> | AppSsrRenderResult>;
 };
@@ -166,6 +170,10 @@ type RenderAppPageHtmlStreamOptions = {
   waitForAllReady?: boolean;
   /** Dev-only: original server error to surface in the browser overlay. */
   initialDevServerError?: unknown;
+  /** True when the app supplies a custom global-error.tsx. Disables the
+   *  default error-document shell fallback so SSR shell errors keep driving
+   *  the server-rendered global-error boundary re-render. */
+  hasCustomGlobalError?: boolean;
 };
 
 type RenderAppPageHtmlResponseOptions = {
@@ -227,6 +235,9 @@ export async function renderAppPageHtmlStream(
     capturedRscDataRef: options.capturedRscDataRef,
     waitForAllReady: options.waitForAllReady,
     initialDevServerError: options.initialDevServerError,
+    // Only when the caller affirmatively knows there is no custom
+    // global-error.tsx; undefined (unknown) keeps reject semantics.
+    fallbackToErrorDocumentOnShellError: options.hasCustomGlobalError === false,
   };
 
   const rawResult = await options.ssrHandler.handleSsr(
diff --git a/packages/vinext/src/server/app-ssr-entry.ts b/packages/vinext/src/server/app-ssr-entry.ts
index 5a7b7f874..af57cd44a 100644
--- a/packages/vinext/src/server/app-ssr-entry.ts
+++ b/packages/vinext/src/server/app-ssr-entry.ts
@@ -48,6 +48,7 @@ import { BfcacheStateKeyMapContext, ElementsContext, Slot } from "vinext/shims/s
 import { AppRouterContext } from "vinext/shims/internal/app-router-context";
 import { createClientReferencePreloader } from "./app-client-reference-preloader.js";
 import { RSC_FORM_STATE_GLOBAL } from "./app-browser-hydration.js";
+import DefaultGlobalError from "vinext/shims/default-global-error";
 
 /**
  * `@types/react-dom` does not yet type `maxHeadersLength` (it pairs with the
@@ -106,6 +107,55 @@ function getErrorMessage(error: unknown): string {
   return Object.prototype.toString.call(error);
 }
 
+function createUtf8Stream(html: string): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder();
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(encoder.encode(html));
+      controller.close();
+    },
+  });
+}
+
+function buildBootstrapModuleScript(bootstrapModuleUrl?: string, nonce?: string): string {
+  if (!bootstrapModuleUrl) return "";
+  return (
+    `<script type="module"${createNonceAttribute(nonce)} src="` +
+    escapeHtmlAttr(bootstrapModuleUrl) +
+    '" id="_R_" async=""></script>'
+  );
+}
+
+function markErrorShellStyle(html: string): string {
+  return html.replace("<style>", '<style data-vinext-error-shell-style="">');
+}
+
+function renderSsrErrorDocumentShell(
+  bootstrapModuleUrl?: string,
+  nonce?: string,
+): ReadableStream<Uint8Array> {
+  const html = markErrorShellStyle(
+    renderToStaticMarkup(
+      createReactElement(DefaultGlobalError, {
+        error: null,
+      }),
+    ),
+  );
+  const bootstrapScript = buildBootstrapModuleScript(bootstrapModuleUrl, nonce);
+  if (!bootstrapScript) {
+    return createUtf8Stream(`<!DOCTYPE html>${html}`);
+  }
+
+  const documentClose = "</body></html>";
+  if (!html.endsWith(documentClose)) {
+    return createUtf8Stream(`<!DOCTYPE html>${html}${bootstrapScript}`);
+  }
+
+  return createUtf8Stream(
+    `<!DOCTYPE html>${html.slice(0, -documentClose.length)}${bootstrapScript}${documentClose}`,
+  );
+}
+
 function renderInsertedHtml(insertedElements: readonly unknown[]): string {
   let insertedHTML = "";
 
@@ -306,6 +356,12 @@ export async function handleSsr(
      *  to resolve before returning the HTML stream. Used for static prerender
      *  and ISR cache writes to avoid caching fallback content. */
     waitForAllReady?: boolean;
+    /** When true, an SSR-phase shell render error (no RSC-originated `digest`)
+     *  resolves to the default `__next_error__` error-document shell with the
+     *  original flight payload and bootstrap module, instead of rejecting.
+     *  Callers set this only when the app has no custom global-error.tsx, so
+     *  boundary re-render semantics are unaffected. */
+    fallbackToErrorDocumentOnShellError?: boolean;
   },
 ): Promise<AppSsrRenderResult> {
   return runWithNavigationContext(async () => {
@@ -501,8 +557,6 @@ export async function handleSsr(
           },
         };
 
-        const htmlStream = await renderToReadableStream(ssrRoot, ssrRenderOptions);
-
         // Populated before any SSR request runs: at prod-server startup
         // (prod-server.ts) or via build-time bundle injection (index.ts). Left
         // undefined in dev, which naturally disables inline CSS there.
@@ -560,8 +614,33 @@ export async function handleSsr(
         const getBeforeInteractiveHeadHTML = (): string =>
           renderBeforeInteractiveInlineScripts(beforeInteractiveInlineScripts);
 
-        if (options?.waitForAllReady === true) {
-          await htmlStream.allReady;
+        let htmlStream: ReadableStream<Uint8Array>;
+        try {
+          const renderedHtmlStream = await renderToReadableStream(ssrRoot, ssrRenderOptions);
+          if (options?.waitForAllReady === true) {
+            await renderedHtmlStream.allReady;
+          }
+          htmlStream = renderedHtmlStream;
+        } catch (error) {
+          // Contract with renderAppPageHtmlStreamWithRecovery (app-page-stream.ts):
+          // a rejected handleSsr drives redirect()/notFound() responses and
+          // local/global error.tsx boundary re-renders. Errors that originate in
+          // the RSC render (rethrown here through the flight deserializer) carry
+          // a string `digest` and must always propagate so those semantics stay
+          // intact. Only an SSR-phase-only shell error — and only when the app
+          // has no custom global-error.tsx (the caller sets the flag) — falls
+          // back to the default `__next_error__` document shell: the original
+          // flight payload plus the bootstrap module are still emitted, so the
+          // browser recovers by re-rendering the real tree from the embedded
+          // RSC data (Next.js shell-error recovery semantics).
+          if (
+            options?.fallbackToErrorDocumentOnShellError !== true ||
+            typeof (error as { digest?: unknown } | null)?.digest === "string"
+          ) {
+            throw error;
+          }
+          errorMetaRenderer.capture(error);
+          htmlStream = renderSsrErrorDocumentShell(bootstrapModuleUrl, options?.scriptNonce);
         }
 
         const finalStream = deferUntilStreamConsumed(
diff --git a/tests/e2e/app-router/nextjs-compat/ssr-error-shell-recovery.browser.spec.ts b/tests/e2e/app-router/nextjs-compat/ssr-error-shell-recovery.browser.spec.ts
new file mode 100644
index 000000000..d8703640b
--- /dev/null
+++ b/tests/e2e/app-router/nextjs-compat/ssr-error-shell-recovery.browser.spec.ts
@@ -0,0 +1,287 @@
+/**
+ * SSR shell-error recovery in production builds.
+ *
+ * When the HTML (Fizz) render of an SSR pass rejects with an error that did
+ * not originate in the RSC render (no `digest`), and the app has no custom
+ * global-error.tsx, vinext serves the default `__next_error__` error-document
+ * shell with the original flight payload and bootstrap module. The browser
+ * detects the marker and re-renders the real tree with `createRoot` instead
+ * of hydrating — Next.js's shell-error recovery semantics:
+ * https://github.com/vercel/next.js/blob/v16.2.6/packages/next/src/server/app-render/app-render.tsx
+ *
+ * The throw-during-SSR-only pattern ("Expected error to opt out of server
+ * rendering") comes from the Next.js `next-dynamic-css` fixture:
+ * https://github.com/vercel/next.js/blob/v16.2.6/test/e2e/app-dir/next-dynamic-css/next-dynamic-css.test.ts
+ *
+ * This fixture intentionally has NO custom global-error.tsx — that is the
+ * configuration in which handleSsr's error-document fallback is active
+ * (`fallbackToErrorDocumentOnShellError`). Apps with a custom global-error
+ * keep the server-rendered boundary re-render path, covered by
+ * tests/nextjs-compat/global-error.test.ts.
+ */
+import fs from "node:fs/promises";
+import type { Server } from "node:http";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { expect, test } from "../../fixtures";
+
+type ProductionApp = {
+  baseUrl: string;
+  fixtureRoot: string;
+  server: Server;
+};
+
+async function closeServer(server: Server): Promise<void> {
+  const closed = new Promise<void>((resolve) => server.close(() => resolve()));
+  server.closeIdleConnections();
+  server.closeAllConnections();
+  await closed;
+}
+
+async function linkFixtureNodeModules(fixtureRoot: string): Promise<void> {
+  const sourceNodeModules = path.resolve(process.cwd(), "tests/fixtures/app-basic/node_modules");
+  const targetNodeModules = path.join(fixtureRoot, "node_modules");
+
+  await fs.mkdir(targetNodeModules, { recursive: true });
+
+  for (const entry of await fs.readdir(sourceNodeModules, { withFileTypes: true })) {
+    if (entry.name === ".vite-temp") continue;
+
+    await fs.symlink(
+      path.join(sourceNodeModules, entry.name),
+      path.join(targetNodeModules, entry.name),
+      entry.isDirectory() ? "junction" : "file",
+    );
+  }
+}
+
+async function writeRecoveryFixture(fixtureRoot: string): Promise<void> {
+  const appDir = path.join(fixtureRoot, "app");
+  await fs.mkdir(appDir, { recursive: true });
+  await fs.mkdir(path.join(fixtureRoot, "public"), { recursive: true });
+  await linkFixtureNodeModules(fixtureRoot);
+
+  // Minimal valid .ico so browser favicon requests do not 404 (the console
+  // error fixture is strict).
+  await fs.writeFile(
+    path.join(fixtureRoot, "public/favicon.ico"),
+    new Uint8Array([
+      0, 0, 1, 0, 1, 0, 1, 1, 0, 0, 1, 0, 32, 0, 48, 0, 0, 0, 22, 0, 0, 0, 40, 0, 0, 0, 1, 0, 0, 0,
+      2, 0, 0, 0, 1, 0, 32, 0, 0, 0, 0, 0, 4, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+      0, 255, 255, 255, 0,
+    ]),
+  );
+
+  await fs.writeFile(
+    path.join(fixtureRoot, "package.json"),
+    `${JSON.stringify({ type: "module", dependencies: {} }, null, 2)}\n`,
+  );
+  await fs.writeFile(
+    path.join(appDir, "layout.tsx"),
+    `import { ReactNode } from "react";
+
+export default function Root({ children }: { children: ReactNode }) {
+  return (
+    <html>
+      <body>{children}</body>
+    </html>
+  );
+}
+`,
+  );
+
+  // No local boundary: an SSR-only client throw rejects the HTML shell and the
+  // default __next_error__ document recovery re-renders the real tree in the
+  // browser. `cookies()` keeps the page dynamic so the runtime SSR pass (not a
+  // prerendered document) serves the request.
+  const pageDir = path.join(appDir, "page");
+  await fs.mkdir(pageDir, { recursive: true });
+  await fs.writeFile(
+    path.join(pageDir, "page.tsx"),
+    `import React from "react";
+import { cookies } from "next/headers";
+import Client from "./Client";
+
+export default async function Page() {
+  await cookies();
+  return (
+    <>
+      <p id="server-content">Hello Server</p>
+      <Client />
+    </>
+  );
+}
+`,
+  );
+  await fs.writeFile(
+    path.join(pageDir, "Client.tsx"),
+    `"use client";
+import React from "react";
+
+export default function Client() {
+  if (typeof window === "undefined") {
+    throw new Error("Expected error to opt out of server rendering");
+  }
+  return <p id="client-content">Hello Client</p>;
+}
+`,
+  );
+
+  // Local error.tsx routes: the shell fallback must not swallow local
+  // boundary semantics. Local boundaries for shell errors materialize
+  // client-side from the flight payload (Next.js parity):
+  // - /boundary-ssr-only: throw recurs only on the server, so the browser
+  //   re-render succeeds and the content (not the boundary) appears.
+  // - /boundary-always: the browser re-render throws again and React catches
+  //   it in the local error.tsx delivered in the flight payload.
+  const boundarySsrOnlyDir = path.join(appDir, "boundary-ssr-only");
+  const boundaryAlwaysDir = path.join(appDir, "boundary-always");
+  await fs.mkdir(boundarySsrOnlyDir, { recursive: true });
+  await fs.mkdir(boundaryAlwaysDir, { recursive: true });
+
+  const localErrorBoundary = `"use client";
+import React from "react";
+export default function LocalError() {
+  return <p id="local-error-boundary">Local boundary caught it</p>;
+}
+`;
+
+  await fs.writeFile(
+    path.join(boundarySsrOnlyDir, "page.tsx"),
+    `import React from "react";
+import Client from "./Client";
+export default function BoundarySsrOnlyPage() {
+  return <Client />;
+}
+`,
+  );
+  await fs.writeFile(
+    path.join(boundarySsrOnlyDir, "Client.tsx"),
+    `"use client";
+import React from "react";
+export default function Client() {
+  if (typeof window === "undefined") {
+    throw new Error("ssr-only boundary throw");
+  }
+  return <p id="boundary-ssr-only-content">Recovered client render</p>;
+}
+`,
+  );
+  await fs.writeFile(path.join(boundarySsrOnlyDir, "error.tsx"), localErrorBoundary);
+
+  await fs.writeFile(
+    path.join(boundaryAlwaysDir, "page.tsx"),
+    `import React from "react";
+import Client from "./Client";
+export default function BoundaryAlwaysPage() {
+  return <Client />;
+}
+`,
+  );
+  await fs.writeFile(
+    path.join(boundaryAlwaysDir, "Client.tsx"),
+    `"use client";
+import React from "react";
+export default function Client(): React.ReactNode {
+  throw new Error("always boundary throw");
+}
+`,
+  );
+  await fs.writeFile(path.join(boundaryAlwaysDir, "error.tsx"), localErrorBoundary);
+
+  const vinextSource = path.resolve(process.cwd(), "packages/vinext/src/index.ts");
+  await fs.writeFile(
+    path.join(fixtureRoot, "vite.config.ts"),
+    `import { defineConfig } from "vite";
+import vinext from ${JSON.stringify(pathToFileURL(vinextSource).href)};
+
+export default defineConfig({
+  plugins: [vinext({ appDir: import.meta.dirname })],
+});
+`,
+  );
+}
+
+async function buildPrerenderAndServeRecoveryFixture(): Promise<ProductionApp> {
+  const fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), "vinext-ssr-error-recovery-"));
+  await writeRecoveryFixture(fixtureRoot);
+
+  const { createBuilder } = await import("vite");
+  const builder = await createBuilder({
+    root: fixtureRoot,
+    configFile: path.join(fixtureRoot, "vite.config.ts"),
+    logLevel: "silent",
+  });
+  await builder.buildApp();
+
+  const { runPrerender } = await import(
+    pathToFileURL(path.resolve(process.cwd(), "packages/vinext/dist/build/run-prerender.js")).href
+  );
+  await runPrerender({ root: fixtureRoot });
+
+  const { startProdServer } = await import(
+    pathToFileURL(path.resolve(process.cwd(), "packages/vinext/dist/server/prod-server.js")).href
+  );
+  const started = await startProdServer({
+    host: "127.0.0.1",
+    port: 0,
+    outDir: path.join(fixtureRoot, "dist"),
+    noCompression: true,
+  });
+
+  return {
+    baseUrl: `http://127.0.0.1:${started.port}`,
+    fixtureRoot,
+    server: started.server,
+  };
+}
+
+test.setTimeout(90_000);
+
+test.describe("SSR shell-error recovery (no custom global-error.tsx)", () => {
+  test("recovers the real tree in the browser and preserves local error.tsx semantics", async ({
+    page,
+    consoleErrors,
+  }) => {
+    const app = await buildPrerenderAndServeRecoveryFixture();
+
+    try {
+      // SSR-only client throw without a boundary: the default __next_error__
+      // shell is served and the browser re-renders the real tree from the
+      // embedded flight payload.
+      await page.goto(`${app.baseUrl}/page`, { waitUntil: "load" });
+      await expect(page.locator("#server-content")).toHaveText("Hello Server");
+      await expect(page.locator("#client-content")).toHaveText("Hello Client");
+
+      // SSR-only throw with a local error.tsx: browser re-render succeeds, so
+      // the content (not the boundary) appears.
+      await page.goto(`${app.baseUrl}/boundary-ssr-only`, { waitUntil: "load" });
+      await expect(page.locator("#boundary-ssr-only-content")).toHaveText(
+        "Recovered client render",
+      );
+      await expect(page.locator("#local-error-boundary")).toHaveCount(0);
+
+      // Unconditional client throw: the browser re-render throws again and the
+      // local error.tsx from the flight payload catches it.
+      await page.goto(`${app.baseUrl}/boundary-always`, { waitUntil: "load" });
+      await expect(page.locator("#local-error-boundary")).toHaveText("Local boundary caught it");
+
+      // The boundary routes throw on purpose, and React logs caught boundary
+      // errors to the console. Drop those expected entries but stay strict
+      // about anything else; the fixture re-asserts emptiness at teardown.
+      const unexpectedErrors = consoleErrors.filter(
+        (message) =>
+          !message.includes("boundary throw") &&
+          !message.includes("Expected error to opt out of server rendering") &&
+          // React's companion log for an error caught by a boundary.
+          !message.startsWith("The above error occurred in a React component"),
+      );
+      expect(unexpectedErrors).toEqual([]);
+      consoleErrors.length = 0;
+    } finally {
+      await closeServer(app.server);
+      await fs.rm(app.fixtureRoot, { recursive: true, force: true });
+    }
+  });
+});

From dab9c72725265f679a0b87670a040f8e659856f3 Mon Sep 17 00:00:00 2001
From: Nathan Nguyen <146415969+NathanDrake2406@users.noreply.github.com>
Date: Fri, 12 Jun 2026 17:32:20 +1000
Subject: [PATCH 03/11] refactor(review): address PR 1908 non-blocking notes

- Add static prerender no-boundary recovery regression test to
  ssr-error-shell-recovery.browser.spec.ts
- Document broad __next_error__ browser marker in app-browser-entry.ts
- Extract stripJsExtension to utils/path.ts and wire into all shim
  resolution sites (vinext/shims/* + react-server shims)

Non-functional: targeted regression coverage + code documentation
+ minor resolver hardening per reviewer feedback.
---
 packages/vinext/src/index.ts                  | 11 +++--
 .../vinext/src/server/app-browser-entry.ts    | 11 +++++
 packages/vinext/src/utils/path.ts             |  9 ++++
 .../ssr-error-shell-recovery.browser.spec.ts  | 42 +++++++++++++++++++
 4 files changed, 69 insertions(+), 4 deletions(-)

diff --git a/packages/vinext/src/index.ts b/packages/vinext/src/index.ts
index abc0e6722..eb511dbe7 100644
--- a/packages/vinext/src/index.ts
+++ b/packages/vinext/src/index.ts
@@ -185,7 +185,7 @@ import { createRequire } from "node:module";
 import fs from "node:fs";
 import { randomBytes, randomUUID } from "node:crypto";
 import commonjs from "vite-plugin-commonjs";
-import { normalizePathSeparators, stripViteModuleQuery } from "./utils/path.js";
+import { normalizePathSeparators, stripJsExtension, stripViteModuleQuery } from "./utils/path.js";
 
 // Install the process-level peer-disconnect backstop at module load.
 // Vite plugin lifecycle hooks (config / configureServer) proved
@@ -2111,7 +2111,7 @@ export default function vinext(options: VinextOptions = {}): PluginOption[] {
           resolveId(id: string) {
             const shimBase = _reactServerShims.get(id);
             if (shimBase !== undefined) {
-              return resolveShimModulePath(shimsDir, shimBase);
+              return resolveShimModulePath(shimsDir, stripJsExtension(shimBase));
             }
           },
         };
@@ -2586,7 +2586,10 @@ export default function vinext(options: VinextOptions = {}): PluginOption[] {
           // between source shims and the package export copy.
           const vinextShimPrefix = "vinext/shims/";
           if (cleanId.startsWith(vinextShimPrefix)) {
-            return resolveShimModulePath(_shimsDir, cleanId.slice(vinextShimPrefix.length));
+            return resolveShimModulePath(
+              _shimsDir,
+              stripJsExtension(cleanId.slice(vinextShimPrefix.length)),
+            );
           }
 
           // Shims with react-server variants — resolve per-environment.
@@ -2599,7 +2602,7 @@ export default function vinext(options: VinextOptions = {}): PluginOption[] {
               this.environment?.name === "rsc"
                 ? `${reactServerShim}.react-server`
                 : reactServerShim;
-            return resolveShimModulePath(_shimsDir, shimName);
+            return resolveShimModulePath(_shimsDir, stripJsExtension(shimName));
           }
         },
       },
diff --git a/packages/vinext/src/server/app-browser-entry.ts b/packages/vinext/src/server/app-browser-entry.ts
index 25562ec6b..dd60c9ce0 100644
--- a/packages/vinext/src/server/app-browser-entry.ts
+++ b/packages/vinext/src/server/app-browser-entry.ts
@@ -1607,6 +1607,12 @@ function bootstrapHydration(rscStream: ReadableStream<Uint8Array>): void {
     initialElements: root,
     initialNavigationSnapshot,
   });
+  // The `__next_error__` marker is intentionally broad: it detects the default
+  // error document generally, not only the new SSR shell-error recovery path.
+  // Both `DefaultGlobalError` (used here) and the boundary renderer emit
+  // `<html id="__next_error__">`, so this branch also fires for legacy server-
+  // rendered global-error pages. That is upstream-compatible — the browser
+  // should always createRoot when the document is the default error shell.
   if (document.documentElement.id === "__next_error__") {
     for (const style of document.querySelectorAll("style[data-vinext-error-shell-style]")) {
       style.remove();
@@ -2202,6 +2208,11 @@ function bootstrapHydration(rscStream: ReadableStream<Uint8Array>): void {
       // original document from there, so let the next HMR update reload the
       // current URL. If the edit fixed the error the page comes back clean; if
       // not, initial dev server errors re-populate the overlay.
+      //
+      // The `__next_error__` marker is broad — see the matching comment in
+      // bootstrapHydration above. Reloading here is safe for any default-error
+      // document because the dev server will render the current state of the
+      // source after the edit.
       if (document.documentElement.id === "__next_error__") {
         window.location.reload();
         return;
diff --git a/packages/vinext/src/utils/path.ts b/packages/vinext/src/utils/path.ts
index 49327f3ff..29384b3af 100644
--- a/packages/vinext/src/utils/path.ts
+++ b/packages/vinext/src/utils/path.ts
@@ -19,3 +19,12 @@ export function stripViteModuleQuery(id: string): string {
   const queryIndex = id.search(/[?#]/);
   return queryIndex === -1 ? id : id.slice(0, queryIndex);
 }
+
+/** Strip a trailing `.js` extension from a module specifier so
+ *  `resolveShimModulePath` looks for the correct base name (e.g. `headers.js`
+ *  → `headers`). Public and internal shim imports may carry extensionful
+ *  subpaths; normalising before resolution prevents looking for non-existent
+ *  files like `headers.js.ts`. */
+export function stripJsExtension(name: string): string {
+  return name.endsWith(".js") ? name.slice(0, -3) : name;
+}
diff --git a/tests/e2e/app-router/nextjs-compat/ssr-error-shell-recovery.browser.spec.ts b/tests/e2e/app-router/nextjs-compat/ssr-error-shell-recovery.browser.spec.ts
index d8703640b..00cffba5e 100644
--- a/tests/e2e/app-router/nextjs-compat/ssr-error-shell-recovery.browser.spec.ts
+++ b/tests/e2e/app-router/nextjs-compat/ssr-error-shell-recovery.browser.spec.ts
@@ -128,6 +128,41 @@ export default function Client() {
 `,
   );
 
+  // Static prerender variant: no dynamic APIs, so the route is prerendered at
+  // build time. The SSR shell error is resolved to the error-document during
+  // prerender, and the cached HTML is served on the next request. The browser
+  // must still recover the real tree from the embedded flight payload.
+  const staticDir = path.join(appDir, "static-recovery");
+  await fs.mkdir(staticDir, { recursive: true });
+  await fs.writeFile(
+    path.join(staticDir, "page.tsx"),
+    `import React from "react";
+import Client from "./Client";
+
+export default function StaticPage() {
+  return (
+    <>
+      <p id="static-server-content">Hello Static Server</p>
+      <Client />
+    </>
+  );
+}
+`,
+  );
+  await fs.writeFile(
+    path.join(staticDir, "Client.tsx"),
+    `"use client";
+import React from "react";
+
+export default function Client() {
+  if (typeof window === "undefined") {
+    throw new Error("Expected error to opt out of server rendering");
+  }
+  return <p id="static-client-content">Hello Static Client</p>;
+}
+`,
+  );
+
   // Local error.tsx routes: the shell fallback must not swallow local
   // boundary semantics. Local boundaries for shell errors materialize
   // client-side from the flight payload (Next.js parity):
@@ -254,6 +289,13 @@ test.describe("SSR shell-error recovery (no custom global-error.tsx)", () => {
       await expect(page.locator("#server-content")).toHaveText("Hello Server");
       await expect(page.locator("#client-content")).toHaveText("Hello Client");
 
+      // Static prerender variant: the shell error was resolved to the error
+      // document during prerender, cached as HTML, and the browser must still
+      // recover the real tree from the embedded flight payload.
+      await page.goto(`${app.baseUrl}/static-recovery`, { waitUntil: "load" });
+      await expect(page.locator("#static-server-content")).toHaveText("Hello Static Server");
+      await expect(page.locator("#static-client-content")).toHaveText("Hello Static Client");
+
       // SSR-only throw with a local error.tsx: browser re-render succeeds, so
       // the content (not the boundary) appears.
       await page.goto(`${app.baseUrl}/boundary-ssr-only`, { waitUntil: "load" });

From 7f8b8ba88dd7b5104b6bfafb8a65d236c56f357e Mon Sep 17 00:00:00 2001
From: James <james@eli.cx>
Date: Fri, 12 Jun 2026 12:17:09 +0100
Subject: [PATCH 04/11] refactor(review): clarify shell recovery assumptions

---
 packages/vinext/src/index.ts                | 5 ++++-
 packages/vinext/src/server/app-ssr-entry.ts | 8 ++++++--
 2 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/packages/vinext/src/index.ts b/packages/vinext/src/index.ts
index eb511dbe7..990da0e1b 100644
--- a/packages/vinext/src/index.ts
+++ b/packages/vinext/src/index.ts
@@ -2583,7 +2583,10 @@ export default function vinext(options: VinextOptions = {}): PluginOption[] {
           // `vinext/shims/headers`). Source checkouts also alias userland
           // `next/*` imports to the local shim files. Resolve both forms
           // through this plugin so request-scoped singleton state is not split
-          // between source shims and the package export copy.
+          // between source shims and the package export copy. These internal
+          // package subpaths deliberately resolve to the plain shim today; if
+          // one gains an environment-specific variant, handle it here before
+          // returning rather than relying on the userland `next/*` map below.
           const vinextShimPrefix = "vinext/shims/";
           if (cleanId.startsWith(vinextShimPrefix)) {
             return resolveShimModulePath(
diff --git a/packages/vinext/src/server/app-ssr-entry.ts b/packages/vinext/src/server/app-ssr-entry.ts
index af57cd44a..7c86eface 100644
--- a/packages/vinext/src/server/app-ssr-entry.ts
+++ b/packages/vinext/src/server/app-ssr-entry.ts
@@ -127,6 +127,9 @@ function buildBootstrapModuleScript(bootstrapModuleUrl?: string, nonce?: string)
 }
 
 function markErrorShellStyle(html: string): string {
+  // DefaultGlobalError intentionally emits one style tag. If that changes,
+  // update this marker logic without touching styles inserted later by the
+  // stream transforms.
   return html.replace("<style>", '<style data-vinext-error-shell-style="">');
 }
 
@@ -632,14 +635,15 @@ export async function handleSsr(
           // back to the default `__next_error__` document shell: the original
           // flight payload plus the bootstrap module are still emitted, so the
           // browser recovers by re-rendering the real tree from the embedded
-          // RSC data (Next.js shell-error recovery semantics).
+          // RSC data (Next.js shell-error recovery semantics). This resolves
+          // as a successful shell render, so the caller preserves its normal
+          // status and ISR eligibility rather than treating it as a 500.
           if (
             options?.fallbackToErrorDocumentOnShellError !== true ||
             typeof (error as { digest?: unknown } | null)?.digest === "string"
           ) {
             throw error;
           }
-          errorMetaRenderer.capture(error);
           htmlStream = renderSsrErrorDocumentShell(bootstrapModuleUrl, options?.scriptNonce);
         }
 

From f8ff07cd0438d215e77b18b5e5d4648c82955e91 Mon Sep 17 00:00:00 2001
From: James <james@eli.cx>
Date: Fri, 12 Jun 2026 12:34:34 +0100
Subject: [PATCH 05/11] fix(ssr): cancel abandoned prerender streams

---
 packages/vinext/src/index.ts                | 2 +-
 packages/vinext/src/server/app-ssr-entry.ts | 4 +++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/vinext/src/index.ts b/packages/vinext/src/index.ts
index 990da0e1b..699847fcf 100644
--- a/packages/vinext/src/index.ts
+++ b/packages/vinext/src/index.ts
@@ -2111,7 +2111,7 @@ export default function vinext(options: VinextOptions = {}): PluginOption[] {
           resolveId(id: string) {
             const shimBase = _reactServerShims.get(id);
             if (shimBase !== undefined) {
-              return resolveShimModulePath(shimsDir, stripJsExtension(shimBase));
+              return resolveShimModulePath(shimsDir, shimBase);
             }
           },
         };
diff --git a/packages/vinext/src/server/app-ssr-entry.ts b/packages/vinext/src/server/app-ssr-entry.ts
index 7c86eface..c6f3a7118 100644
--- a/packages/vinext/src/server/app-ssr-entry.ts
+++ b/packages/vinext/src/server/app-ssr-entry.ts
@@ -617,14 +617,16 @@ export async function handleSsr(
         const getBeforeInteractiveHeadHTML = (): string =>
           renderBeforeInteractiveInlineScripts(beforeInteractiveInlineScripts);
 
+        let renderedHtmlStream: Awaited<ReturnType<typeof renderToReadableStream>> | undefined;
         let htmlStream: ReadableStream<Uint8Array>;
         try {
-          const renderedHtmlStream = await renderToReadableStream(ssrRoot, ssrRenderOptions);
+          renderedHtmlStream = await renderToReadableStream(ssrRoot, ssrRenderOptions);
           if (options?.waitForAllReady === true) {
             await renderedHtmlStream.allReady;
           }
           htmlStream = renderedHtmlStream;
         } catch (error) {
+          void renderedHtmlStream?.cancel().catch(() => {});
           // Contract with renderAppPageHtmlStreamWithRecovery (app-page-stream.ts):
           // a rejected handleSsr drives redirect()/notFound() responses and
           // local/global error.tsx boundary re-renders. Errors that originate in

From ad6daace8c9a173aecfa9321df60be742d9dfc11 Mon Sep 17 00:00:00 2001
From: James <james@eli.cx>
Date: Fri, 12 Jun 2026 13:01:50 +0100
Subject: [PATCH 06/11] refactor(ssr): clarify error shell root options

---
 packages/vinext/src/server/app-browser-entry.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/packages/vinext/src/server/app-browser-entry.ts b/packages/vinext/src/server/app-browser-entry.ts
index dd60c9ce0..657bccc2b 100644
--- a/packages/vinext/src/server/app-browser-entry.ts
+++ b/packages/vinext/src/server/app-browser-entry.ts
@@ -1614,11 +1614,14 @@ function bootstrapHydration(rscStream: ReadableStream<Uint8Array>): void {
   // rendered global-error pages. That is upstream-compatible — the browser
   // should always createRoot when the document is the default error shell.
   if (document.documentElement.id === "__next_error__") {
+    // There is no server-rendered form to hydrate in this client-render path;
+    // reuse only the shared root error callbacks and related root options.
+    const { formState: _inertFormState, ...createRootOptions } = hydrateRootOptions;
     for (const style of document.querySelectorAll("style[data-vinext-error-shell-style]")) {
       style.remove();
     }
     startTransition(() => {
-      const clientRoot = createRoot(document, hydrateRootOptions);
+      const clientRoot = createRoot(document, createRootOptions);
       clientRoot.render(children);
       window.__VINEXT_RSC_ROOT__ = clientRoot;
     });

From 2a6292a7c78b19bd42a5de64bcd18da89fd95b3c Mon Sep 17 00:00:00 2001
From: James <james@eli.cx>
Date: Fri, 12 Jun 2026 13:12:38 +0100
Subject: [PATCH 07/11] fix(isr): recover shell errors during regeneration

---
 packages/vinext/src/index.ts                    | 2 +-
 packages/vinext/src/server/app-page-dispatch.ts | 1 +
 tests/app-page-dispatch.test.ts                 | 6 ++++++
 3 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/packages/vinext/src/index.ts b/packages/vinext/src/index.ts
index 699847fcf..fc82018f4 100644
--- a/packages/vinext/src/index.ts
+++ b/packages/vinext/src/index.ts
@@ -2605,7 +2605,7 @@ export default function vinext(options: VinextOptions = {}): PluginOption[] {
               this.environment?.name === "rsc"
                 ? `${reactServerShim}.react-server`
                 : reactServerShim;
-            return resolveShimModulePath(_shimsDir, stripJsExtension(shimName));
+            return resolveShimModulePath(_shimsDir, shimName);
           }
         },
       },
diff --git a/packages/vinext/src/server/app-page-dispatch.ts b/packages/vinext/src/server/app-page-dispatch.ts
index 2c3325e22..5053ccd82 100644
--- a/packages/vinext/src/server/app-page-dispatch.ts
+++ b/packages/vinext/src/server/app-page-dispatch.ts
@@ -664,6 +664,7 @@ async function dispatchAppPageInner<TRoute extends AppPageDispatchRoute>(
                 reactMaxHeadersLength: options.reactMaxHeadersLength,
                 rootParams: options.rootParams,
                 waitForAllReady: true,
+                fallbackToErrorDocumentOnShellError: options.hasCustomGlobalError === false,
                 ...(revalidatedRscCapture.sideStream
                   ? {
                       sideStream: revalidatedRscCapture.sideStream,
diff --git a/tests/app-page-dispatch.test.ts b/tests/app-page-dispatch.test.ts
index b0cfea77a..068c2db4f 100644
--- a/tests/app-page-dispatch.test.ts
+++ b/tests/app-page-dispatch.test.ts
@@ -265,6 +265,7 @@ function createDispatchOptions(
     dynamicConfig?: DispatchOptions["dynamicConfig"];
     findIntercept?: DispatchOptions["findIntercept"];
     generateStaticParams?: DispatchOptions["generateStaticParams"];
+    hasCustomGlobalError?: DispatchOptions["hasCustomGlobalError"];
     formState?: DispatchOptions["formState"];
     getSourceRoute?: DispatchOptions["getSourceRoute"];
     actionError?: DispatchOptions["actionError"];
@@ -338,6 +339,7 @@ function createDispatchOptions(
     },
     getSourceRoute: overrides.getSourceRoute ?? (() => undefined),
     hasGenerateStaticParams: typeof overrides.generateStaticParams === "function",
+    hasCustomGlobalError: overrides.hasCustomGlobalError,
     hasPageDefaultExport: true,
     hasPageModule: true,
     handlerStart: 10,
@@ -1187,6 +1189,7 @@ describe("app page dispatch", () => {
       scheduledRender = renderFn;
     };
     let capturedWaitForAllReady: boolean | undefined;
+    let capturedFallbackToErrorDocument: boolean | undefined;
     const isrSet = vi.fn(async () => {});
     const { options } = createDispatchOptions({
       buildPageElement: async () => React.createElement("main", null, "fresh"),
@@ -1196,9 +1199,11 @@ describe("app page dispatch", () => {
         buildISRCacheEntry(buildCachedAppPageValue("<html>stale</html>"), true),
       ),
       isrSet,
+      hasCustomGlobalError: false,
       loadSsrHandler: async () => ({
         async handleSsr(_rscStream, _navigationContext, _fontData, captureOptions) {
           capturedWaitForAllReady = captureOptions?.waitForAllReady;
+          capturedFallbackToErrorDocument = captureOptions?.fallbackToErrorDocumentOnShellError;
           if (captureOptions?.capturedRscDataRef) {
             captureOptions.capturedRscDataRef.value = Promise.resolve(
               new TextEncoder().encode("fresh-flight").buffer,
@@ -1228,6 +1233,7 @@ describe("app page dispatch", () => {
     await scheduledRender();
 
     expect(capturedWaitForAllReady).toBe(true);
+    expect(capturedFallbackToErrorDocument).toBe(true);
     expect(isrSet).toHaveBeenCalled();
   });
 });

From 57b01b4614a95791b5079d684e0af411bd74c821 Mon Sep 17 00:00:00 2001
From: James <james@eli.cx>
Date: Fri, 12 Jun 2026 13:32:51 +0100
Subject: [PATCH 08/11] fix(ssr): scope client recovery to marked shells

---
 packages/vinext/src/index.ts                  |  2 +-
 .../vinext/src/server/app-browser-entry.ts    | 21 ++++++-------
 .../ssr-error-shell-recovery.browser.spec.ts  | 24 ++++++++++++++
 tests/shims.test.ts                           | 31 +++++++++++++++++++
 4 files changed, 65 insertions(+), 13 deletions(-)

diff --git a/packages/vinext/src/index.ts b/packages/vinext/src/index.ts
index fc82018f4..c21294b9f 100644
--- a/packages/vinext/src/index.ts
+++ b/packages/vinext/src/index.ts
@@ -2591,7 +2591,7 @@ export default function vinext(options: VinextOptions = {}): PluginOption[] {
           if (cleanId.startsWith(vinextShimPrefix)) {
             return resolveShimModulePath(
               _shimsDir,
-              stripJsExtension(cleanId.slice(vinextShimPrefix.length)),
+              stripJsExtension(stripViteModuleQuery(cleanId.slice(vinextShimPrefix.length))),
             );
           }
 
diff --git a/packages/vinext/src/server/app-browser-entry.ts b/packages/vinext/src/server/app-browser-entry.ts
index 657bccc2b..89baa7d51 100644
--- a/packages/vinext/src/server/app-browser-entry.ts
+++ b/packages/vinext/src/server/app-browser-entry.ts
@@ -1607,17 +1607,16 @@ function bootstrapHydration(rscStream: ReadableStream<Uint8Array>): void {
     initialElements: root,
     initialNavigationSnapshot,
   });
-  // The `__next_error__` marker is intentionally broad: it detects the default
-  // error document generally, not only the new SSR shell-error recovery path.
-  // Both `DefaultGlobalError` (used here) and the boundary renderer emit
-  // `<html id="__next_error__">`, so this branch also fires for legacy server-
-  // rendered global-error pages. That is upstream-compatible — the browser
-  // should always createRoot when the document is the default error shell.
-  if (document.documentElement.id === "__next_error__") {
+  const errorShellStyles = document.querySelectorAll("style[data-vinext-error-shell-style]");
+  // Only the SSR shell-error recovery document carries the style marker.
+  // Legacy server-rendered default-error pages also use `__next_error__`, but
+  // keep their existing hydration path so the serialized server error digest
+  // remains available to DefaultGlobalError.
+  if (document.documentElement.id === "__next_error__" && errorShellStyles.length > 0) {
     // There is no server-rendered form to hydrate in this client-render path;
     // reuse only the shared root error callbacks and related root options.
     const { formState: _inertFormState, ...createRootOptions } = hydrateRootOptions;
-    for (const style of document.querySelectorAll("style[data-vinext-error-shell-style]")) {
+    for (const style of errorShellStyles) {
       style.remove();
     }
     startTransition(() => {
@@ -2212,10 +2211,8 @@ function bootstrapHydration(rscStream: ReadableStream<Uint8Array>): void {
       // current URL. If the edit fixed the error the page comes back clean; if
       // not, initial dev server errors re-populate the overlay.
       //
-      // The `__next_error__` marker is broad — see the matching comment in
-      // bootstrapHydration above. Reloading here is safe for any default-error
-      // document because the dev server will render the current state of the
-      // source after the edit.
+      // Reloading is safe for any default-error document because the dev
+      // server will render the current state of the source after the edit.
       if (document.documentElement.id === "__next_error__") {
         window.location.reload();
         return;
diff --git a/tests/e2e/app-router/nextjs-compat/ssr-error-shell-recovery.browser.spec.ts b/tests/e2e/app-router/nextjs-compat/ssr-error-shell-recovery.browser.spec.ts
index 00cffba5e..18718b44a 100644
--- a/tests/e2e/app-router/nextjs-compat/ssr-error-shell-recovery.browser.spec.ts
+++ b/tests/e2e/app-router/nextjs-compat/ssr-error-shell-recovery.browser.spec.ts
@@ -163,6 +163,19 @@ export default function Client() {
 `,
   );
 
+  // Genuine RSC/server error with no custom global-error.tsx. It also uses an
+  // __next_error__ document, but must retain the pre-existing hydration path
+  // rather than being mistaken for the marked SSR shell-recovery document.
+  const serverErrorDir = path.join(appDir, "server-error");
+  await fs.mkdir(serverErrorDir, { recursive: true });
+  await fs.writeFile(
+    path.join(serverErrorDir, "page.tsx"),
+    `export default function ServerErrorPage(): never {
+  throw new Error("genuine server digest error");
+}
+`,
+  );
+
   // Local error.tsx routes: the shell fallback must not swallow local
   // boundary semantics. Local boundaries for shell errors materialize
   // client-side from the flight payload (Next.js parity):
@@ -296,6 +309,16 @@ test.describe("SSR shell-error recovery (no custom global-error.tsx)", () => {
       await expect(page.locator("#static-server-content")).toHaveText("Hello Static Server");
       await expect(page.locator("#static-client-content")).toHaveText("Hello Static Client");
 
+      // A genuine server/RSC error also uses the default __next_error__
+      // document, but has no recovery-shell style marker. It must keep the
+      // existing hydrated default-error card instead of entering createRoot.
+      await page.goto(`${app.baseUrl}/server-error`, { waitUntil: "load" });
+      await expect(page.getByRole("heading", { name: "This page couldn’t load" })).toBeVisible();
+      await expect(page.getByText("Reload to try again, or go back.")).toBeVisible();
+      await expect(page.getByRole("button", { name: "Reload" })).toBeVisible();
+      await expect(page.getByRole("button", { name: "Back" })).toBeVisible();
+      await expect(page.locator("style[data-vinext-error-shell-style]")).toHaveCount(0);
+
       // SSR-only throw with a local error.tsx: browser re-render succeeds, so
       // the content (not the boundary) appears.
       await page.goto(`${app.baseUrl}/boundary-ssr-only`, { waitUntil: "load" });
@@ -315,6 +338,7 @@ test.describe("SSR shell-error recovery (no custom global-error.tsx)", () => {
       const unexpectedErrors = consoleErrors.filter(
         (message) =>
           !message.includes("boundary throw") &&
+          !message.includes("genuine server digest error") &&
           !message.includes("Expected error to opt out of server rendering") &&
           // React's companion log for an error caught by a boundary.
           !message.startsWith("The above error occurred in a React component"),
diff --git a/tests/shims.test.ts b/tests/shims.test.ts
index 6dd5c7878..f8e4d6fba 100644
--- a/tests/shims.test.ts
+++ b/tests/shims.test.ts
@@ -18993,6 +18993,37 @@ describe("@vercel/og compatibility resolution", () => {
   });
 });
 
+describe("vinext shim package-subpath resolution", () => {
+  type ResolveIdHook = {
+    filter: { id: RegExp };
+    handler: (
+      this: { environment?: { name?: string } },
+      id: string,
+      importer?: string,
+    ) => string | undefined;
+  };
+
+  function getResolveIdHook(): ResolveIdHook {
+    const plugins = vinext() as Plugin[];
+    const configPlugin = plugins.find((plugin) => plugin.name === "vinext:config");
+    if (!configPlugin?.resolveId || typeof configPlugin.resolveId === "function") {
+      throw new Error("vinext:config resolveId hook not found");
+    }
+    return configPlugin.resolveId as ResolveIdHook;
+  }
+
+  it("strips JavaScript extensions and Vite queries from package subpaths", () => {
+    const hook = getResolveIdHook();
+    const expectedShim = path.resolve(
+      import.meta.dirname,
+      "../packages/vinext/src/shims/navigation.ts",
+    );
+
+    expect(hook.filter.id.test("vinext/shims/navigation.js?v=123")).toBe(true);
+    expect(hook.handler.call({}, "vinext/shims/navigation.js?v=123")).toBe(expectedShim);
+  });
+});
+
 // ── next/head attribute name validation ─────────────────────────────────────
 
 describe("isSafeAttrName", () => {

From 2da12421cb7b356238aab6ffaf8dcd7699ea05c7 Mon Sep 17 00:00:00 2001
From: James <james@eli.cx>
Date: Fri, 12 Jun 2026 14:06:50 +0100
Subject: [PATCH 09/11] fix(plugin): explicitly filter vinext shim subpaths

---
 packages/vinext/src/index.ts | 5 +++--
 tests/shims.test.ts          | 1 +
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/vinext/src/index.ts b/packages/vinext/src/index.ts
index c21294b9f..ae5a66a5a 100644
--- a/packages/vinext/src/index.ts
+++ b/packages/vinext/src/index.ts
@@ -2500,11 +2500,12 @@ export default function vinext(options: VinextOptions = {}): PluginOption[] {
 
       resolveId: {
         // Hook filter: only invoke JS for handled Next/Vinext compatibility modules.
-        // Matches "next/navigation", "next/router.js", "virtual:vinext-rsc-entry",
+        // Matches "next/navigation", "next/router.js", internal
+        // "vinext/shims/*" package subpaths, "virtual:vinext-rsc-entry",
         // direct @vercel/og imports in metadata routes, and \0-prefixed
         // re-imports from @vitejs/plugin-rsc.
         filter: {
-          id: /(?:next\/|virtual:vinext-|^@vercel\/og(?:\.js)?$)/,
+          id: /(?:^next\/|^vinext\/shims\/|virtual:vinext-|^@vercel\/og(?:\.js)?$)/,
         },
         handler(id, importer) {
           // Strip \0 prefix if present — @vitejs/plugin-rsc's generated
diff --git a/tests/shims.test.ts b/tests/shims.test.ts
index f8e4d6fba..afcc930fd 100644
--- a/tests/shims.test.ts
+++ b/tests/shims.test.ts
@@ -19020,6 +19020,7 @@ describe("vinext shim package-subpath resolution", () => {
     );
 
     expect(hook.filter.id.test("vinext/shims/navigation.js?v=123")).toBe(true);
+    expect(hook.filter.id.test("unrelated-next/navigation")).toBe(false);
     expect(hook.handler.call({}, "vinext/shims/navigation.js?v=123")).toBe(expectedShim);
   });
 });

From e9f011982c5dacb49bd7b4c8c368b6811e412631 Mon Sep 17 00:00:00 2001
From: James <james@eli.cx>
Date: Fri, 12 Jun 2026 14:34:34 +0100
Subject: [PATCH 10/11] fix(plugin): retain null-prefixed shim resolution

---
 packages/vinext/src/index.ts |  2 +-
 tests/shims.test.ts          | 17 ++++++++++++++++-
 2 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/packages/vinext/src/index.ts b/packages/vinext/src/index.ts
index ae5a66a5a..185b265d5 100644
--- a/packages/vinext/src/index.ts
+++ b/packages/vinext/src/index.ts
@@ -2505,7 +2505,7 @@ export default function vinext(options: VinextOptions = {}): PluginOption[] {
         // direct @vercel/og imports in metadata routes, and \0-prefixed
         // re-imports from @vitejs/plugin-rsc.
         filter: {
-          id: /(?:^next\/|^vinext\/shims\/|virtual:vinext-|^@vercel\/og(?:\.js)?$)/,
+          id: /(?:next\/|vinext\/shims\/|virtual:vinext-|@vercel\/og(?:\.js)?$)/,
         },
         handler(id, importer) {
           // Strip \0 prefix if present — @vitejs/plugin-rsc's generated
diff --git a/tests/shims.test.ts b/tests/shims.test.ts
index afcc930fd..2cd38dcb8 100644
--- a/tests/shims.test.ts
+++ b/tests/shims.test.ts
@@ -19018,10 +19018,25 @@ describe("vinext shim package-subpath resolution", () => {
       import.meta.dirname,
       "../packages/vinext/src/shims/navigation.ts",
     );
+    const expectedReactServerShim = path.resolve(
+      import.meta.dirname,
+      "../packages/vinext/src/shims/navigation.react-server.ts",
+    );
+    const expectedOgShim = path.resolve(import.meta.dirname, "../packages/vinext/src/shims/og.tsx");
 
     expect(hook.filter.id.test("vinext/shims/navigation.js?v=123")).toBe(true);
-    expect(hook.filter.id.test("unrelated-next/navigation")).toBe(false);
+    expect(hook.filter.id.test("\0vinext/shims/navigation.js?v=123")).toBe(true);
+    expect(hook.filter.id.test("\0next/navigation")).toBe(true);
+    expect(hook.filter.id.test("\0@vercel/og")).toBe(true);
+    expect(hook.handler.call({}, "unrelated-next/navigation")).toBeUndefined();
     expect(hook.handler.call({}, "vinext/shims/navigation.js?v=123")).toBe(expectedShim);
+    expect(hook.handler.call({}, "\0vinext/shims/navigation.js?v=123")).toBe(expectedShim);
+    expect(hook.handler.call({ environment: { name: "rsc" } }, "\0next/navigation")).toBe(
+      expectedReactServerShim,
+    );
+    expect(
+      hook.handler.call({}, "\0@vercel/og", path.join(FIXTURE_DIR, "app/opengraph-image.tsx")),
+    ).toBe(expectedOgShim);
   });
 });
 

From a2f481b9459357fa9ae01ab286feb39bca859705 Mon Sep 17 00:00:00 2001
From: Nathan Nguyen <146415969+NathanDrake2406@users.noreply.github.com>
Date: Sat, 13 Jun 2026 01:37:49 +1000
Subject: [PATCH 11/11] test(nextjs-compat): cover no-boundary shell recovery
 fallback

An unconditional client throw during SSR shell recovery without a local error boundary must still land on the default global-error card. Without a regression test, a future change could tear down the recovery shell and leave a blank document.\n\nAdd a production browser case that exercises the no-boundary route and asserts the default error UI after the client re-render throws again.
---
 .../ssr-error-shell-recovery.browser.spec.ts  | 35 +++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/tests/e2e/app-router/nextjs-compat/ssr-error-shell-recovery.browser.spec.ts b/tests/e2e/app-router/nextjs-compat/ssr-error-shell-recovery.browser.spec.ts
index 18718b44a..548e750a4 100644
--- a/tests/e2e/app-router/nextjs-compat/ssr-error-shell-recovery.browser.spec.ts
+++ b/tests/e2e/app-router/nextjs-compat/ssr-error-shell-recovery.browser.spec.ts
@@ -238,6 +238,31 @@ export default function Client(): React.ReactNode {
   );
   await fs.writeFile(path.join(boundaryAlwaysDir, "error.tsx"), localErrorBoundary);
 
+  // Ported from Next.js default global-error client runtime semantics:
+  // https://github.com/vercel/next.js/blob/canary/test/e2e/app-dir/errors/index.test.ts
+  // Combined with the SSR shell-recovery entry path exercised by:
+  // https://github.com/vercel/next.js/blob/canary/test/e2e/app-dir/next-dynamic-css/next-dynamic-css.test.ts
+  const noBoundaryAlwaysDir = path.join(appDir, "no-boundary-always");
+  await fs.mkdir(noBoundaryAlwaysDir, { recursive: true });
+  await fs.writeFile(
+    path.join(noBoundaryAlwaysDir, "page.tsx"),
+    `import React from "react";
+import Client from "./Client";
+export default function NoBoundaryAlwaysPage() {
+  return <Client />;
+}
+`,
+  );
+  await fs.writeFile(
+    path.join(noBoundaryAlwaysDir, "Client.tsx"),
+    `"use client";
+import React from "react";
+export default function Client(): React.ReactNode {
+  throw new Error("always no boundary throw");
+}
+`,
+  );
+
   const vinextSource = path.resolve(process.cwd(), "packages/vinext/src/index.ts");
   await fs.writeFile(
     path.join(fixtureRoot, "vite.config.ts"),
@@ -332,12 +357,22 @@ test.describe("SSR shell-error recovery (no custom global-error.tsx)", () => {
       await page.goto(`${app.baseUrl}/boundary-always`, { waitUntil: "load" });
       await expect(page.locator("#local-error-boundary")).toHaveText("Local boundary caught it");
 
+      // No local boundary: the shell recovery still re-renders on the client,
+      // but the root default global-error boundary must catch the repeated
+      // throw instead of leaving a blank torn-down document.
+      await page.goto(`${app.baseUrl}/no-boundary-always`, { waitUntil: "load" });
+      await expect(page.getByRole("heading", { name: "This page couldn’t load" })).toBeVisible();
+      await expect(page.getByText("Reload to try again, or go back.")).toBeVisible();
+      await expect(page.getByRole("button", { name: "Reload" })).toBeVisible();
+      await expect(page.getByRole("button", { name: "Back" })).toBeVisible();
+
       // The boundary routes throw on purpose, and React logs caught boundary
       // errors to the console. Drop those expected entries but stay strict
       // about anything else; the fixture re-asserts emptiness at teardown.
       const unexpectedErrors = consoleErrors.filter(
         (message) =>
           !message.includes("boundary throw") &&
+          !message.includes("always no boundary throw") &&
           !message.includes("genuine server digest error") &&
           !message.includes("Expected error to opt out of server rendering") &&
           // React's companion log for an error caught by a boundary.