@pylonsync/functions 0.3.293 → 0.3.294

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.3.293",
+  "version": "0.3.294",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/ssr-client-bundler.test.ts

@@ -160,6 +160,38 @@ describe("ssr-client-bundler (Phase 1.5e)", () => {
     expect(chunkHasReact).toBe(true);
   });
 
+  test("client runtime wires the nav-fallback guard (uncaught render error → full page load)", async () => {
+    // Regression: a page that renders React-19-hoisted <title>/<meta>/<link> in
+    // its own tree (use the `metadata` export instead) makes a client-side nav
+    // re-render throw in React's commit phase — the URL changes but the page
+    // can't swap (white screen). hydrateRoot must carry an onUncaughtError that
+    // falls back to a full page load of the in-flight destination so nav
+    // degrades gracefully. The distinctive console string is preserved through
+    // minification, so we assert the guard actually ships in the bundle.
+    tempDir = makeFixture(
+      { "page.tsx": PAGE_BODY("Home") },
+      { "layout.tsx": LAYOUT_BODY },
+    );
+    originalCwd = process.cwd();
+    process.chdir(tempDir);
+
+    const { outdir } = await buildClientBundle();
+    // The runtime (hydrateRoot + guard) lands in the shared chunk with multiple
+    // entries, or inlined in the entry with one — read every emitted .js.
+    const readJsRecursive = (dir: string): string[] =>
+      fs.readdirSync(dir, { withFileTypes: true }).flatMap((d) => {
+        const full = path.join(dir, d.name);
+        if (d.isDirectory()) return readJsRecursive(full);
+        return d.name.endsWith(".js") ? [fs.readFileSync(full, "utf8")] : [];
+      });
+    const bundled = readJsRecursive(outdir).join("\n");
+
+    // onUncaughtError is a React hydrateRoot option (property name preserved).
+    expect(bundled).toMatch(/onUncaughtError/);
+    // The fallback path: a full page load of the pending destination.
+    expect(bundled).toMatch(/falling back to a full page load/);
+  });
+
   test("manifest names every route, each with a non-empty imports list", async () => {
     tempDir = makeFixture(
       {

package/src/ssr-client-bundler.ts

@@ -212,6 +212,10 @@ import { createPylonBoundary } from "./client-boundary";
 
 const routeCache = Object.create(null);
 let activeRoot = null;
+// Destination of an in-flight client navigation. Read by hydrateRoot's
+// onUncaughtError so a re-render that throws mid-nav degrades to a full page
+// load instead of a white screen. Null when no nav is in flight.
+let pendingNav = null;
 let manifestPromise = null;
 const prefetchedChunks = new Set();
 
@@ -466,7 +470,30 @@ export function hydrate(component, Page, Layouts) {
       data.component,
       navEpoch,
     );
-    activeRoot = hydrateRoot(document, tree);
+    activeRoot = hydrateRoot(document, tree, {
+      // Safety net for client navigation. If a nav re-render throws an uncaught
+      // error in React's commit phase, the URL has already changed but the page
+      // can't swap — a white/stale screen. The classic trigger is a page that
+      // renders hoisted <title>/<meta>/<link> in its own tree (use the
+      // \`metadata\` export instead); React 19 owns those head nodes on the client
+      // and reconciling them across routes can throw. Rather than strand the
+      // user, fall back to a full page load of the pending destination, which
+      // re-renders it cleanly from SSR. Non-navigation errors keep React's
+      // default reporting.
+      onUncaughtError(error) {
+        if (pendingNav) {
+          const dest = pendingNav;
+          pendingNav = null;
+          console.error(
+            "[pylon ssr] client navigation failed to render; falling back to a full page load:",
+            error,
+          );
+          window.location.href = dest;
+          return;
+        }
+        console.error(error);
+      },
+    });
     installNavHandlers();
     return;
   }
@@ -544,13 +571,21 @@ async function navigate(href, opts) {
   setNavParams(data);
   navEpoch++;
   currentPageProps = withClientProps(data);
+  const target = url.pathname + url.search;
   const tree = withBoundary(
     buildTree(route.Page, route.Layouts, currentPageProps),
     data.component,
     navEpoch,
   );
+  // Track the in-flight destination so hydrateRoot's onUncaughtError can fall
+  // back to a full page load if this re-render throws in React's commit phase
+  // (instead of leaving the URL changed but the page unswapped). Cleared on the
+  // next macrotask once the commit has settled with no error.
+  pendingNav = target;
   activeRoot.render(tree);
-  const target = url.pathname + url.search;
+  setTimeout(() => {
+    if (pendingNav === target) pendingNav = null;
+  }, 0);
   if (opts && opts.replace) {
     history.replaceState({ component: data.component }, "", target);
   } else if (push) {