@pylonsync/functions 0.4.10 → 0.4.12

package/dist/ssr-client-boundary.d.ts

@@ -14,6 +14,16 @@ export type BoundaryFile = "not-found" | "error" | "loading";
  * the shared chunk instead.
  */
 export declare function nearestBoundaryComponent(component: string, fileName: BoundaryFile, routeKeys: Iterable<string>): string | null;
+/**
+ * The URL-space directory a module sits in: its parent path with `(group)`
+ * segments removed, since a group contributes no URL segment.
+ *
+ * `web/app/(marketing)/pricing/page` → `web/app/pricing`, and
+ * `web/app/(marketing)/not-found` → `web/app`. That is what makes a group's
+ * boundary resolve for `/` — matching the server, which walks the real
+ * directories but treats group dirs as transparent the same way.
+ */
+export declare function boundaryScope(componentPath: string): string;
 /** Runtime internals the boundary needs, injected so the module stays
  *  browser-safe AND unit-testable. */
 export interface BoundaryDeps {

package/dist/ssr-nav-cache.d.ts

@@ -0,0 +1,26 @@
+export interface NavPayloadCacheDeps {
+    /** Fetch a page, resolving to its HTML or null when it shouldn't be reused. */
+    fetchPage: (target: string) => Promise<string | null>;
+    /** Injected so tests drive expiry without sleeping. */
+    now: () => number;
+    /** Long enough to cover hover-to-click, short enough that nobody reads a
+     *  page rendered from data this old. */
+    ttlMs?: number;
+    /** Cap on retained payloads; the oldest is evicted first. Pages are whole
+     *  HTML documents, so this bounds memory on a link-dense page. */
+    max?: number;
+}
+export interface NavPayloadCache {
+    /** Warm `target`, unless a fresh entry is already present or in flight. */
+    prefetch(target: string): void;
+    /** Hand over `target`'s payload, or null. Single-use: a prefetch
+     *  accelerates the NEXT click, and holding it past that would serve
+     *  navigations from an increasingly stale render. */
+    take(target: string): Promise<string | null> | null;
+    /** Drop everything — called when a navigation commits, since entries were
+     *  rendered against the page the user just left. */
+    clear(): void;
+    /** Retained entry count (tests + diagnostics). */
+    size(): number;
+}
+export declare function createNavPayloadCache(deps: NavPayloadCacheDeps): NavPayloadCache;

package/dist/ssr-route-match.d.ts

@@ -26,18 +26,27 @@ export declare function matchRoute(manifest: MatchableManifest | null | undefine
 export interface PrefetchTargets {
     /** The destination route's own entry chunk, or "" when no page route matches. */
     file: string;
-    /** Shared chunks to warm alongside it. */
+    /** Chunks to warm alongside it. */
     imports: string[];
 }
 /**
  * The chunks a click on `pathname` will need before anything can render: the
- * destination route's entry, plus the shared chunks (React, the client
- * runtime, common layouts) that every route pulls in.
+ * destination route's entry, plus the chunks (React, the client runtime,
+ * common layouts) it pulls in.
  *
  * Warming the page payload alone leaves the entry chunk to be fetched after
  * the click, and the route cannot render until it lands — so the prefetch
- * covers only the half that was already fast. An href matching no page route
- * (an API path, a route this build doesn't serve) still yields the shared set;
- * `file` is "" and the caller skips it.
+ * covers only the half that was already fast.
+ *
+ * Size is deliberately NOT a factor. Build output is content-hashed and served
+ * immutable, so warming a heavy route costs its bytes once per browser and
+ * makes every later visit to it instant; skipping it would trade a permanent
+ * win for a one-time saving, and would skip exactly the routes slowest to
+ * fetch on demand. The warm is deferred to the load event, so those bytes
+ * never compete with the current page's own render.
+ *
+ * An href matching no page route (an API path, a route this build doesn't
+ * serve) yields the union of every route's chunks: no destination is known,
+ * but those are needed by any navigation.
  */
 export declare function prefetchTargets(manifest: MatchableManifest | null | undefined, pathname: string): PrefetchTargets;

package/dist/ssr-runtime.d.ts

@@ -303,6 +303,12 @@ export interface SsrMetadata {
 export declare function renderMetadata(React: any, m: SsrMetadata | undefined): any;
 /** Import a project-relative module, trying each common extension. */
 export declare function importModule(cwd: string, relPath: string): Promise<any>;
+/**
+ * `findBoundary` with its filesystem and root injected, so the walk is
+ * testable against a fixture without `chdir` — which races every other test
+ * in the process.
+ */
+export declare function findBoundaryIn(fs: any, path: any, cwd: string, componentPath: string, fileName: string): string | null;
 /** Pure origin resolution (exported for tests).
  *
  *  SECURITY: the request `Host` (and `X-Forwarded-Proto`) is attacker-
@@ -409,7 +415,30 @@ export declare function buildHydrationTail(args: {
     bucketAuth?: {
         signedIn: boolean;
     };
+    /** Client-side NAVIGATION payload: emit the `__PYLON_DATA__` blob and
+     *  nothing else. The client already has the runtime and resolves the route
+     *  entry from the build manifest, so the entry `<script>`, the preload tags
+     *  and the dev-reload snippet are all dead weight on a navigation. Shares
+     *  this function — and therefore its props strip — rather than rebuilding
+     *  the payload somewhere the security-relevant parts could drift. */
+    dataOnly?: boolean;
 }): string;
+/**
+ * Is this render answering a client-side navigation rather than a document
+ * load? The client runtime sets `X-Pylon-Nav: 1`; the Rust host reads the same
+ * header to key the ISR cache, so the two always agree on which shape a URL
+ * is being asked for.
+ */
+export declare function isNavRequest(headers: Record<string, unknown> | undefined): boolean;
+/**
+ * Render a detached element (the metadata fragment) to an HTML string.
+ *
+ * A navigation response carries the page's `<title>`/`<meta>`/`<link>` so the
+ * client can swap them, but not the page body — which the client re-renders
+ * from `__PYLON_DATA__` anyway. Rendering the fragment on its own is what
+ * lets the body be dropped without losing the head.
+ */
+export declare function renderElementToString(renderToReadableStream: any, element: any): Promise<string>;
 /**
  * A short, non-reversible correlation id for an error — surfaced to the
  * client error boundary as `error.digest` (matching server logs) WITHOUT

package/package.json

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

package/src/ssr-boundary-groups.test.ts

@@ -0,0 +1,183 @@
+// The server's boundary walk must agree with the client's on route groups.
+//
+// Regression: `app/(marketing)/not-found.tsx` served unmatched URLs — the host
+// matches those on the manifest's URL path, where a group adds no segment —
+// but NOT a notFound() thrown by a page, which walked real directories and so
+// never crossed out of the page's own subtree. One class of 404 got the app's
+// boundary and the other got the built-in, while ROUTE_PATH_DUPLICATE blocked
+// keeping a root copy alongside the group's.
+//
+// These drive the SERVER walk (findBoundaryIn) over a real fixture tree and
+// assert the same answers the client's nearestBoundaryComponent gives for the
+// equivalent key set — the two diverging is what caused the bug.
+
+import { afterEach, describe, expect, test } from "bun:test";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+import { findBoundaryIn } from "./ssr-runtime";
+import { nearestBoundaryComponent } from "./ssr-client-boundary";
+
+let tmp: string | null = null;
+
+afterEach(() => {
+  if (tmp) {
+    try {
+      fs.rmSync(tmp, { recursive: true, force: true });
+    } catch {
+      /* best effort */
+    }
+    tmp = null;
+  }
+});
+
+/** Create a tree of empty module files and return its root. */
+function tree(files: string[]): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pylon-boundary-"));
+  for (const f of files) {
+    const full = path.join(dir, f);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, "export default function X(){return null}\n", "utf8");
+  }
+  tmp = dir;
+  return dir;
+}
+
+/** Module paths (no extension) for the client-side equivalent. */
+const keysOf = (files: string[]) => files.map((f) => f.replace(/\.tsx$/, ""));
+
+describe("server boundary walk treats route groups as transparent", () => {
+  test("a group's not-found covers a page outside the group", () => {
+    const files = ["app/(marketing)/not-found.tsx", "app/gone/page.tsx"];
+    const root = tree(files);
+    expect(findBoundaryIn(fs, path, root, "app/gone/page", "not-found")).toBe(
+      "app/(marketing)/not-found",
+    );
+    // ...and the client agrees, which is the property that broke.
+    expect(
+      nearestBoundaryComponent("app/gone/page", "not-found", keysOf(files)),
+    ).toBe("app/(marketing)/not-found");
+  });
+
+  test("nested groups resolve too", () => {
+    const files = ["app/(a)/(b)/not-found.tsx", "app/gone/page.tsx"];
+    const root = tree(files);
+    expect(findBoundaryIn(fs, path, root, "app/gone/page", "not-found")).toBe(
+      "app/(a)/(b)/not-found",
+    );
+    expect(
+      nearestBoundaryComponent("app/gone/page", "not-found", keysOf(files)),
+    ).toBe("app/(a)/(b)/not-found");
+  });
+
+  test("a real directory's own boundary wins over a group beside it", () => {
+    const files = [
+      "app/not-found.tsx",
+      "app/(marketing)/not-found.tsx",
+      "app/gone/page.tsx",
+    ];
+    const root = tree(files);
+    // (An app can't actually ship both — both claim "/" and the duplicate
+    // check rejects it — but the walk must still be deterministic.)
+    expect(findBoundaryIn(fs, path, root, "app/gone/page", "not-found")).toBe(
+      "app/not-found",
+    );
+  });
+
+  test("a nearer boundary still beats a group one higher up", () => {
+    const files = [
+      "app/(marketing)/not-found.tsx",
+      "app/dashboard/not-found.tsx",
+      "app/dashboard/settings/page.tsx",
+    ];
+    const root = tree(files);
+    expect(
+      findBoundaryIn(fs, path, root, "app/dashboard/settings/page", "not-found"),
+    ).toBe("app/dashboard/not-found");
+    expect(
+      nearestBoundaryComponent(
+        "app/dashboard/settings/page",
+        "not-found",
+        keysOf(files),
+      ),
+    ).toBe("app/dashboard/not-found");
+  });
+
+  test("a group boundary in a deeper URL scope does not leak upward", () => {
+    // app/(marketing)/pricing/not-found is at "/pricing"; a page at
+    // "/dashboard" must not get it.
+    const files = [
+      "app/(marketing)/pricing/not-found.tsx",
+      "app/dashboard/page.tsx",
+    ];
+    const root = tree(files);
+    expect(
+      findBoundaryIn(fs, path, root, "app/dashboard/page", "not-found"),
+    ).toBeNull();
+    expect(
+      nearestBoundaryComponent("app/dashboard/page", "not-found", keysOf(files)),
+    ).toBeNull();
+  });
+
+  test("a boundary inside a group still covers that group's own pages", () => {
+    const files = [
+      "app/(marketing)/not-found.tsx",
+      "app/(marketing)/pricing/page.tsx",
+    ];
+    const root = tree(files);
+    expect(
+      findBoundaryIn(fs, path, root, "app/(marketing)/pricing/page", "not-found"),
+    ).toBe("app/(marketing)/not-found");
+  });
+
+  test("error.tsx and loading.tsx follow the same rule", () => {
+    const files = [
+      "app/(shell)/error.tsx",
+      "app/(shell)/loading.tsx",
+      "app/reports/page.tsx",
+    ];
+    const root = tree(files);
+    expect(findBoundaryIn(fs, path, root, "app/reports/page", "error")).toBe(
+      "app/(shell)/error",
+    );
+    expect(findBoundaryIn(fs, path, root, "app/reports/page", "loading")).toBe(
+      "app/(shell)/loading",
+    );
+  });
+
+  test("an app with no boundary anywhere still resolves to null", () => {
+    const root = tree(["app/page.tsx"]);
+    expect(findBoundaryIn(fs, path, root, "app/page", "not-found")).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Boundary metadata.
+//
+// Regression: `export const metadata` on not-found.tsx / error.tsx was ignored
+// on the catch path (a page calling notFound(), or throwing). The rendered
+// head had no <title> at all — and because the framework's built-in 404 body
+// supplies one, taking over the boundary LOST the title rather than replacing
+// it, leaving the tab showing the raw URL.
+// ---------------------------------------------------------------------------
+
+import { renderMetadata } from "./ssr-runtime";
+
+describe("renderMetadata drives boundary heads too", () => {
+  test("emits a title element a boundary can hoist", () => {
+    const React = require("react");
+    const frag = renderMetadata(React, { title: "Missing", description: "d" });
+    expect(frag).toBeTruthy();
+    const kids = React.Children.toArray(frag.props.children);
+    const types = kids.map((k: any) => k.type);
+    expect(types).toContain("title");
+    expect(types).toContain("meta");
+  });
+
+  test("no metadata yields nothing to wrap", () => {
+    // The boundary tree must be left alone rather than wrapped in an empty
+    // fragment, so hydration matches what the bundler baked for it.
+    expect(renderMetadata(require("react"), undefined)).toBeNull();
+  });
+});

package/src/ssr-client-boundary.ts

@@ -42,16 +42,38 @@ export function nearestBoundaryComponent(
   fileName: BoundaryFile,
   routeKeys: Iterable<string>,
 ): string | null {
-  const keys = routeKeys instanceof Set ? routeKeys : new Set(routeKeys);
-  let dir = String(component);
-  dir = dir.includes("/") ? dir.slice(0, dir.lastIndexOf("/")) : "";
-  while (dir) {
-    const key = `${dir}/${fileName}`;
-    if (keys.has(key)) return key;
-    const slash = dir.lastIndexOf("/");
-    dir = slash >= 0 ? dir.slice(0, slash) : "";
+  const target = boundaryScope(component);
+  let best: { key: string; depth: number } | null = null;
+  for (const key of routeKeys) {
+    if (!key.endsWith(`/${fileName}`)) continue;
+    const scope = boundaryScope(key);
+    // Same URL scope, or an ancestor of it.
+    if (scope !== target && !target.startsWith(`${scope}/`)) continue;
+    const depth = scope === "" ? 0 : scope.split("/").length;
+    // Nearest ancestor wins; ties (a directory's own file vs one in a group
+    // beside it) resolve by key order so the answer is deterministic.
+    if (!best || depth > best.depth || (depth === best.depth && key < best.key)) {
+      best = { key, depth };
+    }
   }
-  return null;
+  return best ? best.key : null;
+}
+
+/**
+ * The URL-space directory a module sits in: its parent path with `(group)`
+ * segments removed, since a group contributes no URL segment.
+ *
+ * `web/app/(marketing)/pricing/page` → `web/app/pricing`, and
+ * `web/app/(marketing)/not-found` → `web/app`. That is what makes a group's
+ * boundary resolve for `/` — matching the server, which walks the real
+ * directories but treats group dirs as transparent the same way.
+ */
+export function boundaryScope(componentPath: string): string {
+  const parts = String(componentPath).replace(/\\/g, "/").split("/");
+  parts.pop(); // the module's own basename
+  return parts
+    .filter((p) => !(p.startsWith("(") && p.endsWith(")")))
+    .join("/");
 }
 
 /** Runtime internals the boundary needs, injected so the module stays

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

@@ -29,7 +29,10 @@ import {
   generateLoadingRegistry,
   type PylonBundleManifest,
 } from "./ssr-client-bundler";
-import { nearestBoundaryComponent } from "./ssr-client-boundary";
+import {
+  boundaryScope,
+  nearestBoundaryComponent,
+} from "./ssr-client-boundary";
 
 // State that needs cleanup between tests.
 let originalCwd: string | null = null;
@@ -650,3 +653,81 @@ describe("loading.tsx is wired into the client build", () => {
     ).toBe(true);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Route groups and boundary resolution.
+//
+// Regression: a `not-found.tsx` inside a route group served unmatched URLs
+// (the host matches those on the manifest's URL path, where a group adds no
+// segment, so it sits at "/") but NOT a notFound() thrown by a page (which
+// walked real directories and never crossed out of the page's own subtree).
+// So a group boundary silently covered one class of 404 and not the other,
+// while ROUTE_PATH_DUPLICATE blocked keeping a root copy alongside it.
+// ---------------------------------------------------------------------------
+
+describe("boundaryScope", () => {
+  test("drops group segments, keeps real ones", () => {
+    expect(boundaryScope("web/app/(marketing)/pricing/page")).toBe("web/app/pricing");
+    expect(boundaryScope("web/app/(marketing)/not-found")).toBe("web/app");
+    expect(boundaryScope("app/not-found")).toBe("app");
+  });
+
+  test("handles nested groups", () => {
+    expect(boundaryScope("app/(a)/(b)/not-found")).toBe("app");
+  });
+});
+
+describe("nearestBoundaryComponent across route groups", () => {
+  test("a group's boundary covers a page outside the group", () => {
+    // Both are at URL "/", so the group copy IS the root boundary.
+    expect(
+      nearestBoundaryComponent(
+        "app/gone/page",
+        "not-found",
+        new Set(["app/(marketing)/not-found", "app/gone/page"]),
+      ),
+    ).toBe("app/(marketing)/not-found");
+  });
+
+  test("a nested group's boundary resolves the same way", () => {
+    expect(
+      nearestBoundaryComponent(
+        "app/gone/page",
+        "not-found",
+        new Set(["app/(a)/(b)/not-found"]),
+      ),
+    ).toBe("app/(a)/(b)/not-found");
+  });
+
+  test("a nearer real boundary still beats a group one higher up", () => {
+    expect(
+      nearestBoundaryComponent(
+        "app/dashboard/settings/page",
+        "not-found",
+        new Set(["app/(marketing)/not-found", "app/dashboard/not-found"]),
+      ),
+    ).toBe("app/dashboard/not-found");
+  });
+
+  test("a group boundary does not leak into a deeper URL scope", () => {
+    // app/(marketing)/pricing/not-found is at "/pricing" — it must not answer
+    // for a page at "/dashboard".
+    expect(
+      nearestBoundaryComponent(
+        "app/dashboard/page",
+        "not-found",
+        new Set(["app/(marketing)/pricing/not-found"]),
+      ),
+    ).toBeNull();
+  });
+
+  test("a boundary inside a group still covers that group's own pages", () => {
+    expect(
+      nearestBoundaryComponent(
+        "app/(marketing)/pricing/page",
+        "not-found",
+        new Set(["app/(marketing)/not-found"]),
+      ),
+    ).toBe("app/(marketing)/not-found");
+  });
+});

package/src/ssr-client-bundler.ts

@@ -332,6 +332,7 @@ import { createElement } from "react";
 import { hydrateRoot } from "react-dom/client";
 import { createPylonBoundary, nearestBoundaryComponent } from "./client-boundary";
 import { LOADING_MODULES } from "./loading-registry";
+import { createNavPayloadCache } from "./nav-cache";
 import { matchRoute, prefetchTargets } from "./route-match";
 
 const routeCache = Object.create(null);
@@ -597,16 +598,38 @@ function whenLoaded(fn) {
   window.addEventListener("load", fn, { once: true });
 }
 
-async function prefetch(href) {
-  // HTML prefetch — primes the SSR response cache.
+// Marks a request as a client-side NAVIGATION rather than a document load.
+// The server answers with the head metadata + __PYLON_DATA__ and skips the
+// page markup, which this runtime re-renders from that data anyway. The host
+// keys its render cache on the same header, so the two shapes never share an
+// entry. Prefetch and navigate MUST send identical headers, or the prefetched
+// response is the wrong shape for the click that consumes it.
+const NAV_REQUEST_HEADERS = { Accept: "text/html", "X-Pylon-Nav": "1" };
+
+// Payloads warmed by a hover, consumed by the click that follows. See
+// ./nav-cache for why this is in memory rather than an HTTP-level prefetch.
+const navPayloads = createNavPayloadCache({
+  now: () => Date.now(),
+  fetchPage: (target) =>
+    fetch(target, {
+      credentials: "same-origin",
+      headers: NAV_REQUEST_HEADERS,
+    }).then((res) => {
+      // A redirect means the URL navigate() would commit isn't the one that
+      // answered; let the real navigation resolve that itself.
+      if (!res.ok || res.redirected) return null;
+      return res.text();
+    }),
+});
+
+async function prefetch(href, opts) {
   const url = new URL(href, location.href);
   if (url.origin !== location.origin) return;
-  if (!document.querySelector('link[rel="prefetch"][href="' + url.pathname + '"]')) {
-    const html = document.createElement("link");
-    html.rel = "prefetch";
-    html.as = "document";
-    html.href = url.pathname + url.search;
-    document.head.appendChild(html);
+  // The page payload, but ONLY on a real intent signal (hover / touch). It
+  // costs a full SSR render, so warming a screenful of links on sight would
+  // spend a dozen renders per page load to save one.
+  if (opts && opts.document) {
+    navPayloads.prefetch(url.pathname + url.search);
   }
   const manifest = await loadManifest();
   if (!manifest) return;
@@ -643,6 +666,11 @@ async function loadRouteEntry(component) {
 export function hydrate(component, Page, Layouts) {
   // Always cache the route for nav.
   routeCache[component] = { Page, Layouts };
+  // Start the manifest fetch NOW rather than on first use. Nothing can resolve
+  // a route without it — the first <Link> reaching the viewport warms its
+  // chunks only after it lands — so leaving it lazy put a round trip in front
+  // of all prefetching. In flight from here, it resolves during hydration.
+  void loadManifest();
   const data = readPylonData();
   // First hydrate: the entry's component MATCHES the SSR'd page.
   // Establish the root + install the click + popstate handlers
@@ -851,15 +879,21 @@ async function navigate(href, opts) {
   // ---- Real fetch + render -----------------------------------------------
   let html;
   try {
-    const res = await fetch(target, {
-      credentials: "same-origin",
-      headers: { Accept: "text/html" },
-    });
-    if (!res.ok) {
-      fullLoad();
-      return;
+    // A hover-prefetch usually has this in hand, or in flight — either way the
+    // click joins it instead of opening a second request for the same page.
+    const prefetched = navPayloads.take(target);
+    html = prefetched ? await prefetched : null;
+    if (html == null) {
+      const res = await fetch(target, {
+        credentials: "same-origin",
+        headers: NAV_REQUEST_HEADERS,
+      });
+      if (!res.ok) {
+        fullLoad();
+        return;
+      }
+      html = await res.text();
     }
-    html = await res.text();
   } catch {
     fullLoad();
     return;
@@ -912,6 +946,10 @@ async function navigate(href, opts) {
   // next macrotask once the commit has settled with no error.
   pendingNav = target;
   currentComponent = data.component;
+  // Drop every other prefetched payload once a navigation commits: they were
+  // rendered against the previous page's state, and whatever the user does
+  // here can invalidate them. Hovering on the new page re-warms in one request.
+  navPayloads.clear();
   activeRoot.render(tree);
   setTimeout(() => {
     if (pendingNav === target) pendingNav = null;
@@ -1407,6 +1445,15 @@ async function _doBuildInner(
       "utf8",
     );
 
+    // Same pattern for the prefetch payload cache — the runtime imports it as
+    // `./nav-cache`; its source of truth is ssr-nav-cache.ts, unit-tested
+    // directly (expiry, eviction, single-use).
+    fs.writeFileSync(
+      path.join(stageDir, "nav-cache.ts"),
+      fs.readFileSync(path.join(here, "ssr-nav-cache.ts"), "utf8"),
+      "utf8",
+    );
+
     // The app's loading.tsx modules, gathered into one module the runtime
     // imports statically (`./loading-registry`) so a pending navigation can
     // paint a skeleton without fetching anything. Always written — an app with

package/src/ssr-nav-cache.test.ts

@@ -0,0 +1,146 @@
+// Regression tests for the client-navigation payload cache.
+//
+// The bug this exists to fix: `<Link>` prefetched pages with a
+// `<link rel="prefetch">` that could never be reused. Measured on a real app,
+// the same URL was fetched twice — 16742 bytes both times, full transferSize
+// on the second — because SSR pages are sent "private, no-store" and an
+// as="document" prefetch only feeds real navigations, not fetch(). So each
+// prefetch was a full server render, thrown away, and the click still paid.
+
+import { describe, expect, it } from "bun:test";
+import { createNavPayloadCache } from "./ssr-nav-cache";
+
+/** A cache with a controllable clock and a fetch that records its calls. */
+function harness(opts: { ttlMs?: number; max?: number } = {}) {
+  let clock = 1000;
+  const calls: string[] = [];
+  let resolveNext: ((v: string | null) => void) | null = null;
+  const cache = createNavPayloadCache({
+    now: () => clock,
+    ttlMs: opts.ttlMs,
+    max: opts.max,
+    fetchPage: (target) => {
+      calls.push(target);
+      return new Promise<string | null>((res) => {
+        resolveNext = res;
+        // Default: resolve immediately on the microtask queue.
+        queueMicrotask(() => res(`<html>${target}</html>`));
+      });
+    },
+  });
+  return {
+    cache,
+    calls,
+    advance: (ms: number) => {
+      clock += ms;
+    },
+    settleWith: (v: string | null) => resolveNext?.(v),
+  };
+}
+
+describe("nav payload cache", () => {
+  it("hands the prefetched payload to the click", async () => {
+    const h = harness();
+    h.cache.prefetch("/a");
+    const taken = h.cache.take("/a");
+    expect(taken).not.toBeNull();
+    expect(await taken!).toBe("<html>/a</html>");
+    // The whole point: the click opened no request of its own.
+    expect(h.calls).toEqual(["/a"]);
+  });
+
+  it("does not re-fetch a target already in flight", () => {
+    const h = harness();
+    h.cache.prefetch("/a");
+    h.cache.prefetch("/a");
+    h.cache.prefetch("/a");
+    expect(h.calls).toEqual(["/a"]);
+  });
+
+  it("lets a click join a prefetch that hasn't landed yet", async () => {
+    // Hover-to-click is usually shorter than the render, so this is the
+    // common path, not an edge case.
+    const h = harness();
+    h.cache.prefetch("/slow");
+    const taken = h.cache.take("/slow");
+    h.settleWith("<html>late</html>");
+    expect(await taken!).toBe("<html>late</html>");
+    expect(h.calls).toEqual(["/slow"]);
+  });
+
+  it("is single-use, so a second navigation re-renders", () => {
+    const h = harness();
+    h.cache.prefetch("/a");
+    expect(h.cache.take("/a")).not.toBeNull();
+    expect(h.cache.take("/a")).toBeNull();
+  });
+
+  it("refuses a payload past its TTL", () => {
+    const h = harness({ ttlMs: 15000 });
+    h.cache.prefetch("/a");
+    h.advance(15000);
+    expect(h.cache.take("/a")).toBeNull();
+  });
+
+  it("still serves a payload just inside its TTL", async () => {
+    const h = harness({ ttlMs: 15000 });
+    h.cache.prefetch("/a");
+    h.advance(14999);
+    expect(await h.cache.take("/a")!).toBe("<html>/a</html>");
+  });
+
+  it("re-warms an expired target instead of holding the stale one", async () => {
+    const h = harness({ ttlMs: 100 });
+    h.cache.prefetch("/a");
+    h.advance(200);
+    h.cache.prefetch("/a");
+    expect(h.calls).toEqual(["/a", "/a"]);
+    expect(await h.cache.take("/a")!).toBe("<html>/a</html>");
+  });
+
+  it("evicts the oldest entry at the cap", () => {
+    const h = harness({ max: 2 });
+    h.cache.prefetch("/a");
+    h.cache.prefetch("/b");
+    h.cache.prefetch("/c");
+    expect(h.cache.size()).toBe(2);
+    expect(h.cache.take("/a")).toBeNull();
+    expect(h.cache.take("/c")).not.toBeNull();
+  });
+
+  it("drops everything when a navigation commits", () => {
+    // Entries were rendered against the page the user just left.
+    const h = harness();
+    h.cache.prefetch("/a");
+    h.cache.prefetch("/b");
+    h.cache.clear();
+    expect(h.cache.size()).toBe(0);
+    expect(h.cache.take("/a")).toBeNull();
+  });
+
+  it("yields null when the fetch fails, so the click refetches", async () => {
+    const calls: string[] = [];
+    const cache = createNavPayloadCache({
+      now: () => 0,
+      fetchPage: (t) => {
+        calls.push(t);
+        return Promise.reject(new Error("offline"));
+      },
+    });
+    cache.prefetch("/a");
+    // A rejection must not escape as an unhandled rejection when nobody clicks.
+    expect(await cache.take("/a")!).toBeNull();
+    expect(calls).toEqual(["/a"]);
+  });
+
+  it("caches nothing for a response the fetch rejected as unusable", async () => {
+    // fetchPage returns null for a non-200 or a redirect — the URL that
+    // answered isn't the one navigate() would commit.
+    const cache = createNavPayloadCache({
+      now: () => 0,
+      fetchPage: () => Promise.resolve(null),
+    });
+    cache.prefetch("/a");
+    expect(await cache.take("/a")!).toBeNull();
+  });
+});

package/src/ssr-nav-cache.ts

@@ -0,0 +1,97 @@
+// Prefetched page payloads for client-side navigation.
+//
+// `<Link>` warms a destination on hover; the click then consumes what the
+// hover fetched instead of opening its own request. Before this existed the
+// prefetch was a `<link rel="prefetch">` that could never be reused — SSR
+// pages are sent "private, no-store", so nothing was storable, and an
+// `as="document"` prefetch only feeds real navigations anyway, not `fetch()`.
+// Every prefetch was therefore a full server render, executed and discarded,
+// and the click still paid full price.
+//
+// So the cache lives HERE, in memory, for the length of the tab: honoring
+// no-store means never handing the response to a disk cache, and it means a
+// reload always re-renders.
+//
+// Kept in its own module (not inlined in CLIENT_RUNTIME_SOURCE) so its
+// expiry, eviction and single-use rules are unit-testable — the same reason
+// client-boundary and route-match were pulled out. The bundler stages a copy
+// next to the generated runtime, which imports it as "./nav-cache".
+
+export interface NavPayloadCacheDeps {
+  /** Fetch a page, resolving to its HTML or null when it shouldn't be reused. */
+  fetchPage: (target: string) => Promise<string | null>;
+  /** Injected so tests drive expiry without sleeping. */
+  now: () => number;
+  /** Long enough to cover hover-to-click, short enough that nobody reads a
+   *  page rendered from data this old. */
+  ttlMs?: number;
+  /** Cap on retained payloads; the oldest is evicted first. Pages are whole
+   *  HTML documents, so this bounds memory on a link-dense page. */
+  max?: number;
+}
+
+export interface NavPayloadCache {
+  /** Warm `target`, unless a fresh entry is already present or in flight. */
+  prefetch(target: string): void;
+  /** Hand over `target`'s payload, or null. Single-use: a prefetch
+   *  accelerates the NEXT click, and holding it past that would serve
+   *  navigations from an increasingly stale render. */
+  take(target: string): Promise<string | null> | null;
+  /** Drop everything — called when a navigation commits, since entries were
+   *  rendered against the page the user just left. */
+  clear(): void;
+  /** Retained entry count (tests + diagnostics). */
+  size(): number;
+}
+
+export function createNavPayloadCache(
+  deps: NavPayloadCacheDeps,
+): NavPayloadCache {
+  const { fetchPage, now } = deps;
+  const ttlMs = deps.ttlMs ?? 15000;
+  const max = deps.max ?? 8;
+  // Holds the in-flight PROMISE, not just the resolved text, so a click that
+  // lands mid-prefetch joins that request rather than starting a second one —
+  // the common case, since hover-to-click is usually shorter than the render.
+  const entries = new Map<string, { at: number; promise: Promise<string | null> }>();
+
+  return {
+    prefetch(target: string): void {
+      const hit = entries.get(target);
+      if (hit && now() - hit.at < ttlMs) return;
+      // Re-warming an expired target: drop it first so the refreshed entry
+      // re-enters at the END of the insertion order. Map.set on an existing
+      // key keeps its original position, which would make a repeatedly
+      // re-warmed target the first one evicted. No test covers this: a
+      // re-warm only happens after expiry, so everything ahead of it in the
+      // order has expired too and evicting it costs nothing today. Keeping
+      // the LRU order honest anyway, so this stays true if the TTL does not.
+      entries.delete(target);
+      while (entries.size >= max) {
+        const oldest = entries.keys().next();
+        if (oldest.done) break;
+        entries.delete(oldest.value);
+      }
+      // A rejected fetch must not surface as an unhandled rejection when
+      // nobody ends up clicking; resolve to null and let the click refetch.
+      const promise = fetchPage(target).catch(() => null);
+      entries.set(target, { at: now(), promise });
+    },
+
+    take(target: string): Promise<string | null> | null {
+      const hit = entries.get(target);
+      if (!hit) return null;
+      entries.delete(target);
+      if (now() - hit.at >= ttlMs) return null;
+      return hit.promise;
+    },
+
+    clear(): void {
+      entries.clear();
+    },
+
+    size(): number {
+      return entries.size;
+    },
+  };
+}

package/src/ssr-nav-response.test.ts

@@ -0,0 +1,95 @@
+// Regression tests for the client-navigation response shape.
+//
+// A client-side navigation re-renders the page from __PYLON_DATA__, so the
+// markup the server built for it is parsed and thrown away. Measured on a real
+// route, that was 16442 bytes of HTML to deliver a 374-byte payload. The nav
+// response carries the head metadata and the data, and nothing else.
+
+import { describe, expect, it } from "bun:test";
+import { buildHydrationTail, isNavRequest } from "./ssr-runtime";
+
+describe("isNavRequest", () => {
+  it("recognizes the header the client sends", () => {
+    expect(isNavRequest({ "x-pylon-nav": "1" })).toBe(true);
+  });
+
+  it("tolerates surrounding whitespace", () => {
+    expect(isNavRequest({ "x-pylon-nav": " 1 " })).toBe(true);
+  });
+
+  it("treats a document load as a document load", () => {
+    expect(isNavRequest({})).toBe(false);
+    expect(isNavRequest(undefined)).toBe(false);
+    expect(isNavRequest({ accept: "text/html" })).toBe(false);
+  });
+
+  it("refuses any value other than 1", () => {
+    // Fail closed: an unrecognized value serves the full page, which is
+    // always correct, rather than a payload the caller can't use.
+    expect(isNavRequest({ "x-pylon-nav": "0" })).toBe(false);
+    expect(isNavRequest({ "x-pylon-nav": "true" })).toBe(false);
+    expect(isNavRequest({ "x-pylon-nav": "" })).toBe(false);
+  });
+});
+
+const TAIL_ARGS = {
+  component: "app/dashboard/page",
+  layouts: ["app/layout"],
+  props: { url: "/dashboard", params: {}, auth: { user_id: "u_1" } },
+  ssrData: { "list:[\"Todo\"]": [{ id: "t1" }] },
+  manifestRoute: { file: "entry-a1.js", imports: ["chunks/s.js"], css: [] },
+  publicPrefix: "/_pylon/build/",
+  manifestErr: null,
+};
+
+describe("hydration tail, dataOnly", () => {
+  it("carries the same payload as a full page tail", () => {
+    const data = (html: string) =>
+      html.match(/<script id="__PYLON_DATA__"[^>]*>(.*?)<\/script>/s)?.[1];
+    expect(data(buildHydrationTail({ ...TAIL_ARGS, dataOnly: true }))).toBe(
+      data(buildHydrationTail(TAIL_ARGS))!,
+    );
+  });
+
+  it("drops the entry script and preloads a navigation doesn't need", () => {
+    // The client already has the runtime and resolves the route entry from the
+    // build manifest, so these are dead weight on every navigation.
+    const nav = buildHydrationTail({ ...TAIL_ARGS, dataOnly: true });
+    expect(nav).not.toContain("<script type=\"module\"");
+    expect(nav).not.toContain("entry-a1.js");
+    const full = buildHydrationTail(TAIL_ARGS);
+    expect(full).toContain("entry-a1.js");
+  });
+
+  it("still strips the live handles and the request's own headers/cookies", () => {
+    // SECURITY: the strip is why this shares buildHydrationTail rather than
+    // rebuilding the payload — the session cookie must never reach client JS.
+    const nav = buildHydrationTail({
+      ...TAIL_ARGS,
+      props: {
+        ...TAIL_ARGS.props,
+        headers: { cookie: "pylon_session=secret" },
+        cookies: { pylon_session: "secret" },
+        serverData: { list: () => {} },
+        response: { setStatus: () => {} },
+      },
+      dataOnly: true,
+    });
+    expect(nav).not.toContain("secret");
+    expect(nav).not.toContain("serverData");
+  });
+
+  it("carries only the binary signed-in bit on a bucketed render", () => {
+    // A bucketed render is stored SHARED, so its payload must never carry the
+    // rendering user's identity — same rule, data-only or not.
+    const nav = buildHydrationTail({
+      ...TAIL_ARGS,
+      props: { ...TAIL_ARGS.props, auth: { user_id: "u_1", email: "a@b.c" } },
+      bucketAuth: { signedIn: true },
+      dataOnly: true,
+    });
+    expect(nav).not.toContain("u_1");
+    expect(nav).not.toContain("a@b.c");
+    expect(nav).toContain('"signedIn":true');
+  });
+});

package/src/ssr-route-match.test.ts

@@ -162,10 +162,15 @@ describe("prefetchTargets", () => {
   });
 
   it("is null-safe on an absent or empty manifest", () => {
-    expect(prefetchTargets(null, "/")).toEqual({ file: "", imports: [] });
+    expect(prefetchTargets(null, "/")).toEqual({
+      file: "",
+      imports: [],
+
+    });
     expect(prefetchTargets({ routes: {} }, "/")).toEqual({
       file: "",
       imports: [],
+
     });
   });
 

package/src/ssr-route-match.ts

@@ -116,34 +116,48 @@ export function matchRoute(
 export interface PrefetchTargets {
   /** The destination route's own entry chunk, or "" when no page route matches. */
   file: string;
-  /** Shared chunks to warm alongside it. */
+  /** Chunks to warm alongside it. */
   imports: string[];
 }
 
 /**
  * The chunks a click on `pathname` will need before anything can render: the
- * destination route's entry, plus the shared chunks (React, the client
- * runtime, common layouts) that every route pulls in.
+ * destination route's entry, plus the chunks (React, the client runtime,
+ * common layouts) it pulls in.
  *
  * Warming the page payload alone leaves the entry chunk to be fetched after
  * the click, and the route cannot render until it lands — so the prefetch
- * covers only the half that was already fast. An href matching no page route
- * (an API path, a route this build doesn't serve) still yields the shared set;
- * `file` is "" and the caller skips it.
+ * covers only the half that was already fast.
+ *
+ * Size is deliberately NOT a factor. Build output is content-hashed and served
+ * immutable, so warming a heavy route costs its bytes once per browser and
+ * makes every later visit to it instant; skipping it would trade a permanent
+ * win for a one-time saving, and would skip exactly the routes slowest to
+ * fetch on demand. The warm is deferred to the load event, so those bytes
+ * never compete with the current page's own render.
+ *
+ * An href matching no page route (an API path, a route this build doesn't
+ * serve) yields the union of every route's chunks: no destination is known,
+ * but those are needed by any navigation.
  */
 export function prefetchTargets(
   manifest: MatchableManifest | null | undefined,
   pathname: string,
 ): PrefetchTargets {
-  const imports = new Set<string>();
   if (!manifest || !manifest.routes) return { file: "", imports: [] };
-  for (const r of Object.values(manifest.routes)) {
-    for (const i of r?.imports || []) imports.add(i);
-  }
   const matched = matchRoute(manifest, pathname);
   const route = matched ? manifest.routes[matched.component] : null;
   if (route) {
-    for (const i of route.imports || []) imports.add(i);
+    // The route's OWN transitive chunks — everything it needs, and nothing
+    // belonging to routes the user isn't heading for.
+    return {
+      file: route.file || "",
+      imports: Array.from(new Set(route.imports || [])),
+    };
+  }
+  const imports = new Set<string>();
+  for (const r of Object.values(manifest.routes)) {
+    for (const i of r?.imports || []) imports.add(i);
   }
-  return { file: route?.file || "", imports: Array.from(imports) };
+  return { file: "", imports: Array.from(imports) };
 }

package/src/ssr-runtime.ts

@@ -763,24 +763,85 @@ async function buildLayoutTree(
  * Returns the project-relative path (no extension) or null.
  */
 function findBoundary(componentPath: string, fileName: string): string | null {
-  const fs = require("node:fs");
-  const path = require("node:path");
-  const cwd = process.cwd();
+  return findBoundaryIn(
+    require("node:fs"),
+    require("node:path"),
+    process.cwd(),
+    componentPath,
+    fileName,
+  );
+}
+
+/**
+ * `findBoundary` with its filesystem and root injected, so the walk is
+ * testable against a fixture without `chdir` — which races every other test
+ * in the process.
+ */
+export function findBoundaryIn(
+  fs: any,
+  path: any,
+  cwd: string,
+  componentPath: string,
+  fileName: string,
+): string | null {
   // Component paths use "/" — walk up directory by directory.
   let dir = componentPath.replace(/\\/g, "/");
   dir = dir.includes("/") ? dir.slice(0, dir.lastIndexOf("/")) : "";
   while (dir && dir !== "." && dir !== "/") {
-    for (const ext of MODULE_EXTS) {
-      if (fs.existsSync(path.join(cwd, dir, `${fileName}${ext}`))) {
-        return `${dir}/${fileName}`;
-      }
-    }
+    const hit = boundaryInDirOrGroups(fs, path, cwd, dir, fileName);
+    if (hit) return hit;
     const slash = dir.lastIndexOf("/");
     dir = slash >= 0 ? dir.slice(0, slash) : "";
   }
   return null;
 }
 
+/**
+ * The boundary for one URL-space level: `<dir>/<fileName>`, or the same file
+ * inside a route group under it.
+ *
+ * A route group contributes no URL segment, so `app/(marketing)/not-found` is
+ * the boundary for `/` exactly as `app/not-found` is — and an app can't ship
+ * both, because the duplicate-path check rejects two routes claiming `/`.
+ * Without this, putting the file in a group left `/` with no boundary at all
+ * while the build insisted the group's copy owned it.
+ *
+ * Groups nest, so this recurses. The directory's own file wins over a group's,
+ * and groups are searched in name order so the answer never depends on
+ * readdir ordering.
+ */
+function boundaryInDirOrGroups(
+  fs: any,
+  path: any,
+  cwd: string,
+  dir: string,
+  fileName: string,
+): string | null {
+  for (const ext of MODULE_EXTS) {
+    if (fs.existsSync(path.join(cwd, dir, `${fileName}${ext}`))) {
+      return `${dir}/${fileName}`;
+    }
+  }
+  let entries: any[];
+  try {
+    entries = fs.readdirSync(path.join(cwd, dir), { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  const groups = entries
+    .filter(
+      (e: any) =>
+        e.isDirectory() && e.name.startsWith("(") && e.name.endsWith(")"),
+    )
+    .map((e: any) => e.name as string)
+    .sort();
+  for (const g of groups) {
+    const hit = boundaryInDirOrGroups(fs, path, cwd, `${dir}/${g}`, fileName);
+    if (hit) return hit;
+  }
+  return null;
+}
+
 // ---------------------------------------------------------------------------
 // Social-card image file convention (Next-style `opengraph-image.png` /
 // `twitter-image.png` colocated with a `page.tsx`). Drop the file in a
@@ -1904,6 +1965,13 @@ export function buildHydrationTail(args: {
   // user's identity to another (the #277 leak class, at the body level). The
   // raw `auth` is replaced AFTER the live-handle strip below.
   bucketAuth?: { signedIn: boolean };
+  /** Client-side NAVIGATION payload: emit the `__PYLON_DATA__` blob and
+   *  nothing else. The client already has the runtime and resolves the route
+   *  entry from the build manifest, so the entry `<script>`, the preload tags
+   *  and the dev-reload snippet are all dead weight on a navigation. Shares
+   *  this function — and therefore its props strip — rather than rebuilding
+   *  the payload somewhere the security-relevant parts could drift. */
+  dataOnly?: boolean;
 }): string {
   // Strip live, non-serializable handles (serverData / response / reset) + the
   // request headers/cookies (SECURITY: never expose the session cookie to
@@ -1950,6 +2018,7 @@ export function buildHydrationTail(args: {
   if (args.kind) hydrationPayload.kind = args.kind;
   const json = escapeScriptJson(JSON.stringify(hydrationPayload));
   let tail = `<script id="__PYLON_DATA__" type="application/json">${json}</script>`;
+  if (args.dataOnly) return tail;
   if (args.manifestRoute) {
     // A cross-origin CDN module (`public_prefix` is an absolute http(s) URL) is
     // fetched in CORS mode; `crossorigin` makes the matching modulepreload
@@ -1967,6 +2036,54 @@ export function buildHydrationTail(args: {
   return tail;
 }
 
+/**
+ * Is this render answering a client-side navigation rather than a document
+ * load? The client runtime sets `X-Pylon-Nav: 1`; the Rust host reads the same
+ * header to key the ISR cache, so the two always agree on which shape a URL
+ * is being asked for.
+ */
+export function isNavRequest(
+  headers: Record<string, unknown> | undefined,
+): boolean {
+  if (!headers) return false;
+  const v = headers["x-pylon-nav"] ?? headers["X-Pylon-Nav"];
+  return typeof v === "string" && v.trim() === "1";
+}
+
+/**
+ * Render a detached element (the metadata fragment) to an HTML string.
+ *
+ * A navigation response carries the page's `<title>`/`<meta>`/`<link>` so the
+ * client can swap them, but not the page body — which the client re-renders
+ * from `__PYLON_DATA__` anyway. Rendering the fragment on its own is what
+ * lets the body be dropped without losing the head.
+ */
+export async function renderElementToString(
+  renderToReadableStream: any,
+  element: any,
+): Promise<string> {
+  if (!element) return "";
+  try {
+    const stream = await renderToReadableStream(element);
+    if ((stream as any).allReady) await (stream as any).allReady;
+    const reader = stream.getReader();
+    // One decoder across the whole read: a multi-byte character split across
+    // chunk boundaries decodes correctly only if the decoder carries state.
+    const decoder = new TextDecoder("utf-8");
+    let out = "";
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      out += decoder.decode(value, { stream: true });
+    }
+    out += decoder.decode();
+    return out;
+  } catch {
+    // Metadata is never worth failing a navigation over.
+    return "";
+  }
+}
+
 /**
  * The layout chain for a component, walked top-down from `app/` to the
  * component's own directory — IDENTICAL to the bundler's `discoverRoutes`
@@ -2146,7 +2263,32 @@ async function tryRenderBoundary(
       };
       compProps = { ...props, error: errorForClient, reset: () => {} };
     }
+    // A boundary's own `metadata` / `generateMetadata`, same as a page's.
+    // Without this a not-found.tsx rendered no <title> at all — and because
+    // the framework's built-in 404 body supplies one, taking over the boundary
+    // silently LOST the title rather than replacing it, leaving the tab
+    // showing the raw URL. The fragment goes first so React hoists its
+    // <title>/<meta> into the <head> a layout renders.
+    let boundaryMeta: SsrMetadata | undefined = mod.metadata;
+    if (typeof mod.generateMetadata === "function") {
+      try {
+        boundaryMeta = await mod.generateMetadata(compProps);
+      } catch {
+        // A boundary is already the failure path; don't fail it again over
+        // its title.
+        boundaryMeta = mod.metadata;
+      }
+    }
+    const boundaryMetaFragment = renderMetadata(React, boundaryMeta);
     let tree = React.createElement(Comp, compProps);
+    if (boundaryMetaFragment) {
+      tree = React.createElement(
+        React.Fragment,
+        null,
+        boundaryMetaFragment,
+        tree,
+      );
+    }
     tree = await buildLayoutTree(cwd, tree, boundaryLayouts, compProps, React);
     await renderBoundaryToClient(
       React,
@@ -2969,6 +3111,14 @@ export async function handleRenderRoute(
     metadata = applyAutoIcons(msg.component, metadata);
     const metaFragment = renderMetadata(React, metadata);
 
+    // Client-side navigation: the browser already has the runtime, the layouts
+    // and the styles, and re-renders the page from `__PYLON_DATA__`. Measured
+    // on a real route, the full document was 16442 bytes to deliver a 374-byte
+    // payload — the markup is built, shipped, parsed, and thrown away. This
+    // render still runs (it is what resolves serverData), but the response
+    // carries only the head metadata and the data.
+    const navRender = isNavRequest(msg.headers as Record<string, unknown>);
+
     // loading.tsx (#278): the nearest `loading` module — walked up from the
     // page dir, like not-found/error — becomes ONE route-level Suspense
     // fallback wrapping the page. When present, the shell (layouts) + this
@@ -3094,7 +3244,10 @@ export async function handleRenderRoute(
     // the fully-resolved `ssrData` map) and after all of React's $RC reveals,
     // so the client's `use()` reads a fulfilled value and never re-suspends —
     // there is no progressive hydration racing the stream.
-    if (!wantsStream && (stream as any).allReady) {
+    // A navigation response is data, so it must wait for the whole render even
+    // on a page that would otherwise stream: `ssrData` is only complete once
+    // every serverData read has resolved, and that map IS the response.
+    if ((!wantsStream || navRender) && (stream as any).allReady) {
       await (stream as any).allReady;
     }
 
@@ -3314,7 +3467,26 @@ export async function handleRenderRoute(
         data: Buffer.from(text, "utf8").toString("base64"),
       });
     };
-    await streamWithHeadInjection(stream.getReader(), headBlob, sendChunk);
+    if (navRender) {
+      // Drain React's output and drop it. The render is what resolves the
+      // serverData reads that fill `ssrData`; the markup it produces is the
+      // part the client rebuilds for itself.
+      const reader = stream.getReader();
+      for (;;) {
+        const { done } = await reader.read();
+        if (done) break;
+      }
+      // A minimal document, so the client's existing parse path works
+      // unchanged: it reads document.title, copies [data-pylon-meta], and
+      // pulls __PYLON_DATA__ — all of which this carries.
+      sendChunk(
+        '<!DOCTYPE html><html><head><meta charset="utf-8">' +
+          (await renderElementToString(renderToReadableStream, metaFragment)) +
+          "</head><body>",
+      );
+    } else {
+      await streamWithHeadInjection(stream.getReader(), headBlob, sendChunk);
+    }
 
     // #278: detect a late response.* mutation from a suspended subtree that the
     // already-committed head couldn't carry, and warn loudly (a silently
@@ -3401,17 +3573,22 @@ export async function handleRenderRoute(
         bucketAuth: bucketable
           ? { signedIn: msg.session_present === true }
           : undefined,
+        dataOnly: navRender,
       });
       sendChunk(tail);
     }
 
+
     // Dev HUD (dev only): append the cache-verdict + render-timing blob + the
     // floating overlay, and emit ONE structured log line. After the page tail so
     // the HUD marker/probe are in place before the deferred client entry boots the
     // sync engine. `devVerdict` was computed once above (reused here + in the
     // x-pylon-dev header). The log rides the runtime's inherited stderr, so an
     // agent running `pylon dev` sees the verdict without any extra call.
-    if (devVerdict) {
+    //
+    // Never on a navigation response: there is no document for the overlay to
+    // attach to, and its blob would dwarf the payload it rode in on.
+    if (devVerdict && !navRender) {
       const renderMs = Math.round((performance.now() - renderStart) * 10) / 10;
       // Build-level failures that degraded this page (currently: the
       // Tailwind compile). Dev-only and unmissable — the HUD paints a
@@ -3452,6 +3629,8 @@ export async function handleRenderRoute(
       // [pylon] line — no duplicate console.error here.
     }
 
+    if (navRender) sendChunk("</body></html>");
+
     send({ type: "render_done", call_id: msg.call_id });
   } catch (err: any) {
     // A page/layout called response.redirect()/response.notFound(), or