@pylonsync/functions 0.4.9 → 0.4.11

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

@@ -1,15 +1,19 @@
+/** A per-directory module resolved by walking up from a route: the two error
+ *  boundaries, plus `loading` (the pending-navigation skeleton). */
+export type BoundaryFile = "not-found" | "error" | "loading";
 /**
- * Resolve the nearest boundary module (`<dir>/not-found` or `<dir>/error`)
- * for a route by walking its component path up to the app root, returning the
- * first manifest route key that exists. Nearest ancestor wins — the same model
- * the server's `findBoundary` uses, but driven off the client build manifest's
- * route keys so the client runtime needs no extra server round-trip.
+ * Resolve the nearest `<dir>/<fileName>` module for a route by walking its
+ * component path up to the app root, returning the first key that exists.
+ * Nearest ancestor wins — the same model the server's `findBoundary` uses, but
+ * driven off client-side keys so the runtime needs no extra server round-trip.
  *
  * `component` is a cwd-relative path with "/" separators and no extension
- * (e.g. "web/app/dashboard/orgs/[slug]/page"); `routeKeys` is
- * `Object.keys(manifest.routes)`.
+ * (e.g. "web/app/dashboard/orgs/[slug]/page"). `keys` is the set to resolve
+ * against: `Object.keys(manifest.routes)` for not-found/error, which ship as
+ * route entries, or the loading registry's keys for `loading`, which ships in
+ * the shared chunk instead.
  */
-export declare function nearestBoundaryComponent(component: string, fileName: "not-found" | "error", routeKeys: Iterable<string>): string | null;
+export declare function nearestBoundaryComponent(component: string, fileName: BoundaryFile, routeKeys: Iterable<string>): string | null;
 /** Runtime internals the boundary needs, injected so the module stays
  *  browser-safe AND unit-testable. */
 export interface BoundaryDeps {

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

@@ -24,6 +24,30 @@ interface BundleClientMessage {
  * import into a loud build failure that names the offending importer.
  */
 export declare function assertNotServerOnly(specifier: string, importer: string): void;
+/**
+ * Every route-level `loading` module under the app dir, as project-relative
+ * component paths (`app/dashboard/loading`), sorted for a stable build.
+ *
+ * Unlike not-found / error, these get NO client entry of their own — see
+ * `generateLoadingRegistry` for why.
+ */
+export declare function discoverLoadingModules(fs: any, path: any, cwd: string, appDirRel: string): string[];
+/**
+ * The module the client runtime imports as `./loading-registry`: every
+ * loading.tsx in the app, keyed by component path so the runtime can walk up
+ * from a destination route to its nearest one — the same nearest-ancestor rule
+ * the server's findBoundary applies.
+ *
+ * Statically imported, so these land in the SHARED chunk rather than shipping
+ * as route entries the way not-found / error do. A loading state exists to
+ * acknowledge a click that is already waiting on the network; fetching a chunk
+ * to render it would put it behind the very delay it covers.
+ *
+ * Route groups need no special handling: a page under `app/(dash)/settings`
+ * resolves against `app/(dash)/loading` by path, exactly as it does on the
+ * server.
+ */
+export declare function generateLoadingRegistry(components: string[]): string;
 /**
  * Manifest schema. One entry per route, indexed by the same
  * project-relative component path the SSR side passes through.

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

@@ -4,10 +4,14 @@ export interface RouteMatch {
     /** Decoded dynamic params captured from the path (e.g. `{ slug: "shoe-x" }`). */
     params: Record<string, string>;
 }
-/** The slice of the build manifest this matcher needs. */
+/** The slice of the build manifest this module needs. */
 export interface MatchableManifest {
     routes: Record<string, {
         path?: string;
+        /** The route's own entry chunk (outdir-relative). */
+        file?: string;
+        /** Shared chunks the browser needs before that entry runs. */
+        imports?: string[];
     }>;
 }
 /**
@@ -18,3 +22,31 @@ export interface MatchableManifest {
  * so `/orders/new` beats `/orders/[id]` beats `/[...all]`.
  */
 export declare function matchRoute(manifest: MatchableManifest | null | undefined, pathname: string): RouteMatch | null;
+/** What `<Link prefetch>` should warm for a destination href. */
+export interface PrefetchTargets {
+    /** The destination route's own entry chunk, or "" when no page route matches. */
+    file: string;
+    /** 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 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.
+ *
+ * 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/package.json

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

package/src/ssr-client-boundary.ts

@@ -21,20 +21,25 @@
 
 import { Component, createElement, useEffect, useState } from "react";
 
+/** A per-directory module resolved by walking up from a route: the two error
+ *  boundaries, plus `loading` (the pending-navigation skeleton). */
+export type BoundaryFile = "not-found" | "error" | "loading";
+
 /**
- * Resolve the nearest boundary module (`<dir>/not-found` or `<dir>/error`)
- * for a route by walking its component path up to the app root, returning the
- * first manifest route key that exists. Nearest ancestor wins — the same model
- * the server's `findBoundary` uses, but driven off the client build manifest's
- * route keys so the client runtime needs no extra server round-trip.
+ * Resolve the nearest `<dir>/<fileName>` module for a route by walking its
+ * component path up to the app root, returning the first key that exists.
+ * Nearest ancestor wins — the same model the server's `findBoundary` uses, but
+ * driven off client-side keys so the runtime needs no extra server round-trip.
  *
  * `component` is a cwd-relative path with "/" separators and no extension
- * (e.g. "web/app/dashboard/orgs/[slug]/page"); `routeKeys` is
- * `Object.keys(manifest.routes)`.
+ * (e.g. "web/app/dashboard/orgs/[slug]/page"). `keys` is the set to resolve
+ * against: `Object.keys(manifest.routes)` for not-found/error, which ship as
+ * route entries, or the loading registry's keys for `loading`, which ships in
+ * the shared chunk instead.
  */
 export function nearestBoundaryComponent(
   component: string,
-  fileName: "not-found" | "error",
+  fileName: BoundaryFile,
   routeKeys: Iterable<string>,
 ): string | null {
   const keys = routeKeys instanceof Set ? routeKeys : new Set(routeKeys);

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

@@ -25,6 +25,8 @@ import {
   buildClientBundle,
   buildTailwind,
   assertNotServerOnly,
+  discoverLoadingModules,
+  generateLoadingRegistry,
   type PylonBundleManifest,
 } from "./ssr-client-bundler";
 import { nearestBoundaryComponent } from "./ssr-client-boundary";
@@ -488,3 +490,163 @@ describe("server-only guard (secrets can't leak into the client bundle)", () =>
     fs.rmSync(dir, { recursive: true, force: true });
   });
 });
+
+// ---------------------------------------------------------------------------
+// loading.tsx during client-side navigation.
+//
+// Regression: a route-level loading.tsx was honored ONLY by the server's
+// streaming render. The client bundler emitted entries for not-found and error
+// but not loading, so no loading module existed on the client at all and a
+// pending navigation left the previous page fully painted until the
+// destination was ready. Polling the DOM every 15ms across a sidebar click
+// never saw the skeleton; the same route hard-loaded streamed it fine.
+// ---------------------------------------------------------------------------
+
+const LOADING_BODY = `
+import React from "react";
+export default function Loading() {
+  return <div aria-busy="true" data-skeleton="pylon-pending">Loading…</div>;
+}
+`;
+
+describe("discoverLoadingModules", () => {
+  test("finds loading modules at every depth, sorted", () => {
+    tempDir = makeFixture(
+      {
+        "page.tsx": PAGE_BODY("Home"),
+        "loading.tsx": LOADING_BODY,
+        "dashboard/page.tsx": PAGE_BODY("Dash"),
+        "dashboard/events/[id]/page.tsx": PAGE_BODY("Event"),
+        "dashboard/events/[id]/loading.tsx": LOADING_BODY,
+      },
+      { "layout.tsx": LAYOUT_BODY },
+    );
+    expect(discoverLoadingModules(fs, path, tempDir, "app")).toEqual([
+      "app/dashboard/events/[id]/loading",
+      "app/loading",
+    ]);
+  });
+
+  test("finds one inside a route group", () => {
+    // Chrome commonly lives in a (group) layout; its loading sibling has to be
+    // discoverable by the same path walk the server uses.
+    tempDir = makeFixture(
+      {
+        "(dash)/settings/page.tsx": PAGE_BODY("Settings"),
+        "(dash)/loading.tsx": LOADING_BODY,
+      },
+      { "layout.tsx": LAYOUT_BODY },
+    );
+    expect(discoverLoadingModules(fs, path, tempDir, "app")).toEqual([
+      "app/(dash)/loading",
+    ]);
+  });
+
+  test("an app with no loading.tsx yields an empty list, not an error", () => {
+    tempDir = makeFixture(
+      { "page.tsx": PAGE_BODY("Home") },
+      { "layout.tsx": LAYOUT_BODY },
+    );
+    expect(discoverLoadingModules(fs, path, tempDir, "app")).toEqual([]);
+  });
+});
+
+describe("generateLoadingRegistry", () => {
+  test("keys each module by component path so the nearest-ancestor walk works", () => {
+    const src = generateLoadingRegistry([
+      "app/loading",
+      "app/dashboard/loading",
+    ]);
+    expect(src).toContain(`import M0 from "../app/loading";`);
+    expect(src).toContain(`import M1 from "../app/dashboard/loading";`);
+    expect(src).toContain(`"app/loading": M0,`);
+    expect(src).toContain(`"app/dashboard/loading": M1,`);
+  });
+
+  test("emits a valid empty registry when the app has none", () => {
+    // The runtime imports LOADING_MODULES unconditionally — an app without a
+    // loading.tsx must still produce a module that parses and exports it.
+    const src = generateLoadingRegistry([]);
+    expect(src).toContain("export const LOADING_MODULES = {");
+    expect(src).not.toContain("import M0");
+  });
+});
+
+describe("nearestBoundaryComponent resolves loading.tsx", () => {
+  const loadingKeys = new Set([
+    "web/app/loading",
+    "web/app/dashboard/events/[id]/loading",
+  ]);
+
+  test("a sibling route picks up the nearest ancestor's skeleton", () => {
+    // Every tab under events/[id] shares that one loading.tsx.
+    expect(
+      nearestBoundaryComponent(
+        "web/app/dashboard/events/[id]/speakers/page",
+        "loading",
+        loadingKeys,
+      ),
+    ).toBe("web/app/dashboard/events/[id]/loading");
+  });
+
+  test("falls back to the root skeleton outside that subtree", () => {
+    expect(
+      nearestBoundaryComponent("web/app/settings/page", "loading", loadingKeys),
+    ).toBe("web/app/loading");
+  });
+
+  test("returns null when the app ships none", () => {
+    expect(
+      nearestBoundaryComponent("web/app/page", "loading", new Set()),
+    ).toBeNull();
+  });
+});
+
+describe("loading.tsx is wired into the client build", () => {
+  test("ships in the SHARED chunk — a skeleton can't wait on its own fetch", async () => {
+    tempDir = makeFixture(
+      {
+        "page.tsx": PAGE_BODY("Home"),
+        "dashboard/page.tsx": PAGE_BODY("Dash"),
+        "dashboard/loading.tsx": LOADING_BODY,
+      },
+      { "layout.tsx": LAYOUT_BODY },
+    );
+    originalCwd = process.cwd();
+    process.chdir(tempDir);
+
+    const { manifestPath, outdir } = await buildClientBundle();
+    const manifest = JSON.parse(
+      fs.readFileSync(manifestPath, "utf8"),
+    ) as PylonBundleManifest;
+
+    // Not a route entry: it has no URL of its own, and a loading state that
+    // costs a chunk fetch sits behind the very delay it exists to cover.
+    expect(manifest.routes["app/dashboard/loading"]).toBeUndefined();
+
+    const sharedChunks = fs
+      .readdirSync(path.join(outdir, "chunks"))
+      .map((n) => fs.readFileSync(path.join(outdir, "chunks", n), "utf8"))
+      .join("\n");
+    // The skeleton's own markup, and the registry key the runtime walks to.
+    expect(sharedChunks).toContain("pylon-pending");
+    expect(sharedChunks).toContain("app/dashboard/loading");
+  });
+
+  test("an app with no loading.tsx still builds and navigates", async () => {
+    // The runtime's import of ./loading-registry is unconditional, so the
+    // staged module must exist even with nothing to put in it.
+    tempDir = makeFixture(
+      { "page.tsx": PAGE_BODY("Home"), "about/page.tsx": PAGE_BODY("About") },
+      { "layout.tsx": LAYOUT_BODY },
+    );
+    originalCwd = process.cwd();
+    process.chdir(tempDir);
+
+    const { manifestPath } = await buildClientBundle();
+    expect(fs.existsSync(manifestPath)).toBe(true);
+    expect(
+      fs.existsSync(path.join(tempDir, ".pylon", "loading-registry.ts")),
+    ).toBe(true);
+  });
+});

package/src/ssr-client-bundler.ts

@@ -230,6 +230,77 @@ function discoverRoutes(
   }));
 }
 
+/**
+ * Every route-level `loading` module under the app dir, as project-relative
+ * component paths (`app/dashboard/loading`), sorted for a stable build.
+ *
+ * Unlike not-found / error, these get NO client entry of their own — see
+ * `generateLoadingRegistry` for why.
+ */
+export function discoverLoadingModules(
+  fs: any,
+  path: any,
+  cwd: string,
+  appDirRel: string,
+): string[] {
+  const found: string[] = [];
+  function walk(dir: string) {
+    let entries: any[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    const here = ["loading.tsx", "loading.ts", "loading.jsx", "loading.js"]
+      .map((n: string) => path.join(dir, n))
+      .find((p: string) => fs.existsSync(p));
+    if (here) {
+      found.push(
+        path.relative(cwd, here).replace(/\.(tsx?|jsx?)$/, "").replace(/\\/g, "/"),
+      );
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      if (e.name.startsWith(".") || e.name === "node_modules") continue;
+      walk(path.join(dir, e.name));
+    }
+  }
+  walk(path.join(cwd, appDirRel));
+  found.sort();
+  return found;
+}
+
+/**
+ * The module the client runtime imports as `./loading-registry`: every
+ * loading.tsx in the app, keyed by component path so the runtime can walk up
+ * from a destination route to its nearest one — the same nearest-ancestor rule
+ * the server's findBoundary applies.
+ *
+ * Statically imported, so these land in the SHARED chunk rather than shipping
+ * as route entries the way not-found / error do. A loading state exists to
+ * acknowledge a click that is already waiting on the network; fetching a chunk
+ * to render it would put it behind the very delay it covers.
+ *
+ * Route groups need no special handling: a page under `app/(dash)/settings`
+ * resolves against `app/(dash)/loading` by path, exactly as it does on the
+ * server.
+ */
+export function generateLoadingRegistry(components: string[]): string {
+  const imports = components
+    .map((c, i) => `import M${i} from "${cwd_to_import(c)}";`)
+    .join("\n");
+  const entries = components
+    .map((c, i) => `  ${JSON.stringify(c)}: M${i},`)
+    .join("\n");
+  return `// Generated by Pylon SSR (route-level loading.tsx registry).
+// DO NOT EDIT — overwritten on every pylon dev / build.
+${imports ? "\n" + imports + "\n" : ""}
+export const LOADING_MODULES = {
+${entries}
+};
+`;
+}
+
 /**
  * The shared hydration dispatcher + router. ONE module, imported
  * by every per-route entry. Bun's splitter sees N entries reach
@@ -259,11 +330,16 @@ const CLIENT_RUNTIME_SOURCE = `// Generated by Pylon SSR (Phase 2 client runtime
 
 import { createElement } from "react";
 import { hydrateRoot } from "react-dom/client";
-import { createPylonBoundary } from "./client-boundary";
-import { matchRoute } from "./route-match";
+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);
 let activeRoot = null;
+// Component path of the route currently mounted (the manifest key). Its cached
+// layout chain is what a pending-navigation skeleton renders inside.
+let currentComponent = null;
 // Destination of an in-flight client navigation. Read by hydrateRoot's
 // onUncaughtError so a re-render that throws mid-nav degrades to a full page
 // load instead of a white screen. Null when no nav is in flight.
@@ -509,32 +585,57 @@ function preloadChunks(routeInfo) {
   }
 }
 
-async function prefetch(href) {
-  // HTML prefetch — primes the SSR response cache.
+// Run fn once the page itself has finished loading. modulepreload fetches at
+// high priority, and a sidebar of links warms on first paint (Link's
+// IntersectionObserver), so warming a dozen route chunks inline would compete
+// with the current page's own scripts and data — buying a faster second
+// navigation with a slower first render.
+function whenLoaded(fn) {
+  if (document.readyState === "complete") {
+    fn();
+    return;
+  }
+  window.addEventListener("load", fn, { once: true });
+}
+
+// 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: { Accept: "text/html" },
+    }).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);
   }
-  // Chunk prefetch — peek at the manifest, but we don't know the
-  // component path from the href without server help. v1: rely on
-  // the shared chunk already being cached + the SSR head emitting
-  // the right preload tags after the user lands. So all prefetch
-  // does today is HTML — chunk dedup happens via the manifest.
   const manifest = await loadManifest();
-  if (manifest) {
-    // Pre-warm all routes' shared chunks (one chunk in practice).
-    const shared = new Set();
-    for (const r of Object.values(manifest.routes || {})) {
-      for (const i of r.imports || []) shared.add(i);
-    }
-    const info = { public_prefix: manifest.public_prefix, file: "", imports: Array.from(shared) };
-    preloadChunks(info);
-  }
+  if (!manifest) return;
+  // Chunk prefetch. The page payload above is the half that was already
+  // cheap: nothing can render until the destination's own entry chunk lands,
+  // so warming only the HTML leaves a full round-trip on the click.
+  const targets = prefetchTargets(manifest, url.pathname);
+  whenLoaded(() =>
+    preloadChunks({
+      public_prefix: manifest.public_prefix,
+      file: targets.file,
+      imports: targets.imports,
+    }),
+  );
 }
 
 async function loadRouteEntry(component) {
@@ -557,6 +658,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
@@ -570,6 +676,7 @@ export function hydrate(component, Page, Layouts) {
     }
     setNavParams(data);
     currentPageProps = withClientProps(data);
+    currentComponent = data.component;
     const tree = withBoundary(
       buildTree(Page, Layouts, currentPageProps),
       data.component,
@@ -628,6 +735,48 @@ function syncHeadMeta(doc) {
   }
 }
 
+// How long a navigation may run before the destination's loading.tsx takes
+// over the page area. Below this, the transition finishes on its own and
+// swapping to a skeleton would read as a flicker rather than as feedback.
+const PENDING_PLACEHOLDER_MS = 100;
+
+// Paint the destination's nearest loading.tsx in place of the current page,
+// so a click that can't complete immediately is still acknowledged. Returns
+// whether anything was rendered — apps without a loading.tsx keep the old
+// behavior (previous page stays put until the new one is ready).
+//
+// Rendered inside the CURRENTLY MOUNTED layout chain, not the destination's:
+// the destination's layouts live in the chunk this skeleton exists to cover,
+// so waiting for them would defeat the point. Sibling routes (the common case
+// for a nav that's slow enough to reach here) share that chain anyway, and
+// React keeps those layouts mounted across the swap — only the page area
+// changes.
+//
+// Props are the current page's, verbatim. Layouts re-render with the data they
+// already had, so one that read serverData or params can't suspend on a
+// never-resolving handle or crash on a cache miss halfway through a
+// transition. A skeleton has no data of its own to show.
+function renderPendingPlaceholder(pathname, manifest, myEpoch) {
+  if (!activeRoot || !currentComponent) return false;
+  const matched = matchRoute(manifest, pathname);
+  if (!matched) return false;
+  const key = nearestBoundaryComponent(
+    matched.component,
+    "loading",
+    Object.keys(LOADING_MODULES),
+  );
+  const Loading = key ? LOADING_MODULES[key] : null;
+  if (!Loading) return false;
+  const current = routeCache[currentComponent];
+  const tree = withBoundary(
+    buildTree(Loading, (current && current.Layouts) || [], currentPageProps),
+    currentComponent,
+    myEpoch,
+  );
+  activeRoot.render(tree);
+  return true;
+}
+
 async function navigate(href, opts) {
   const push = !opts || opts.push !== false;
   const url = new URL(href, location.href);
@@ -643,6 +792,14 @@ async function navigate(href, opts) {
   const myEpoch = ++navEpoch;
   currentSeed = opts && opts.seed != null ? opts.seed : null;
 
+  // Flipped the moment this nav commits or gives up, so a pending-placeholder
+  // timer that fires late can never paint a skeleton over real content.
+  const navState = { settled: false };
+  const fullLoad = () => {
+    navState.settled = true;
+    window.location.href = href;
+  };
+
   // ---- Optimistic first paint --------------------------------------------
   // With a seed AND a client-resolvable route, render the destination NOW —
   // before the SSR fetch — with a pending serverData, so the page shows its
@@ -673,6 +830,7 @@ async function navigate(href, opts) {
           myEpoch,
         );
         pendingNav = target;
+        currentComponent = matched.component;
         activeRoot.render(tree);
         if (opts && opts.replace) {
           history.replaceState({ component: matched.component }, "", target);
@@ -688,34 +846,62 @@ async function navigate(href, opts) {
     }
   }
 
+  // ---- Pending-state placeholder -----------------------------------------
+  // Nothing below paints until the SSR payload AND the destination's chunk are
+  // both in hand, which on a cold route is long enough for the click to look
+  // ignored. Hand the page area to the destination's loading.tsx once the nav
+  // outlives the flicker threshold. Skipped when a seed already painted the
+  // real destination — that's strictly better than a skeleton.
+  let placeholderTimer = null;
+  if (!didOptimistic && activeRoot) {
+    placeholderTimer = setTimeout(() => {
+      placeholderTimer = null;
+      // loadManifest resolves instantly once warm (Link prefetch primes it on
+      // first paint); the settled check covers the cold first navigation,
+      // where the fetch can win the race with it.
+      loadManifest().then((manifest) => {
+        if (navState.settled || myEpoch !== navEpoch) return;
+        if (renderPendingPlaceholder(url.pathname, manifest, myEpoch)) {
+          window.scrollTo(0, 0);
+        }
+      });
+    }, PENDING_PLACEHOLDER_MS);
+  }
+
   // ---- Real fetch + render -----------------------------------------------
   let html;
   try {
-    const res = await fetch(target, {
-      credentials: "same-origin",
-      headers: { Accept: "text/html" },
-    });
-    if (!res.ok) {
-      window.location.href = href;
-      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: { Accept: "text/html" },
+      });
+      if (!res.ok) {
+        fullLoad();
+        return;
+      }
+      html = await res.text();
     }
-    html = await res.text();
   } catch {
-    window.location.href = href;
+    fullLoad();
     return;
   }
   if (myEpoch !== navEpoch) return;
   const doc = new DOMParser().parseFromString(html, "text/html");
   const dataEl = doc.getElementById("__PYLON_DATA__");
   if (!dataEl) {
-    window.location.href = href;
+    fullLoad();
     return;
   }
   let data;
   try {
     data = JSON.parse(dataEl.textContent || "{}");
   } catch {
-    window.location.href = href;
+    fullLoad();
     return;
   }
   let route;
@@ -723,10 +909,12 @@ async function navigate(href, opts) {
     route = await loadRouteEntry(data.component);
   } catch (e) {
     console.warn("[pylon ssr] nav fallback (entry load failed):", e);
-    window.location.href = href;
+    fullLoad();
     return;
   }
   if (myEpoch !== navEpoch) return;
+  navState.settled = true;
+  if (placeholderTimer) clearTimeout(placeholderTimer);
   document.title = doc.title || document.title;
   syncHeadMeta(doc);
   setNavParams(data);
@@ -749,6 +937,11 @@ async function navigate(href, opts) {
   // (instead of leaving the URL changed but the page unswapped). Cleared on the
   // 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;
@@ -1244,6 +1437,28 @@ 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
+    // no loading.tsx gets an empty registry, since the runtime's import of it
+    // is unconditional.
+    fs.writeFileSync(
+      path.join(stageDir, "loading-registry.ts"),
+      generateLoadingRegistry(
+        discoverLoadingModules(fs, path, cwd, appDirRel),
+      ),
+      "utf8",
+    );
+
     const entryPaths: string[] = [];
     // entryPath (absolute) → component path (for manifest lookup).
     const entryToComponent = new Map<string, string>();

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-route-match.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, it } from "bun:test";
-import { matchRoute, type MatchableManifest } from "./ssr-route-match";
+import {
+  matchRoute,
+  prefetchTargets,
+  type MatchableManifest,
+} from "./ssr-route-match";
 
 const manifest: MatchableManifest = {
   routes: {
@@ -81,3 +85,99 @@ describe("matchRoute", () => {
     expect(matchRoute({ routes: {} }, "/")).toBeNull();
   });
 });
+
+// ---------------------------------------------------------------------------
+// prefetchTargets — what <Link prefetch> warms.
+//
+// Regression: prefetch emitted the page payload and the shared chunks but
+// never the destination's OWN entry chunk, so every click paid a full
+// round-trip (126-281ms measured across a 12-link sidebar) before the route
+// could render. The payload it did prefetch was the half that was already fast.
+// ---------------------------------------------------------------------------
+
+const chunked: MatchableManifest = {
+  routes: {
+    "app/page": {
+      path: "/",
+      file: "client-entry-app__page-a1.js",
+      imports: ["chunks/shared-1.js"],
+    },
+    "app/speakers/page": {
+      path: "/speakers",
+      file: "client-entry-app__speakers__page-b2.js",
+      imports: ["chunks/shared-1.js", "chunks/editor-2.js"],
+    },
+    "app/events/[id]/page": {
+      path: "/events/[id]",
+      file: "client-entry-app__events____id____page-c3.js",
+      imports: ["chunks/shared-1.js"],
+    },
+    // A boundary module: no path, so it never matches a href.
+    "app/not-found": { file: "client-entry-app__not_found-d4.js", imports: [] },
+  },
+};
+
+describe("prefetchTargets", () => {
+  it("names the destination's OWN entry chunk", () => {
+    // The whole point: without `file`, the click still blocks on this fetch.
+    expect(prefetchTargets(chunked, "/speakers").file).toBe(
+      "client-entry-app__speakers__page-b2.js",
+    );
+  });
+
+  it("includes chunks belonging to the destination alone", () => {
+    // editor-2 is imported only by /speakers. It has to be in the warm set
+    // whether it's reached as the destination's own import or via the
+    // all-routes union.
+    expect(prefetchTargets(chunked, "/speakers").imports).toContain(
+      "chunks/editor-2.js",
+    );
+  });
+
+  it("warms the shared chunks every route needs", () => {
+    expect(prefetchTargets(chunked, "/").imports).toContain("chunks/shared-1.js");
+  });
+
+  it("resolves a dynamic route to its entry", () => {
+    expect(prefetchTargets(chunked, "/events/42").file).toBe(
+      "client-entry-app__events____id____page-c3.js",
+    );
+  });
+
+  it("yields no entry for an href that matches no page route", () => {
+    // e.g. an API path or a route this build doesn't serve. Shared chunks are
+    // still worth warming; the caller skips an empty `file`.
+    const t = prefetchTargets(chunked, "/api/webhooks/stripe");
+    expect(t.file).toBe("");
+    expect(t.imports).toContain("chunks/shared-1.js");
+  });
+
+  it("never resolves to a boundary module's entry", () => {
+    expect(prefetchTargets(chunked, "/not-found").file).toBe("");
+  });
+
+  it("deduplicates chunks shared across routes", () => {
+    const imports = prefetchTargets(chunked, "/speakers").imports;
+    expect(imports.filter((i) => i === "chunks/shared-1.js")).toHaveLength(1);
+  });
+
+  it("is null-safe on an absent or empty manifest", () => {
+    expect(prefetchTargets(null, "/")).toEqual({
+      file: "",
+      imports: [],
+
+    });
+    expect(prefetchTargets({ routes: {} }, "/")).toEqual({
+      file: "",
+      imports: [],
+
+    });
+  });
+
+  it("tolerates a manifest whose routes carry no chunk fields", () => {
+    // Older build output — must degrade, not throw.
+    expect(prefetchTargets({ routes: { "app/page": { path: "/" } } }, "/")).toEqual(
+      { file: "", imports: [] },
+    );
+  });
+});

package/src/ssr-route-match.ts

@@ -18,9 +18,18 @@ export interface RouteMatch {
   params: Record<string, string>;
 }
 
-/** The slice of the build manifest this matcher needs. */
+/** The slice of the build manifest this module needs. */
 export interface MatchableManifest {
-  routes: Record<string, { path?: string }>;
+  routes: Record<
+    string,
+    {
+      path?: string;
+      /** The route's own entry chunk (outdir-relative). */
+      file?: string;
+      /** Shared chunks the browser needs before that entry runs. */
+      imports?: string[];
+    }
+  >;
 }
 
 function splitPath(p: string): string[] {
@@ -102,3 +111,53 @@ export function matchRoute(
   }
   return best ? best.match : null;
 }
+
+/** What `<Link prefetch>` should warm for a destination href. */
+export interface PrefetchTargets {
+  /** The destination route's own entry chunk, or "" when no page route matches. */
+  file: string;
+  /** 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 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.
+ *
+ * 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 {
+  if (!manifest || !manifest.routes) return { file: "", imports: [] };
+  const matched = matchRoute(manifest, pathname);
+  const route = matched ? manifest.routes[matched.component] : null;
+  if (route) {
+    // 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: "", imports: Array.from(imports) };
+}