perf(router): prefetch on touchstart, and eager links while idle

A finger does not hover, so a phone never prefetched: the page was
fetched on click. Touchstart now starts the fetch a tap-length early
(passive), and links marked data-stx-prefetch="eager" (a tab bar) are
fetched once the page is idle, so even their first tap is a swap. Not
on a connection that asked to save data.

Author: chrisbbreuer

packages/router/src/client.ts

@@ -2096,26 +2096,58 @@ else {
     navigate(location.pathname+location.search+location.hash,false);
   });
 
-  // ── Prefetch on hover ──
+  // ── Prefetch ──
+  // A link's page, fetched before it is followed into the cache navigate
+  // reads, so following it is a swap rather than a round trip.
+  function prefetchLink(link){
+    // Same opt-out set as the click path. Without it, hovering a link the
+    // router is not allowed to claim still fired a real GET at it — a
+    // logout or OAuth URL was requested on hover alone.
+    if(isRouterExcluded(link))return;
+    var href=withCurrentLocale(link.getAttribute('href'));
+    var key=cacheKey(href);
+    if(cache[key]||prefetching[key])return;
+    prefetching[key]=true;
+    var wantsFragment=shouldUseFragmentResponse();
+    fetch(href,{headers:wantsFragment?{'X-STX-Router':'true','Accept':'text/html'}:{'Accept':'text/html'}}).then(function(r){
+      return readPrefetchResponse(r,wantsFragment);
+    }).then(function(result){
+      if(result&&o.cache)setCache(key,result.html,result.layout,result.layoutGroup,result.title,result.containerAttrs);
+    }).catch(function(){}).finally(function(){delete prefetching[key]});
+  }
+
+  // Links marked data-stx-prefetch="eager", fetched once the page is idle, so
+  // even their first tap is served from the cache: the way a phone's tab bar
+  // switches instantly. Not on a connection that asked to save data.
+  var eagerQueued=false;
+  function prefetchEager(){
+    if(!o.prefetch||!o.cache||eagerQueued)return;
+    eagerQueued=true;
+    var run=function(){
+      eagerQueued=false;
+      var connection=navigator.connection;
+      if(connection&&(connection.saveData||/2g/.test(connection.effectiveType||'')))return;
+      var here=cacheKey(location.pathname+location.search);
+      var links=document.querySelectorAll('[data-stx-link][data-stx-prefetch="eager"]');
+      for(var i=0;i<links.length;i++){
+        var href=links[i].getAttribute('href');
+        if(href&&cacheKey(withCurrentLocale(href))!==here)prefetchLink(links[i]);
+      }
+    };
+    if(window.requestIdleCallback)window.requestIdleCallback(run,{timeout:2000});
+    else setTimeout(run,300);
+  }
+
   if(o.prefetch){
-    document.addEventListener('mouseover',function(e){
+    // A mouse hovers before it clicks. A finger does not hover, but it
+    // touches down a tap's length before the click: start the fetch there.
+    var onIntent=function(e){
       if(!e.target||!e.target.closest)return;
-      var link=e.target.closest('[data-stx-link]');
-      // Same opt-out set as the click path. Without it, hovering a link the
-      // router is not allowed to claim still fired a real GET at it — a
-      // logout or OAuth URL was requested on hover alone.
-      if(isRouterExcluded(link))return;
-      var href=withCurrentLocale(link.getAttribute('href'));
-      var key=cacheKey(href);
-      if(cache[key]||prefetching[key])return;
-      prefetching[key]=true;
-      var wantsFragment=shouldUseFragmentResponse();
-      fetch(href,{headers:wantsFragment?{'X-STX-Router':'true','Accept':'text/html'}:{'Accept':'text/html'}}).then(function(r){
-        return readPrefetchResponse(r,wantsFragment);
-      }).then(function(result){
-        if(result&&o.cache)setCache(key,result.html,result.layout,result.layoutGroup,result.title,result.containerAttrs);
-      }).catch(function(){}).finally(function(){delete prefetching[key]});
-    },true);
+      prefetchLink(e.target.closest('[data-stx-link]'));
+    };
+    document.addEventListener('mouseover',onIntent,true);
+    document.addEventListener('touchstart',onIntent,{capture:true,passive:true});
+    window.addEventListener('stx:load',prefetchEager);
   }
 
   // ── Active link management ──
@@ -2317,6 +2349,7 @@ else {
     injectStyles();
     injectViewTransitionCSS();
     refreshCurrentLinks();
+    prefetchEager();
   }
 
   if(document.readyState==='loading')document.addEventListener('DOMContentLoaded',init);else init();

packages/router/test/client-prefetch-touch.test.ts

@@ -0,0 +1,89 @@
+/**
+ * Prefetch on a phone.
+ *
+ * The router prefetched on mouseover only, and a finger never hovers, so on a
+ * phone every first visit waited for its fetch. A touch now starts the fetch
+ * at touchdown, a tap's length before the click, and links marked
+ * data-stx-prefetch="eager" (a tab bar) are fetched once the page is idle, so
+ * their first tap is served from the cache like a native tab switch.
+ */
+import { afterEach, describe, expect, it } from 'bun:test'
+import { Window } from 'very-happy-dom'
+import { getRouterScript } from '../src/client'
+
+const originalGlobals = {
+  window: globalThis.window,
+  document: globalThis.document,
+  location: globalThis.location,
+  history: globalThis.history,
+  fetch: globalThis.fetch,
+  navigator: globalThis.navigator,
+  CustomEvent: globalThis.CustomEvent,
+  Event: globalThis.Event,
+  DOMParser: globalThis.DOMParser,
+}
+
+afterEach(() => {
+  Object.assign(globalThis, originalGlobals)
+})
+
+function installRouter(body: string, connection?: { saveData?: boolean, effectiveType?: string }) {
+  const window = new Window({ url: 'http://localhost/m' })
+  window.document.write(`<html><head><meta name="stx-layout" content="layouts/mobile.stx"></head><body>${body}<main>Today</main></body></html>`)
+  ;(window as any).stx = {}
+  ;(window as any).__stxRouterConfig = { cache: true, prefetch: true, progress: false, viewTransitions: false }
+  if (connection) Object.defineProperty(window.navigator, 'connection', { configurable: true, value: connection })
+  const requested: string[] = []
+  Object.assign(globalThis, {
+    window,
+    document: window.document,
+    location: window.location,
+    history: window.history,
+    navigator: window.navigator,
+    CustomEvent: window.CustomEvent,
+    Event: window.Event,
+    DOMParser: window.DOMParser,
+    fetch: async (url: string) => {
+      requested.push(String(url))
+      return new Response('<section>page</section>', { status: 200, headers: { 'Content-Type': 'text/html', 'X-STX-Fragment': 'true', 'X-STX-Layout': 'layouts/mobile.stx' } })
+    },
+  })
+  new Function(getRouterScript())()
+  return { window, requested }
+}
+
+const wait = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
+
+describe('router prefetch on a phone', () => {
+  it('starts fetching a link when a finger touches it', async () => {
+    const { window, requested } = installRouter('<a href="/m/calendar" data-stx-link id="cal">Calendar</a>')
+    const link = window.document.getElementById('cal')!
+    link.dispatchEvent(new window.Event('touchstart', { bubbles: true }))
+    await wait(10)
+    expect(requested).toContain('/m/calendar')
+  })
+
+  it('fetches eager links once the page is idle, but not the page it is on', async () => {
+    const { requested } = installRouter(
+      '<nav><a href="/m" data-stx-link data-stx-prefetch="eager">Today</a>'
+      + '<a href="/m/calendar" data-stx-link data-stx-prefetch="eager">Calendar</a>'
+      + '<a href="/m/me" data-stx-link data-stx-prefetch="eager">Me</a>'
+      + '<a href="/m/health" data-stx-link>Health</a></nav>',
+    )
+    await wait(400)
+    expect(requested.sort()).toEqual(['/m/calendar', '/m/me'])
+  })
+
+  it('leaves eager links alone on a connection that asked to save data', async () => {
+    const { requested } = installRouter('<a href="/m/calendar" data-stx-link data-stx-prefetch="eager">Calendar</a>', { saveData: true })
+    await wait(400)
+    expect(requested).toEqual([])
+  })
+
+  it('never prefetches a link the router may not claim', async () => {
+    const { window, requested } = installRouter('<a href="/logout" data-stx-link data-stx-no-router id="out">Log out</a>')
+    window.document.getElementById('out')!.dispatchEvent(new window.Event('touchstart', { bubbles: true }))
+    await wait(10)
+    expect(requested).toEqual([])
+  })
+})