@pylonsync/functions 0.22.20 → 0.22.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.22.20",
+  "version": "0.22.21",
   "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

@@ -687,6 +687,28 @@ describe("loading.tsx is wired into the client build", () => {
     expect(sharedChunks).toContain("app/dashboard/loading");
   });
 
+  test("first hydration wraps the page in the same Suspense boundary the server renders", async () => {
+    tempDir = makeFixture(
+      {
+        "dashboard/page.tsx": PAGE_BODY("Dash"),
+        "dashboard/loading.tsx": LOADING_BODY,
+      },
+      { "layout.tsx": LAYOUT_BODY },
+    );
+    originalCwd = process.cwd();
+    process.chdir(tempDir);
+    await buildClientBundle();
+    const runtime = fs.readFileSync(
+      path.join(tempDir, ".pylon", "client-runtime.ts"),
+      "utf8",
+    );
+    // The hydrating tree is built with the page's component path, which
+    // resolves its loading module and wraps the page in <Suspense>
+    // (see ssr-hydration.test.ts for why a missing boundary breaks hydration).
+    expect(runtime).toContain("buildTree(Page, Layouts, currentPageProps, data.component)");
+    expect(runtime).toContain("createElement(Suspense, { fallback: createElement(Loading, props) }, tree)");
+  });
+
   test("an app with no loading.tsx still builds and navigates", async () => {
     // The runtime's import of ./loading-registry is unconditional, so the
     // staged module must exist even with nothing to put in it.

package/src/ssr-client-bundler.ts

@@ -348,7 +348,7 @@ ${entries}
 const CLIENT_RUNTIME_SOURCE = `// Generated by Pylon SSR (Phase 2 client runtime).
 // DO NOT EDIT — overwritten on every pylon dev / build.
 
-import { createElement } from "react";
+import { createElement, Suspense } from "react";
 import { hydrateRoot } from "react-dom/client";
 import { configureClient } from "@pylonsync/react";
 import { createPylonBoundary, nearestBoundaryComponent } from "./client-boundary";
@@ -368,8 +368,18 @@ let pendingNav = null;
 let manifestPromise = null;
 const prefetchedChunks = new Set();
 
-function buildTree(Page, Layouts, props) {
+function buildTree(Page, Layouts, props, loadingFor) {
   let tree = createElement(Page, props);
+  // The server wraps the page of a route with a loading.tsx in ONE Suspense
+  // boundary, fallback = that loading module (ssr-runtime.ts, #278). The
+  // tree that hydrates the server HTML must have the same boundary, or React
+  // finds <Suspense> where it expects the page's first element, throws a
+  // hydration mismatch (#418) and re-renders the whole document; clicks in
+  // that window are lost. \`loadingFor\` is the page's component path.
+  const Loading = loadingFor ? nearestLoading(loadingFor) : null;
+  if (Loading) {
+    tree = createElement(Suspense, { fallback: createElement(Loading, props) }, tree);
+  }
   for (let i = Layouts.length - 1; i >= 0; i--) {
     const Layout = Layouts[i];
     if (!Layout) continue;
@@ -378,6 +388,13 @@ function buildTree(Page, Layouts, props) {
   return tree;
 }
 
+// The loading module the server wraps \`component\` in: the nearest
+// loading.tsx walking up from the page's directory.
+function nearestLoading(component) {
+  const key = nearestBoundaryComponent(component, "loading", Object.keys(LOADING_MODULES));
+  return key ? LOADING_MODULES[key] : null;
+}
+
 // ---------------------------------------------------------------------------
 // Client error / not-found boundary. notFound() (from @pylonsync/react) and
 // any other error thrown DURING a client render — the normal case when an
@@ -714,7 +731,7 @@ export function hydrate(component, Page, Layouts) {
     currentPageProps = withClientProps(data);
     currentComponent = data.component;
     const tree = withBoundary(
-      buildTree(Page, Layouts, currentPageProps),
+      buildTree(Page, Layouts, currentPageProps, data.component),
       data.component,
       navEpoch,
     );

package/src/ssr-hydration.test.ts

@@ -164,3 +164,77 @@ describe("streaming hydration (#278)", () => {
     }
   });
 });
+
+// A route with a loading.tsx: ssr-runtime.ts wraps the page in ONE Suspense
+// boundary whose fallback is the loading module, inside the layouts. The
+// client's first hydration must build the same tree (buildTree's
+// `loadingFor` in ssr-client-bundler.ts). Without the boundary, React finds
+// the server's Suspense marker where it expects the page's first element and
+// throws a hydration mismatch (#418): Stack0 Cloud's dashboard did this on
+// every load, since app/dashboard/loading.tsx exists.
+describe("route-level loading.tsx hydration", () => {
+  function Layout({ children }: { children?: any }) {
+    return React.createElement("main", { id: "layout" }, children);
+  }
+  function Loading() {
+    return React.createElement("p", { id: "pending" }, "Loading…");
+  }
+  function DashPage() {
+    return React.createElement("div", { id: "page" }, "Dashboard");
+  }
+  const withBoundary = (page: any) =>
+    React.createElement(Suspense, { fallback: React.createElement(Loading) }, page);
+
+  async function serverHtml(): Promise<string> {
+    const stream = await renderToReadableStream(
+      React.createElement(Layout, null, withBoundary(React.createElement(DashPage))),
+    );
+    await (stream as any).allReady;
+    const reader = stream.getReader();
+    let html = "";
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      html += dec.decode(value);
+    }
+    return html;
+  }
+
+  async function hydrateErrors(clientTree: any): Promise<string[]> {
+    const html = await serverHtml();
+    const win = new Window({ url: "http://localhost/" });
+    const root = win.document.createElement("div");
+    root.insertAdjacentHTML("afterbegin", html);
+    win.document.body.appendChild(root);
+    registerDom(win);
+    const errors: string[] = [];
+    const origErr = console.error;
+    console.error = (...a: any[]) => {
+      errors.push(a.map(String).join(" "));
+    };
+    try {
+      const { hydrateRoot } = await import("react-dom/client");
+      hydrateRoot(root as any, clientTree, {
+        onRecoverableError: (e: any) => errors.push(String(e?.message ?? e)),
+      });
+      await new Promise((r) => setTimeout(r, 50));
+    } finally {
+      console.error = origErr;
+    }
+    return errors.filter((e) => /hydrat|did not match|mismatch/i.test(e));
+  }
+
+  test("the client tree with the same boundary hydrates without a mismatch", async () => {
+    const errors = await hydrateErrors(
+      React.createElement(Layout, null, withBoundary(React.createElement(DashPage))),
+    );
+    expect(errors).toEqual([]);
+  });
+
+  test("the client tree without the boundary mismatches (the bug)", async () => {
+    const errors = await hydrateErrors(
+      React.createElement(Layout, null, React.createElement(DashPage)),
+    );
+    expect(errors.length).toBeGreaterThan(0);
+  });
+});