app/lib/speculation.mjs

Functions

Imports

It imports app/lib/json-ld.mjs. Imported by app/components/site-speculation.tsx, workers/csp.mjs.

Source

1/**
2 * A document rule, not a URL list: it derives from the links on the page, so it cannot go stale.
3 */
4
5import { jsonLd } from "./json-ld.mjs";
6
7const EXCLUDED_PREFIXES = ["/admin", "/lab", "/api", "/media"];
8
9// `/search/ask` is billed: speculating it would spend model tokens on a click nobody made.
10const EXCLUDED_PATHS = ["/login", "/theme", "/search/ask"];
11
12const EXCLUDED_SUFFIXES = [".md", ".xml", ".json", ".txt"];
13
14/**
15 * Not `immediate`: a cookie-carrying reader bypasses the cache, so immediate cost 4 to 5 extra
16 * origin document requests per page load. Chrome caps moderate speculations in flight.
17 */
18const DOCUMENT_EAGERNESS = "moderate";
19
20/**
21 * Not `prerender`: moderate starts on pointerdown, and activating a prerender that has not painted
22 * swaps in a blank frame (measured in Chrome 151). Prefetch keeps paint holding and stays credentialed.
23 */
24export const DOCUMENT_ACTION = "prefetch";
25
26/**
27 * @param {object} args
28 * @param {string} args.pathname the page the rules are being rendered on
29 * @returns {string} the JSON payload for the speculationrules script, escaped by `jsonLd` so no
30 *   `</script` or `<!--` can appear whatever the pathname. The Worker hashes this same string.
31 */
32export function buildSpeculationRules({ pathname }) {
33  /** @param {string} pattern */
34  const not = (pattern) => ({ not: { href_matches: pattern } });
35
36  // The positive clause is a pathname pattern, which makes the rule same-origin by construction.
37  const conditions = [
38    { href_matches: "/*" },
39    ...EXCLUDED_PREFIXES.flatMap((prefix) => [not(prefix), not(`${prefix}/*`)]),
40    ...EXCLUDED_PATHS.map(not),
41    ...EXCLUDED_SUFFIXES.map((suffix) => not(`/*${suffix}`)),
42    /*
43     * A URLPattern `search` component, not a pathname glob: the glob spelling silently excludes
44     * every link on the page.
45     */
46    { not: { href_matches: { search: "(.+)" } } },
47    not(pathname),
48  ];
49
50  return jsonLd({
51    [DOCUMENT_ACTION]: [{ where: { and: conditions }, eagerness: DOCUMENT_EAGERNESS }],
52  });
53}