@pylonsync/react 0.4.10 → 0.4.12

package/dist/Link.d.ts

@@ -2,7 +2,11 @@ import React from "react";
 declare global {
     interface Window {
         __pylon?: {
-            prefetch: (href: string) => Promise<void>;
+            prefetch: (href: string, opts?: {
+                /** Also fetch the page payload. Costs a server render, so only on an
+                 *  intent signal: hover, touch, or focus. */
+                document?: boolean;
+            }) => Promise<void>;
             navigate: (href: string, opts?: {
                 push?: boolean;
                 replace?: boolean;

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.4.10",
+  "version": "0.4.12",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",
@@ -14,8 +14,8 @@
     "prepack": "bun run build"
   },
   "dependencies": {
-    "@pylonsync/sdk": "0.4.10",
-    "@pylonsync/sync": "0.4.10"
+    "@pylonsync/sdk": "0.4.12",
+    "@pylonsync/sync": "0.4.12"
   },
   "peerDependencies": {
     "react": ">=19.0.0"

package/src/Link.tsx

@@ -8,12 +8,14 @@
 //     route entry, and re-renders the React root in place. Layouts
 //     that match across the two routes survive reconciliation, so
 //     their state persists.
-//   - Prefetches on viewport entry (IntersectionObserver) by default.
-//     The runtime injects `<link rel=prefetch>` for the HTML and
-//     `<link rel=modulepreload>` for the shared chunks the user
-//     will need.
-//   - Hover/touch escalation: if the link isn't in the viewport
-//     long enough, hovering still triggers prefetch.
+//   - Prefetches in two stages, because the two halves cost very
+//     different things. On viewport entry (IntersectionObserver) the
+//     runtime modulepreloads the destination's client chunks — static,
+//     immutable, cacheable. On hover, touch, or focus it also fetches
+//     the page itself, which costs a server render, so that waits for a
+//     real signal of intent rather than firing for a screenful of links.
+//     Focus is included so a keyboard user tabbing to a link gets the
+//     same warm path a mouse user gets.
 //   - Modifier keys (cmd/ctrl/shift/alt) or middle-click fall
 //     through to the browser's default behavior (open in new tab,
 //     etc.) — matches Next.js semantics.
@@ -29,7 +31,14 @@ import React, { useEffect, useRef } from "react";
 declare global {
   interface Window {
     __pylon?: {
-      prefetch: (href: string) => Promise<void>;
+      prefetch: (
+        href: string,
+        opts?: {
+          /** Also fetch the page payload. Costs a server render, so only on an
+           *  intent signal: hover, touch, or focus. */
+          document?: boolean;
+        },
+      ) => Promise<void>;
       navigate: (
         href: string,
         opts?: { push?: boolean; replace?: boolean; seed?: unknown },
@@ -115,12 +124,19 @@ export function Link({
     }
 
     const el = ref.current;
-    let prefetched = false;
-    const doPrefetch = () => {
-      if (prefetched) return;
-      prefetched = true;
+    // Chunks warm once, on sight. The page payload warms on intent — and may
+    // re-warm on a later hover, since the runtime expires payloads that have
+    // gone stale.
+    let warmedChunks = false;
+    const warmChunks = () => {
+      if (warmedChunks) return;
+      warmedChunks = true;
       window.__pylon?.prefetch(href);
     };
+    const warmPage = () => {
+      warmedChunks = true;
+      window.__pylon?.prefetch(href, { document: true });
+    };
 
     let io: IntersectionObserver | null = null;
     if (typeof IntersectionObserver !== "undefined") {
@@ -128,7 +144,7 @@ export function Link({
         (entries) => {
           for (const e of entries) {
             if (e.isIntersecting) {
-              doPrefetch();
+              warmChunks();
               io?.disconnect();
             }
           }
@@ -138,14 +154,19 @@ export function Link({
       io.observe(el);
     }
 
-    const onHover = () => doPrefetch();
-    el.addEventListener("mouseenter", onHover, { once: true });
-    el.addEventListener("touchstart", onHover, { once: true, passive: true });
+    el.addEventListener("mouseenter", warmPage);
+    el.addEventListener("touchstart", warmPage, { passive: true });
+    // Focus is the keyboard's version of hover, and a stronger signal: a
+    // cursor slides across links it isn't aiming at, but nobody tabs onto one
+    // idly. Without it, tabbing to a link and pressing Enter took the cold
+    // path while a mouse user got the warm one — the wrong way round.
+    el.addEventListener("focus", warmPage);
 
     return () => {
       io?.disconnect();
-      el.removeEventListener("mouseenter", onHover);
-      el.removeEventListener("touchstart", onHover);
+      el.removeEventListener("mouseenter", warmPage);
+      el.removeEventListener("touchstart", warmPage);
+      el.removeEventListener("focus", warmPage);
     };
   }, [href, prefetch]);
 

package/src/useRouter.test.ts

@@ -48,10 +48,16 @@ describe("notFound() — branded for the SSR not-found boundary", () => {
 describe("redirect() — client-side replace navigation", () => {
   let calls: Array<{ href: string; opts?: unknown }>;
   const hadWindow = "window" in globalThis;
+  // The suite preloads happy-dom, so a real window usually EXISTS here. Put it
+  // back rather than leaving the stub in place: bun isolates globals per test
+  // file today, so nothing observable depends on this, but a test that
+  // replaces a global and never restores it is one isolation change away from
+  // breaking every file that mounts.
+  const originalWindow = (globalThis as any).window;
 
   beforeEach(() => {
     calls = [];
-    // bun:test has no DOM — stand up a minimal window the module can see.
+    // Stand up a minimal window the module can see, without assuming a DOM.
     (globalThis as any).window = {
       __pylon: {
         prefetch: async () => {},
@@ -63,8 +69,11 @@ describe("redirect() — client-side replace navigation", () => {
   });
 
   afterEach(() => {
-    if (hadWindow) return;
-    delete (globalThis as any).window;
+    if (hadWindow) {
+      (globalThis as any).window = originalWindow;
+    } else {
+      delete (globalThis as any).window;
+    }
   });
 
   test("delegates to __pylon.navigate with replace:true (no history push)", () => {