@pylonsync/functions 0.22.41 → 0.22.44

package/dist/ssr-page-tree.d.ts

@@ -0,0 +1,4 @@
+type CreateElement = (type: any, props: any, ...children: any[]) => any;
+/** The page with its metadata slot. `meta` is null in the browser. */
+export declare function withMetaSlot(createElement: CreateElement, Fragment: any, meta: unknown, page: unknown): any;
+export {};

package/package.json

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

@@ -794,6 +794,13 @@ describe("loading.tsx is wired into the client build", () => {
     // (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)");
+    // The metadata slot the server renders beside every page, empty in the
+    // browser, from the same module the server uses (ssr-page-tree.ts).
+    expect(runtime).toContain('import { withMetaSlot } from "./page-tree";');
+    expect(runtime).toContain("tree = withMetaSlot(createElement, Fragment, null, tree);");
+    expect(fs.readFileSync(path.join(tempDir, ".pylon", "page-tree.ts"), "utf8")).toBe(
+      fs.readFileSync(path.join(import.meta.dir, "ssr-page-tree.ts"), "utf8"),
+    );
   });
 
   test("an app with no loading.tsx still builds and navigates", async () => {

package/src/ssr-client-bundler.ts

@@ -355,13 +355,14 @@ ${entries}
 const CLIENT_RUNTIME_SOURCE = `// Generated by Pylon SSR (Phase 2 client runtime).
 // DO NOT EDIT — overwritten on every pylon dev / build.
 
-import { createElement, Suspense } from "react";
+import { createElement, Fragment, Suspense } from "react";
 import { hydrateRoot } from "react-dom/client";
 import { configureClient } from "@pylonsync/react";
 import { createPylonBoundary, nearestBoundaryComponent } from "./client-boundary";
 import { LOADING_MODULES } from "./loading-registry";
 import { createNavPayloadCache } from "./nav-cache";
 import { matchRoute, prefetchTargets } from "./route-match";
+import { withMetaSlot } from "./page-tree";
 
 const routeCache = Object.create(null);
 let activeRoot = null;
@@ -387,6 +388,9 @@ function buildTree(Page, Layouts, props, loadingFor) {
   if (Loading) {
     tree = createElement(Suspense, { fallback: createElement(Loading, props) }, tree);
   }
+  // The server renders the page's metadata in this slot; the browser leaves
+  // it empty. Same shape on both sides, so useId values match (page-tree.ts).
+  tree = withMetaSlot(createElement, Fragment, null, tree);
   for (let i = Layouts.length - 1; i >= 0; i--) {
     const Layout = Layouts[i];
     if (!Layout) continue;
@@ -1568,6 +1572,14 @@ export async function _doBuildInner(
       "utf8",
     );
 
+    // Same pattern for the page's tree shape, which the server render
+    // shares (ssr-page-tree.ts): the runtime imports it as `./page-tree`.
+    fs.writeFileSync(
+      path.join(stageDir, "page-tree.ts"),
+      fs.readFileSync(path.join(here, "ssr-page-tree.ts"), "utf8"),
+      "utf8",
+    );
+
     // Same pattern for the optimistic-navigation route matcher — the runtime
     // imports it as `./route-match`; its source of truth is ssr-route-match.ts,
     // unit-tested directly.

package/src/ssr-hydration.test.ts

@@ -21,6 +21,7 @@ import { afterEach, describe, expect, test } from "bun:test";
 import { Window } from "happy-dom";
 import React, { Suspense, use } from "react";
 import { renderToReadableStream } from "react-dom/server.browser";
+import { withMetaSlot } from "./ssr-page-tree";
 
 // Mirrors `fulfilledThenable` in ssr-client-bundler.ts's CLIENT_RUNTIME_SOURCE:
 // a React-recognized fulfilled thenable so use() reads `.value` synchronously
@@ -238,3 +239,93 @@ describe("route-level loading.tsx hydration", () => {
     expect(errors.length).toBeGreaterThan(0);
   });
 });
+
+// Every page with metadata had different useId values on the server and in
+// the browser: the server put the metadata beside the page, the browser
+// hydrated the page alone. Radix menus, dialogs and form labels then
+// mismatched. Both sides now share withMetaSlot (ssr-page-tree.ts).
+describe("metadata slot keeps useId values stable", () => {
+  function Layout({ children }: { children?: any }) {
+    return React.createElement("main", { id: "layout" }, children);
+  }
+  function Control() {
+    const id = React.useId();
+    return React.createElement("button", { id: `menu-${id}`, "data-probe": "" }, "Menu");
+  }
+  function MenuPage() {
+    return React.createElement("div", { id: "page" }, React.createElement(Control));
+  }
+  const meta = React.createElement("meta", { name: "description", content: "A page" });
+
+  async function render(tree: any): Promise<string> {
+    const stream = await renderToReadableStream(tree);
+    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 hydrate(serverTree: any, clientTree: any) {
+    const html = await render(serverTree);
+    const serverId = /id="(menu-[^"]+)"/.exec(html)?.[1];
+    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 {
+      serverId,
+      errors: errors.filter((e) => /hydrat|did not match|mismatch/i.test(e)),
+    };
+  }
+
+  const e = React.createElement;
+
+  test("the server's slot with metadata and the browser's empty slot give the same ids", async () => {
+    // What the browser's ids are, rendered alone with the client shape.
+    const clientHtml = await render(e(Layout, null, withMetaSlot(e, React.Fragment, null, e(MenuPage))));
+    const clientId = /id="(menu-[^"]+)"/.exec(clientHtml)?.[1];
+    const { serverId, errors } = await hydrate(
+      e(Layout, null, withMetaSlot(e, React.Fragment, meta, e(MenuPage))),
+      e(Layout, null, withMetaSlot(e, React.Fragment, null, e(MenuPage))),
+    );
+    expect(serverId).toBeDefined();
+    expect(serverId).toBe(clientId);
+    expect(errors).toEqual([]);
+  });
+
+  test("a page without metadata has the same shape", async () => {
+    const { errors } = await hydrate(
+      e(Layout, null, withMetaSlot(e, React.Fragment, null, e(MenuPage))),
+      e(Layout, null, withMetaSlot(e, React.Fragment, null, e(MenuPage))),
+    );
+    expect(errors).toEqual([]);
+  });
+
+  test("hydrating the page without the slot mismatches (the bug)", async () => {
+    const { errors } = await hydrate(
+      e(Layout, null, e(React.Fragment, null, meta, e(MenuPage))),
+      e(Layout, null, e(MenuPage)),
+    );
+    expect(errors.length).toBeGreaterThan(0);
+  });
+});

package/src/ssr-page-tree.ts

@@ -0,0 +1,21 @@
+// The shape of the tree around a route's page, shared by the server render
+// (ssr-runtime.ts) and the browser's hydration (the generated client runtime
+// imports this file as `./page-tree`).
+//
+// React derives `useId` values from the tree's shape, including how many
+// children each element has. The server renders the page's metadata (<title>,
+// <meta>, <link>, which React hoists into <head>) beside the page; the browser
+// never renders those tags. So both sides give the page a fragment with two
+// slots: on the server the first slot holds the metadata, in the browser it
+// holds null. React counts a null slot, so every id inside the page is the
+// same on both sides. Without the slot, every Radix menu, dialog and label id
+// on a page with metadata mismatched on hydration.
+//
+// No imports: the client bundler copies this file next to the runtime.
+
+type CreateElement = (type: any, props: any, ...children: any[]) => any;
+
+/** The page with its metadata slot. `meta` is null in the browser. */
+export function withMetaSlot(createElement: CreateElement, Fragment: any, meta: unknown, page: unknown): any {
+  return createElement(Fragment, null, meta ?? null, page);
+}

package/src/ssr-runtime.ts

@@ -7,6 +7,7 @@
 // the dispatch arm) so projects without SSR routes pay nothing — no
 // react-dom dependency requirement, no startup cost.
 
+import { withMetaSlot } from "./ssr-page-tree";
 import { moduleKey, serverBundle } from "./server-bundle";
 
 // Bun runtime global. This module runs under Bun but is type-checked by
@@ -2561,15 +2562,14 @@ async function tryRenderBoundary(
     );
     boundaryMeta = applyAutoIcons(rel, boundaryMeta);
     const boundaryMetaFragment = renderMetadata(React, boundaryMeta);
-    let tree = React.createElement(Comp, compProps);
-    if (boundaryMetaFragment) {
-      tree = React.createElement(
-        React.Fragment,
-        null,
-        boundaryMetaFragment,
-        tree,
-      );
-    }
+    // The same metadata slot a page gets: the browser hydrates a boundary
+    // with the page's tree shape (ssr-page-tree.ts).
+    let tree = withMetaSlot(
+      React.createElement,
+      React.Fragment,
+      boundaryMetaFragment,
+      React.createElement(Comp, compProps),
+    );
     tree = await buildLayoutTree(cwd, tree, boundaryLayouts, compProps, React);
     await renderBoundaryToClient(
       React,
@@ -3563,11 +3563,10 @@ export async function handleRenderRoute(
     // root: start with the page component as `tree`, then for each
     // layout (innermost first) wrap it as the new tree. Result is
     // the outermost layout containing all nested layouts down to
-    // the page. The metadata fragment is the FIRST child so React hoists
-    // its <title>/<meta> into the <head> a layout renders.
-    let tree: any = metaFragment
-      ? React.createElement(React.Fragment, null, metaFragment, pageLeaf)
-      : pageLeaf;
+    // the page. The metadata is the FIRST child so React hoists its
+    // <title>/<meta> into the <head> a layout renders; the browser renders
+    // the same slot empty (ssr-page-tree.ts), so useId values match.
+    let tree: any = withMetaSlot(React.createElement, React.Fragment, metaFragment, pageLeaf);
     tree = await buildLayoutTree(cwd, tree, msg.layouts, props, React);
     const element = tree;
     // Tracks whether the HTTP head (response_start) has actually gone out. A