@pylonsync/functions 0.4.10 → 0.4.11

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.4.10",
+  "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-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,30 @@ function whenLoaded(fn) {
   window.addEventListener("load", fn, { once: true });
 }
 
-async function prefetch(href) {
-  // HTML prefetch — primes the SSR response cache.
+// 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);
   }
   const manifest = await loadManifest();
   if (!manifest) return;
@@ -643,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
@@ -851,15 +871,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: { Accept: "text/html" },
+      });
+      if (!res.ok) {
+        fullLoad();
+        return;
+      }
+      html = await res.text();
     }
-    html = await res.text();
   } catch {
     fullLoad();
     return;
@@ -912,6 +938,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 +1437,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-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) };
 }