fix(html): load the page in full when swapping it in fails

When anything in the swap threw (`parsePage` reading router data from a
build that writes it differently, a component throwing as it unmounts),
the handler's promise rejected. The Navigation API has no fallback for
that, it only fires `navigateerror`: the URL had already moved to the
next page while the document kept showing the previous one, or half of
the next.

Any error now takes the path a page from another deployment already
took: it is logged, and the page reloads, which is a full load of the
URL the navigation moved to. That cannot loop: `shouldIntercept` never
intercepts a reload, and a page loaded in full does not navigate by
itself. `shouldIntercept` is exported, with unit tests that pin this.

Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: ovflowd

e2e/client-side-navigation.spec.js

@@ -148,4 +148,36 @@ test.describe('Client-side navigation', () => {
     await expect(page).toHaveURL(/\/assert\.json$/);
     expect(await page.evaluate(() => window.__document)).toBeUndefined();
   });
+
+  test('loads the page in full when it cannot swap it in', async ({ page }) => {
+    // The router's copy is the page as another build writes it, with router
+    // data this one cannot read; the full load gets the real page
+    await page.route(/\/all(\.html)?$/, async route => {
+      if (route.request().resourceType() !== 'fetch') {
+        return route.fallback();
+      }
+
+      const response = await route.fetch();
+      const body = (await response.text()).replace(
+        /(<script[^>]*data-router[^>]*>)[^<]*/,
+        '$1{"assets":{}}'
+      );
+
+      return route.fulfill({ response, body });
+    });
+
+    let loads = 0;
+    page.on('load', () => loads++);
+
+    await page.evaluate(() => {
+      navigation.navigate('all.html');
+    });
+
+    await expect(page).toHaveTitle(/^All \|/);
+    expect(await page.evaluate(() => window.__document)).toBeUndefined();
+
+    // Reloads are never intercepted, so the full load is the only one
+    await page.waitForTimeout(500);
+    expect(loads).toBe(1);
+  });
 });

packages/react/src/html/README.md

@@ -532,7 +532,7 @@ Everything else is a regular navigation: links outside the site (including
 other versions of the docs), files that are not pages (such as the JSON and
 Markdown renderings), and every navigation in a browser without the Navigation
 API. So is a page that loads scripts or stylesheets the current one did not,
-such as one from a newer deployment.
+such as one from a newer deployment, or one that fails to swap in.
 
 When customizing the site, keep in mind that:
 

packages/react/src/html/ui/__tests__/router.test.mjs

@@ -1,7 +1,7 @@
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 
-import { isPage, withoutFragment } from '../router.mjs';
+import { isPage, shouldIntercept, withoutFragment } from '../router.mjs';
 
 const root = 'https://nodejs.org/docs/latest/api/';
 
@@ -52,3 +52,53 @@ describe('withoutFragment', () => {
     assert.strictEqual(withoutFragment(`${root}fs.html`), `${root}fs.html`);
   });
 });
+
+describe('shouldIntercept', () => {
+  const url = new URL('fs.html', root);
+
+  /**
+   * The `navigate` event following a link to another page fires.
+   *
+   * @param {object} [overrides]
+   */
+  const event = overrides => ({
+    canIntercept: true,
+    hashChange: false,
+    downloadRequest: null,
+    formData: null,
+    navigationType: 'push',
+    ...overrides,
+  });
+
+  it('intercepts following a link to another page', () => {
+    assert.ok(shouldIntercept(event(), url, root));
+  });
+
+  it('intercepts going back and forward between pages', () => {
+    assert.ok(
+      shouldIntercept(event({ navigationType: 'traverse' }), url, root)
+    );
+  });
+
+  it('never intercepts a reload, which is always a full load', () => {
+    assert.ok(!shouldIntercept(event({ navigationType: 'reload' }), url, root));
+  });
+
+  it('leaves fragments, downloads, forms and other sites to the browser', () => {
+    for (const overrides of [
+      { hashChange: true },
+      { downloadRequest: 'fs.html' },
+      { formData: new FormData() },
+      { canIntercept: false },
+    ]) {
+      assert.ok(
+        !shouldIntercept(event(overrides), url, root),
+        Object.keys(overrides)[0]
+      );
+    }
+  });
+
+  it('leaves files that are not pages to the browser', () => {
+    assert.ok(!shouldIntercept(event(), new URL('fs.json', root), root));
+  });
+});

packages/react/src/html/ui/router.mjs

@@ -56,13 +56,14 @@ export const shouldFollowLink = link =>
   (!link.target || link.target === '_self');
 
 /**
- * Whether a navigation event should be intercepted by the router.
+ * Whether a navigation event should be intercepted by the router. Reloads
+ * never are, so the router can always fall back to one for a full load.
  *
  * @param {NavigateEvent} event
  * @param {URL} url
  * @param {string} root
  */
-const shouldIntercept = (event, url, root) =>
+export const shouldIntercept = (event, url, root) =>
   event.canIntercept &&
   !event.hashChange &&
   event.downloadRequest === null &&
@@ -201,17 +202,24 @@ export const startRouter = ({ unmount, islands }) => {
           return;
         }
 
-        const doc = page && parsePage(page, assets);
+        try {
+          const doc = page && parsePage(page, assets);
 
-        if (!doc) {
-          // The navigation has already moved to the page's URL, so reloading
-          // is a full load of that page
-          location.reload();
+          if (doc) {
+            transition(() =>
+              showPage(doc, () => event.scroll(), unmount, islands)
+            );
 
-          return;
+            return;
+          }
+        } catch (error) {
+          // The swap may have stopped halfway, which only a full load undoes
+          console.error('[router] failed to show', url.href, error);
         }
 
-        transition(() => showPage(doc, () => event.scroll(), unmount, islands));
+        // The navigation has already moved to the page's URL, so reloading
+        // is a full load of that page (see `shouldIntercept`)
+        location.reload();
       },
     });
   });