@pylonsync/functions 0.22.60 → 0.22.61

package/src/ssr-client-nav-runtime.fixture.ts

@@ -24,11 +24,33 @@ const MANIFEST = {
     "app/fast/page": { file: "fast.js", imports: [], css: [], path: "/fast", navigation: "client" },
     "app/slow/page": { file: "slow.js", imports: [], css: [], path: "/slow" },
     "app/offline/page": { file: "offline.js", imports: [], css: [], path: "/offline" },
+    // Never registered by a test hydrate() call, and their files do not
+    // exist: loading them fails like a file the deploy removed.
+    "app/reports/page": { file: "reports-v1.js", imports: [], css: [], path: "/reports" },
+    "app/quick/page": { file: "quick-v1.js", imports: [], css: [], path: "/quick", navigation: "client" },
   },
   offline: { routes: ["/offline"] },
 };
 
-const LINKS = ["/", "/fast", "/slow", "/offline"];
+/** \`stale-manifest\`: the page runs build v1, and the build manifest it gets
+ *  is build v0's, as an older service worker answers from its cache. */
+const MODE = process.argv[2] ?? "default";
+
+/** Build v0's manifest: other files for the same routes. */
+const STALE_MANIFEST = {
+  ...MANIFEST,
+  routes: Object.fromEntries(
+    Object.entries(MANIFEST.routes).map(([k, v]) => [k, { ...v, file: v.file.replace(/(-v1)?\.js$/, "-v0.js") }]),
+  ),
+  offline: { ...MANIFEST.offline, version: "v0" },
+};
+
+/** The page's build: the home page's __PYLON_DATA__ carries it. */
+const PAGE_BUILD = "v1";
+/** The build the server runs after the deploy. */
+let serverBuild = "v1";
+
+const LINKS = ["/", "/fast", "/slow", "/offline", "/reports", "/quick"];
 
 function Layout({ children }: { children?: React.ReactNode }) {
   return React.createElement(
@@ -65,16 +87,25 @@ const Offline = page("offline");
 
 const fetches: string[] = [];
 const scrolls: number[] = [];
+/** Full page loads (\`location.href = ...\`) the runtime started. */
+const fullLoads: string[] = [];
+/** Calls to @pylonsync/react's moveToLatestBuild, and its answer. */
+const moves: any[] = [];
+let moveResult = "moving";
+/** The server's build as the page's updater last saw it: a recheck asks
+ *  the server; null until then (no check has run). */
+let knownBuild: string | null = null;
 let win: any;
 let rt: any;
 let dir = "";
 
-function pylonData(component: string, pathname: string): string {
+function pylonData(component: string, pathname: string, build = serverBuild): string {
   const data = {
     component,
     layouts: [],
     props: { pathname, url: pathname, params: {}, searchParams: {} },
     ssrData: {},
+    offline: { version: build },
   };
   return `<script id="__PYLON_DATA__" type="application/json">${JSON.stringify(data)}</script>`;
 }
@@ -108,18 +139,29 @@ async function setUp() {
   dir = fs.mkdtempSync(path.join(cacheDir, "pylon-client-nav-"));
   await writeClientRuntimeModules(fs, path, dir);
   // @pylonsync/react is not a dependency of this package: stand in for the
-  // two functions the runtime calls at hydration.
+  // functions the runtime calls.
   const runtimeFile = path.join(dir, "client-runtime.ts");
   fs.writeFileSync(
     runtimeFile,
     fs
       .readFileSync(runtimeFile, "utf8")
-      .replace('from "@pylonsync/react"', 'from "./pylon-react-stub"'),
+      .replaceAll('from "@pylonsync/react"', 'from "./pylon-react-stub"'),
   );
   fs.writeFileSync(
     path.join(dir, "pylon-react-stub.ts"),
-    "export function configureClient() {}\nexport async function registerOfflineWorker() { return null; }\n",
+    "export function configureClient() {}\n" +
+      "export async function registerOfflineWorker() { return null; }\n" +
+      "export function moveToLatestBuild(options) { return globalThis.__moveToLatestBuild(options); }\n",
   );
+  // Answers like AppUpdater.moveToLatestBuild: from the last check, or
+  // from the server on a recheck.
+  (globalThis as any).__moveToLatestBuild = async (options: any) => {
+    moves.push(options);
+    if (options.recheck) knownBuild = serverBuild;
+    if (knownBuild === null) return "offline";
+    if (knownBuild === PAGE_BUILD) return "current";
+    return moveResult;
+  };
   fs.writeFileSync(path.join(dir, "loading-registry.ts"), "export const LOADING_MODULES = {};\n");
 
   win = new Window({ url: "http://localhost/" });
@@ -138,11 +180,22 @@ async function setUp() {
   g.requestAnimationFrame = (cb: any) => setTimeout(() => cb(Date.now()), 0);
   g.cancelAnimationFrame = (id: any) => clearTimeout(id);
   win.scrollTo = (_x: number, y: number) => scrolls.push(y);
+  // Record full page loads instead of letting happy-dom navigate.
+  const hrefDescriptor = Object.getOwnPropertyDescriptor(
+    Object.getPrototypeOf(win.location),
+    "href",
+  )!;
+  Object.defineProperty(win.location, "href", {
+    configurable: true,
+    get: () => hrefDescriptor.get!.call(win.location),
+    set: (value: string) => fullLoads.push(value),
+  });
   const fakeFetch = async (input: any) => {
     const url = typeof input === "string" ? input : input.url;
     fetches.push(url);
     if (url === "/_pylon/build/manifest.json") {
-      return new Response(JSON.stringify(MANIFEST), { status: 200 });
+      const body = MODE === "stale-manifest" ? STALE_MANIFEST : MANIFEST;
+      return new Response(JSON.stringify(body), { status: 200 });
     }
     const pathname = new URL(url, "http://localhost").pathname;
     if (pathname === "/slow") {
@@ -151,6 +204,12 @@ async function setUp() {
         { status: 200 },
       );
     }
+    if (pathname === "/reports") {
+      return new Response(
+        `<!DOCTYPE html><html><head><title>Reports</title></head><body>${pylonData("app/reports/page", pathname)}</body></html>`,
+        { status: 200 },
+      );
+    }
     return new Response("not found", { status: 404 });
   };
   g.fetch = fakeFetch;
@@ -160,7 +219,7 @@ async function setUp() {
   const props = { pathname: "/", url: "/", params: {}, searchParams: {} };
   const html = renderToString(React.createElement(Layout, null, React.createElement(Home, props)));
   const parsed = new win.DOMParser().parseFromString(
-    "<!DOCTYPE html>" + html.replace("</body>", pylonData("app/home/page", "/") + "</body>"),
+    "<!DOCTYPE html>" + html.replace("</body>", pylonData("app/home/page", "/", PAGE_BUILD) + "</body>"),
     "text/html",
   );
   // Remove, then append: happy-dom 20's replaceChild inserts the new root
@@ -245,7 +304,102 @@ async function prefetchTiming() {
   const intent = preloads().length - beforeSave;
   return { sightBeforeIdle, sightAfterIdle, saveDataSight, intent };
 }
-try {
+/** A deploy while the page is open: its build's route files are gone. */
+async function afterDeploy() {
+  const out: Record<string, any> = {};
+  const take = () => {
+    const seen = {
+      moves: moves.splice(0),
+      fullLoads: fullLoads.splice(0),
+      heading: heading() ?? null,
+      pageFetches: pageFetches(),
+    };
+    fetches.length = 0;
+    return seen;
+  };
+  take();
+
+  // Before the deploy, a route entry that fails to load (a bug, not a
+  // deploy) still falls back to one full page load.
+  click("toreports");
+  await settle();
+  out.sameBuildFailure = take();
+
+  serverBuild = "v2";
+  knownBuild = null;
+  // A click on a page route: the server answers with build v2's page. The
+  // page moves to v2 once, through moveToLatestBuild, opening the link;
+  // before the fix this was a full load of the old build, on every click.
+  click("toreports");
+  await settle();
+  out.pageRoute = take();
+
+  // A click on a route that renders on the client, whose entry the deploy
+  // removed: the same move, with no page fetch.
+  knownBuild = null;
+  click("toquick");
+  await settle();
+  out.clientRoute = take();
+
+  // The page's last check already saw the new build: the click moves at
+  // once, with no page fetch and no entry load.
+  knownBuild = "v2";
+  click("toreports");
+  await settle();
+  out.knownAhead = take();
+
+  // Offline: the entry cannot load and the server cannot be asked. The
+  // page keeps its screen; no full load, which would show a kept page.
+  moveResult = "offline";
+  knownBuild = null;
+  serverBuild = null as any;
+  click("toquick");
+  await settle();
+  out.offline = take();
+
+  // A page that already moved and is still on the old build: one full
+  // load, and no loop of moves.
+  moveResult = "blocked";
+  serverBuild = "v2";
+  knownBuild = null;
+  click("toreports");
+  await settle();
+  out.blocked = take();
+  return out;
+}
+
+/** The page of build v1 got build v0's manifest. Before the fix it loaded
+ *  v0's route files (gone, so every click was a full page load). */
+async function staleManifest() {
+  const warnings: string[] = [];
+  const warn = console.warn;
+  console.warn = (...args: any[]) => warnings.push(args.map(String).join(" "));
+  try {
+    await setUp();
+    // The server and the page agree on v1; the page's own worker waits
+    // behind the old one, so the updater moves.
+    knownBuild = null;
+    moveResult = "moving";
+    serverBuild = "v1";
+    (globalThis as any).__moveToLatestBuild = async (options: any) => {
+      moves.push(options);
+      return options.recheck ? "moving" : "offline";
+    };
+    click("toreports");
+    await settle();
+    return {
+      moves: moves.splice(0),
+      fullLoads: fullLoads.splice(0),
+      preloads: preloads(),
+      pageFetches: pageFetches(),
+      warnedAboutManifest: warnings.some((w) => w.includes("build manifest is for build v0")),
+    };
+  } finally {
+    console.warn = warn;
+  }
+}
+
+async function defaultFlow() {
   await setUp();
   report.hydrated = observe();
   click("tofast");
@@ -266,6 +420,12 @@ try {
   await traverse("forward");
   report.forward2 = observe();
   report.prefetch = await prefetchTiming();
+  report.deploy = await afterDeploy();
+}
+
+try {
+  if (MODE === "stale-manifest") report.staleManifest = await staleManifest();
+  else await defaultFlow();
 } finally {
   if (dir) fs.rmSync(dir, { recursive: true, force: true });
 }

package/src/ssr-client-nav-runtime.test.ts

@@ -6,15 +6,22 @@
 //     route) render with no page fetch;
 //   - /slow fetches its page, as before;
 //   - back and forward add no history entries and fetch only /slow;
-//   - every navigation resets the scroll, like a fetched one.
+//   - every navigation resets the scroll, like a fetched one;
+//   - after a deploy, a click moves the page to the new build once instead
+//     of a full page load of the old build per click, and an offline page
+//     keeps its screen;
+//   - a build manifest of another build (an older service worker's cached
+//     copy) is not used.
 
 import { beforeAll, describe, expect, test } from "bun:test";
 import path from "node:path";
 
 let report: Record<string, any> = {};
 
-beforeAll(async () => {
-  const proc = Bun.spawn([process.execPath, path.join(import.meta.dir, "ssr-client-nav-runtime.fixture.ts")], {
+async function runFixture(mode?: string): Promise<Record<string, any>> {
+  const args = [process.execPath, path.join(import.meta.dir, "ssr-client-nav-runtime.fixture.ts")];
+  if (mode) args.push(mode);
+  const proc = Bun.spawn(args, {
     cwd: path.join(import.meta.dir, ".."),
     stdout: "pipe",
     stderr: "pipe",
@@ -23,7 +30,12 @@ beforeAll(async () => {
   await proc.exited;
   const line = out.split("\n").find((l) => l.startsWith("REPORT "));
   if (!line) throw new Error(`fixture printed no report:\n${out}\n${err}`);
-  report = JSON.parse(line.slice("REPORT ".length));
+  return JSON.parse(line.slice("REPORT ".length));
+}
+
+beforeAll(async () => {
+  const [main, stale] = await Promise.all([runFixture(), runFixture("stale-manifest")]);
+  report = { ...main, staleManifest: stale.staleManifest };
 }, 60_000);
 
 describe("instant client navigation", () => {
@@ -77,3 +89,55 @@ describe("instant client navigation", () => {
     expect(intent).toBeGreaterThan(0);
   });
 });
+
+describe("a deploy while the page is open", () => {
+  const early = (url: string) => ({ url, skipIfPendingWrites: true });
+  const recheck = (url: string) => ({ url, recheck: true });
+
+  test("before the deploy, an entry that fails to load still gets one full page load", () => {
+    const { sameBuildFailure } = report.deploy;
+    expect(sameBuildFailure.moves).toEqual([early("/reports"), recheck("/reports")]);
+    expect(sameBuildFailure.fullLoads).toEqual(["/reports"]);
+  });
+
+  test("a page route served by the new build moves the page once, with no full load", () => {
+    const { pageRoute } = report.deploy;
+    expect(pageRoute.pageFetches).toEqual(["/reports"]);
+    expect(pageRoute.moves).toEqual([early("/reports"), recheck("/reports")]);
+    expect(pageRoute.fullLoads).toEqual([]);
+  });
+
+  test("a client route whose entry the deploy removed moves the page, with no page fetch", () => {
+    const { clientRoute } = report.deploy;
+    expect(clientRoute.moves).toEqual([early("/quick"), recheck("/quick")]);
+    expect(clientRoute.pageFetches).toEqual([]);
+    expect(clientRoute.fullLoads).toEqual([]);
+  });
+
+  test("when the last check saw the new build, the click moves at once", () => {
+    const { knownAhead } = report.deploy;
+    expect(knownAhead.moves).toEqual([early("/reports")]);
+    expect(knownAhead.pageFetches).toEqual([]);
+    expect(knownAhead.fullLoads).toEqual([]);
+  });
+
+  test("offline, a route that cannot load keeps the current screen", () => {
+    const { offline } = report.deploy;
+    expect(offline.fullLoads).toEqual([]);
+    expect(offline.heading).toBe("slow /slow");
+  });
+
+  test("a page that already moved and is still on the old build gets one full load, not a loop", () => {
+    const { blocked } = report.deploy;
+    expect(blocked.moves).toEqual([early("/reports"), recheck("/reports")]);
+    expect(blocked.fullLoads).toEqual(["/reports"]);
+  });
+
+  test("another build's manifest is not used: no route files of that build load", () => {
+    const stale = report.staleManifest;
+    expect(stale.warnedAboutManifest).toBe(true);
+    expect(stale.preloads.filter((h: string) => h.includes("-v0"))).toEqual([]);
+    expect(stale.moves).toEqual([early("/reports"), recheck("/reports")]);
+    expect(stale.fullLoads).toEqual([]);
+  });
+});

package/src/ssr-metadata.test.ts

@@ -0,0 +1,251 @@
+// Page metadata in the served HTML.
+//
+// Veritas pages exported `metadata` and the HTML had none of it: the server
+// put the tags inside the React tree beside the page, and the field layout
+// renders a loading screen on the server instead of its children (the
+// member check runs in the browser), so the tags were never rendered. The
+// server now writes the metadata into <head> itself, merges layout metadata
+// under the page's, and replaces the tags a root layout writes in its own
+// <head> instead of adding a second set.
+//
+// ssr-runtime.ts pulls in runtime.ts (the bun runner entrypoint, which runs
+// main() on import), so each render runs in a child process, like
+// ssr-offline-shell.test.ts.
+
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { dropReplacedHeadTags, headTagKeys, mergeMetadata } from "./ssr-runtime";
+
+const SSR_RUNTIME = join(import.meta.dir, "ssr-runtime.ts");
+const PKG_NODE_MODULES = join(import.meta.dir, "..", "node_modules");
+
+function makeApp(files: Record<string, string>): string {
+  const dir = mkdtempSync(join(tmpdir(), "pylon-metadata-"));
+  mkdirSync(join(dir, "app"), { recursive: true });
+  symlinkSync(PKG_NODE_MODULES, join(dir, "node_modules"), "dir");
+  for (const [p, src] of Object.entries(files)) {
+    mkdirSync(join(dir, p, ".."), { recursive: true });
+    writeFileSync(join(dir, p), src);
+  }
+  return dir;
+}
+
+async function render(
+  dir: string,
+  layouts: string[],
+  headers: Record<string, string> = {},
+  component = "app/page",
+): Promise<string> {
+  const msg = {
+    type: "render_route", call_id: "c1", component, layouts,
+    route_path: "/", url: "/", host: "app.example", params: {}, search_params: {},
+    headers: { host: "app.example", ...headers }, cookies: {}, auth: {}, session_present: false,
+  };
+  const probe = `
+import { handleRenderRoute } from ${JSON.stringify(SSR_RUNTIME)};
+const frames = [];
+await handleRenderRoute(${JSON.stringify(msg)}, (m) => frames.push(m));
+console.error("FRAMES " + JSON.stringify(frames));
+setTimeout(() => process.exit(0), 50);
+`;
+  const probePath = join(dir, "probe.ts");
+  writeFileSync(probePath, probe);
+  const proc = Bun.spawn(["bun", "run", probePath], { cwd: dir, env: { ...process.env, PYLON_DEV_MODE: "0" }, stdin: "pipe", stdout: "pipe", stderr: "pipe" });
+  const [out, err] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()]);
+  const code = await proc.exited;
+  const line = err.split("\n").find((l) => l.includes("FRAMES "));
+  if (code !== 0 || !line) throw new Error(`probe failed (exit ${code})\nstdout: ${out}\nstderr: ${err}`);
+  const frames = JSON.parse(line.slice(line.indexOf("FRAMES ") + 7)) as any[];
+  return frames.filter((f) => f.type === "render_chunk").map((f) => Buffer.from(f.data, "base64").toString("utf8")).join("");
+}
+
+
+// A root layout like Veritas's: its own <head> with default link-preview tags.
+const ROOT_LAYOUT = `export default function RootLayout({ children }: any) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <title>Field Sales</title>
+        <meta name="description" content="The field app." />
+        <meta property="og:title" content="Field Sales" />
+        <meta property="og:image" content="https://app.example/og.png" />
+        <meta property="og:image:width" content="1200" />
+        <meta name="twitter:title" content="Field Sales" />
+        <script dangerouslySetInnerHTML={{ __html: 'var t = "<title>kept</title>";' }} />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+`;
+
+// A layout that decides access in the browser: on the server it renders a
+// loading screen, never its children.
+const GATE_LAYOUT = `export default function Gate({ children }: any) {
+  return typeof window === "undefined" ? <p>Loading</p> : children;
+}
+`;
+
+const count = (html: string, re: RegExp) => (html.match(re) ?? []).length;
+// The document up to </head>, without script text (the root layout's script
+// holds a <title> string that is not a tag).
+const headOf = (html: string) =>
+  html.slice(0, html.indexOf("</head>")).replace(/<script\b[\s\S]*?<\/script>/g, "");
+
+describe("page metadata in the HTML", () => {
+  test("reaches <head> when a layout does not render the page, and replaces the root layout's tags", async () => {
+    const dir = makeApp({
+      "app/layout.tsx": ROOT_LAYOUT,
+      "app/gate/layout.tsx": GATE_LAYOUT,
+      "app/page.tsx": `export const metadata = {
+  title: "Home · Field Sales",
+  openGraph: { title: "Home", description: "Today's doors." },
+  twitter: { title: "Home" },
+};
+export default function P() { return <p>page body</p>; }
+`,
+    });
+    const html = await render(dir, ["app/layout", "app/gate/layout"]);
+    expect(html).toContain("Loading");
+    const head = headOf(html);
+    expect(html).not.toContain("page body");
+    expect(count(head, /<title>/g)).toBe(1);
+    expect(head).toContain("<title>Home · Field Sales</title>");
+    expect(count(head, /property="og:title"/g)).toBe(1);
+    expect(head).toContain('property="og:title" content="Home"');
+    expect(head).toContain('property="og:description" content="Today&#x27;s doors."');
+    expect(count(head, /name="twitter:title"/g)).toBe(1);
+    expect(head).toContain('name="twitter:title" content="Home"');
+    // Tags the page does not set stay as the layout wrote them.
+    expect(head).toContain('name="description" content="The field app."');
+    expect(head).toContain('property="og:image" content="https://app.example/og.png"');
+    expect(head).toContain('property="og:image:width" content="1200"');
+    // Text inside a script is not a tag.
+    expect(html).toContain('var t = "<title>kept</title>";');
+  });
+
+  test("a page's og:image replaces the layout's image and its dimensions", async () => {
+    const dir = makeApp({
+      "app/layout.tsx": ROOT_LAYOUT,
+      "app/page.tsx": `export const metadata = { openGraph: { image: "https://app.example/home.png" } };
+export default function P() { return <p>x</p>; }
+`,
+    });
+    const head = headOf(await render(dir, ["app/layout"]));
+    expect(count(head, /property="og:image"/g)).toBe(1);
+    expect(head).toContain('property="og:image" content="https://app.example/home.png"');
+    expect(head).not.toContain("og:image:width");
+    expect(head).toContain("<title>Field Sales</title>");
+  });
+
+  test("a layout's metadata applies to its pages, and the page's values win", async () => {
+    const dir = makeApp({
+      "app/layout.tsx": `export const metadata = { title: "Site", description: "From the layout.", openGraph: { siteName: "Site" } };
+export default function L({ children }: any) { return <html><head><meta charSet="utf-8" /></head><body>{children}</body></html>; }
+`,
+      "app/inner/layout.tsx": `export async function generateMetadata() { return { robots: "noindex" }; }
+export default function L({ children }: any) { return children; }
+`,
+      "app/page.tsx": `export const metadata = { title: "Page", openGraph: { title: "Page OG" } };
+export default function P() { return <p>x</p>; }
+`,
+    });
+    const head = headOf(await render(dir, ["app/layout", "app/inner/layout"]));
+    expect(count(head, /<title>/g)).toBe(1);
+    expect(head).toContain("<title>Page</title>");
+    expect(head).toContain('name="description" content="From the layout."');
+    expect(head).toContain('name="robots" content="noindex"');
+    expect(head).toContain('property="og:site_name" content="Site"');
+    expect(head).toContain('property="og:title" content="Page OG"');
+  });
+
+  test("an offline shell request carries the metadata", async () => {
+    const dir = makeApp({
+      "app/layout.tsx": ROOT_LAYOUT,
+      "app/page.tsx": `export const metadata = { title: "Home · Field Sales" };
+export default function P() { return <p>x</p>; }
+`,
+    });
+    const head = headOf(await render(dir, ["app/layout"], { "x-pylon-offline-shell": "1" }));
+    expect(count(head, /<title>/g)).toBe(1);
+    expect(head).toContain("<title>Home · Field Sales</title>");
+  });
+
+  test("a navigation response carries the page's title, or the layout's when the page has none", async () => {
+    const titled = makeApp({
+      "app/layout.tsx": ROOT_LAYOUT,
+      "app/page.tsx": `export const metadata = { title: "Jobs" };
+export default function P() { return <p>x</p>; }
+`,
+    });
+    const nav = await render(titled, ["app/layout"], { "x-pylon-nav": "1" });
+    expect(count(nav, /<title>/g)).toBe(1);
+    expect(nav).toContain("<title>Jobs</title>");
+
+    const untitled = makeApp({
+      "app/layout.tsx": ROOT_LAYOUT,
+      "app/page.tsx": `export default function P() { return <p>x</p>; }`,
+    });
+    const nav2 = await render(untitled, ["app/layout"], { "x-pylon-nav": "1" });
+    expect(count(nav2, /<title>/g)).toBe(1);
+    expect(nav2).toContain("<title>Field Sales</title>");
+  });
+
+  test("a not-found boundary's metadata replaces the layout's title", async () => {
+    const dir = makeApp({
+      "app/layout.tsx": ROOT_LAYOUT,
+      "app/not-found.tsx": `export const metadata = { title: "Not found" };
+export default function NF() { return <p>missing</p>; }
+`,
+    });
+    // The host renders `app/not-found` by name for an unmatched URL.
+    const head = headOf(await render(dir, ["app/layout"], {}, "app/not-found"));
+    expect(count(head, /<title>/g)).toBe(1);
+    expect(head).toContain("<title>Not found</title>");
+
+    // A page that calls notFound() renders the same boundary.
+    writeFileSync(
+      join(dir, "app", "page.tsx"),
+      `export default function P(props: any) { props.response.notFound(); }`,
+    );
+    const caught = headOf(await render(dir, ["app/layout"]));
+    expect(count(caught, /<title>/g)).toBe(1);
+    expect(caught).toContain("<title>Not found</title>");
+    expect(caught).toContain('property="og:title" content="Field Sales"');
+  });
+});
+
+describe("dropReplacedHeadTags", () => {
+  test("drops only the tags the metadata sets, by title, name, property and canonical", () => {
+    const head =
+      '<head><title>Old</title><meta name="description" content="a > b"/>' +
+      '<meta property="og:image" content="x"/><meta property="og:image:alt" content="y"/>' +
+      '<meta name="viewport" content="w"/><link rel="canonical" href="/old"/>' +
+      '<link rel="stylesheet" href="/s.css"/><style>title{}</style>';
+    const keys = headTagKeys(
+      '<title>New</title><meta data-pylon-meta="" name="description" content="n"/>' +
+        '<meta data-pylon-meta="" property="og:image" content="z"/><link data-pylon-meta="" rel="canonical" href="/new"/>',
+    );
+    expect(dropReplacedHeadTags(head, keys)).toBe(
+      '<head><meta name="viewport" content="w"/><link rel="stylesheet" href="/s.css"/><style>title{}</style>',
+    );
+  });
+});
+
+describe("mergeMetadata", () => {
+  test("merges openGraph field by field; a new image drops the old image's fields", () => {
+    expect(
+      mergeMetadata(
+        { title: "A", openGraph: { siteName: "S", image: "/a.png", imageWidth: 1200 }, twitter: { image: "/a.png", imageAlt: "a" } },
+        { title: "B", openGraph: { image: "/b.png" }, twitter: { image: "/b.png" } },
+      ),
+    ).toEqual({
+      title: "B",
+      openGraph: { siteName: "S", image: "/b.png" },
+      twitter: { image: "/b.png" },
+    });
+  });
+});

package/src/ssr-page-tree.ts

@@ -3,19 +3,16 @@
 // 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.
+// children each element has. Both sides give the page a fragment with two
+// slots, the first one null. The server once put the page's metadata there;
+// it now writes the metadata into <head> as HTML, outside the tree. The slot
+// stays so the tree keeps the shape that built clients hydrate against.
 //
 // 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. */
+/** The page with its metadata slot. Both sides pass null for `meta`. */
 export function withMetaSlot(createElement: CreateElement, Fragment: any, meta: unknown, page: unknown): any {
   return createElement(Fragment, null, meta ?? null, page);
 }