@pylonsync/functions 0.4.11 → 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-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.11",
+  "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

@@ -598,6 +598,14 @@ function whenLoaded(fn) {
   window.addEventListener("load", fn, { once: true });
 }
 
+// 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({
@@ -605,7 +613,7 @@ const navPayloads = createNavPayloadCache({
   fetchPage: (target) =>
     fetch(target, {
       credentials: "same-origin",
-      headers: { Accept: "text/html" },
+      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.
@@ -878,7 +886,7 @@ async function navigate(href, opts) {
     if (html == null) {
       const res = await fetch(target, {
         credentials: "same-origin",
-        headers: { Accept: "text/html" },
+        headers: NAV_REQUEST_HEADERS,
       });
       if (!res.ok) {
         fullLoad();

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-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