Prefetch and/or prerender pages when likely navigated to (#13296)

Implements a mechanism to specify pages to be prefetched and prerendered
when likely navigated to, improving page loading speed and making
website navigation feel more snappy and seamless.

- If a page has a `next` (page) specified, prerender it.
- This for example, makes navigating to the next lesson in the tutorial
feel immediate.
- If a page has `prev` (page) specified, prefetch it.
- If on the homepage, prefetch the pages linked to in the top nav.
- On any page, prefetch a page if hovering a link to it.
- On any page, prerender a page if beginning to click a link to it.

Note that the [Speculation Rules
API](https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API)
this relies on mostly only works on Chromium-based browsers currently
with WebKit having some initial support.

Author: parlough

site/lib/src/extensions/registry.dart

@@ -10,7 +10,7 @@ import 'glossary_link_processor.dart';
 import 'header_extractor.dart';
 import 'header_processor.dart';
 import 'table_processor.dart';
-import 'tutorial_prefetch_processor.dart';
+import 'tutorial_navigation.dart';
 import 'tutorial_structure_processor.dart';
 
 /// A list of all node-processing, page extensions to applied to

…ensions/tutorial_prefetch_processor.dart …/src/extensions/tutorial_navigation.dartsite/lib/src/extensions/tutorial_prefetch_processor.dart renamed to site/lib/src/extensions/tutorial_navigation.dart site/lib/src/extensions/tutorial_prefetch_processor.dart renamed to site/lib/src/extensions/tutorial_navigation.dart

@@ -2,14 +2,12 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-import 'package:jaspr/dom.dart';
-import 'package:jaspr/jaspr.dart';
 import 'package:jaspr_content/jaspr_content.dart';
 
 import '../models/tutorial_model.dart';
 
-/// A page extension for Jaspr Content that adds page navigation and a
-/// prefetch link for the next unit to the current tutorial page.
+/// A page extension for Jaspr Content that adds
+/// page navigation to the current tutorial page.
 final class TutorialNavigationExtension implements PageExtension {
   const TutorialNavigationExtension();
 
@@ -67,19 +65,6 @@ final class TutorialNavigationExtension implements PageExtension {
       },
     );
 
-    if (nextChapter == null) {
-      return nodes;
-    }
-
-    return [
-      ComponentNode(
-        Document.head(
-          children: [
-            link(rel: 'prefetch', href: nextChapter.url),
-          ],
-        ),
-      ),
-      ...nodes,
-    ];
+    return nodes;
   }
 }

site/lib/src/layouts/dash_layout.dart

@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+import 'dart:convert';
+
 import 'package:jaspr/dom.dart';
 import 'package:jaspr/jaspr.dart';
 import 'package:jaspr_content/jaspr_content.dart';
@@ -25,6 +27,14 @@ abstract class FlutterDocsLayout extends PageLayoutBase {
 
   String get defaultSidenav => 'default';
 
+  /// Returns page-specific URLs to eagerly speculate on, in addition to
+  /// the document-level rules that match all internal links.
+  ///
+  /// Override in subclasses to provide page-specific URLs for
+  /// eager prerendering and prefetching.
+  ({Set<String> prerender, Set<String> prefetch}) speculationUrls(Page page) =>
+      const (prerender: {}, prefetch: {});
+
   @override
   @mustCallSuper
   Iterable<Component> buildHead(Page page) {
@@ -148,6 +158,9 @@ ga('create', 'UA-67589403-1', 'auto');
 ga('send', 'pageview');
 </script>
 '''),
+      // Add speculation rules and prefetch fallback links for
+      // URLs provided by subclass overrides of speculationUrls.
+      ..._buildSpeculationRulesHead(page),
     ];
   }
 
@@ -263,4 +276,66 @@ if (sidenav) {
       ],
     );
   }
+
+  /// Builds the speculation rules `<script>` and `<link rel="prefetch">`
+  /// fallback tags for the given [page].
+  ///
+  /// Includes page-specific list rules from [speculationUrls] and
+  /// document rules that prefetch internal links on hover (`moderate`)
+  /// and prerender them on click (`conservative`).
+  ///
+  /// Add the `no-prerender` class to a link to
+  /// exclude it from document-level prerendering.
+  List<Component> _buildSpeculationRulesHead(Page page) {
+    final (:prerender, :prefetch) = speculationUrls(page);
+
+    // Exclude prerendered URLs from the prefetch list since
+    // prerendering is a superset of prefetching.
+    final prefetchOnly = prefetch.difference(prerender);
+
+    // Document rules to match same-origin links across the page.
+    const internalLink = {'href_matches': '/*'};
+    const notNoPrerender = {
+      'not': {'selector_matches': '.no-prerender'},
+    };
+
+    final rules = jsonEncode({
+      'prefetch': [
+        // Prefetch internal links on hover.
+        {
+          'where': internalLink,
+          'eagerness': 'moderate',
+        },
+        // Prefetch specific URLs from the page eagerly.
+        if (prefetchOnly.isNotEmpty)
+          {
+            'urls': [...prefetchOnly],
+          },
+      ],
+      'prerender': [
+        // Prerender internal links on click,
+        // unless the link has the 'no-prerender' class.
+        {
+          'where': {
+            'and': [internalLink, notNoPrerender],
+          },
+          'eagerness': 'conservative',
+        },
+        // Prerender specific URLs from the page eagerly.
+        if (prerender.isNotEmpty)
+          {
+            'urls': [...prerender],
+            'eagerness': 'eager',
+          },
+      ],
+    }).replaceAll('</', r'<\/');
+
+    return [
+      RawText('<script type="speculationrules">$rules</script>'),
+      // Fall back to prefetch link tags for browsers without
+      // Speculation Rules API support.
+      for (final url in {...prerender, ...prefetch})
+        link(rel: 'prefetch', href: url),
+    ];
+  }
 }

site/lib/src/layouts/doc_layout.dart

@@ -24,6 +24,27 @@ class DocLayout extends FlutterDocsLayout {
 
   bool get allowBreadcrumbs => true;
 
+  @override
+  ({Set<String> prerender, Set<String> prefetch}) speculationUrls(Page page) {
+    // On the homepage, prefetch pages commonly navigated to,
+    // such as entries from the top navigation menu.
+    if (page.path == 'index.md') {
+      return (
+        prerender: const {},
+        prefetch: const {
+          '/learn/pathway',
+          '/ai/create-with-ai',
+        },
+      );
+    }
+
+    final pageData = page.data.page;
+    return (
+      prerender: {?_pathFromPageInfo(pageData['next'])},
+      prefetch: {?_pathFromPageInfo(pageData['prev'])},
+    );
+  }
+
   @override
   Component buildBody(Page page, Component child) {
     final pageData = page.data.page;
@@ -89,3 +110,12 @@ class DocLayout extends FlutterDocsLayout {
     );
   }
 }
+
+/// Extracts and returns the `path` value from a page info map,
+/// or `null` if [data] is not a map or has no `path` entry.
+String? _pathFromPageInfo(Object? data) {
+  if (data case {'path': final String path}) {
+    return path;
+  }
+  return null;
+}