Speculative load measurement

at a glance

Syntax

The proposal hangs a single method off performance, returning a SpeculationData with one array per speculation kind plus the navigation destination. IDL from Chromium's implementation of the explainer (Window-only, gated on SpeculationMeasurement):

// partial interface Performance (core/timing/performance.idl)
[Exposed=Window, RuntimeEnabled=SpeculationMeasurement,
 MeasureAs=SpeculationMeasurement]
SpeculationData getSpeculations();

[RuntimeEnabled=SpeculationMeasurement, Exposed=Window]
interface SpeculationData {
  readonly attribute FrozenArray<PreloadData> preloads;
  readonly attribute FrozenArray<PreconnectData> preconnects;
  readonly attribute FrozenArray<SpeculationNavigationData> navigations;
  readonly attribute USVString? navigationDestinationURL;
};

enum CrossOriginMode { "none", "anonymous", "use-credentials" };

[RuntimeEnabled=SpeculationMeasurement, Exposed=Window]
interface PreloadData {
  readonly attribute USVString url;
  readonly attribute DOMString as;
  readonly attribute CrossOriginMode crossorigin;
  readonly attribute boolean earlyhint;
  [CallWith=ScriptState] readonly attribute DOMHighResTimeStamp? used;
};

[RuntimeEnabled=SpeculationMeasurement, Exposed=Window]
interface PreconnectData {
  readonly attribute USVString origin;
  readonly attribute CrossOriginMode crossorigin;
  readonly attribute boolean earlyhint;
};

enum SpeculationNavigationType { "prefetch", "prerender", "prerender-until-script" };
enum SpeculationEagernessValue { "conservative", "moderate", "eager", "immediate" };

[RuntimeEnabled=SpeculationMeasurement, Exposed=Window]
interface SpeculationNavigationData {
  readonly attribute SpeculationNavigationType type;
  readonly attribute USVString url;
  readonly attribute FrozenArray<DOMString>? tags;
  readonly attribute SpeculationEagernessValue? eagerness;
};

Scope notes from the explainer: only speculations made by the current document are reported (even cross-origin ones), no cross-origin data leaks; resource prefetches (as opposed to navigation prefetches) are an explicit non-goal because they may still be used by a future page; <link rel=prerender> (the legacy API) is excluded in favour of speculation-rules prerenders.

Proposal, implementation, and the stale property name

Nothing here is a shipped standard yet. The explainer records an early iteration that exposed a speculations object on dismissal events, then moved away from it because that coupled the design too tightly to dismissal-event behavior. The current explainer and Chromium's experimental IDL agree on the method form, getSpeculations(). ChromeStatus's trial description and Chromium's flag comment still say performance.speculations. That stale property wording is consistent with an earlier property-shaped design, but the available sources do not prove it came from the exact dismissal-event iteration, so this page does not claim that lineage. The explainer also discusses why PerformanceObserver and the Reporting API were not selected.

Examples

// The explainer's canonical pattern: report on dismissal, keep the payload small.
window.addEventListener("pagehide", () => {
  const { preloads, navigations } = performance.getSpeculations();

  fetch("/analytics/unused-speculations", {
    method: "POST",
    keepalive: true,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ preloads, navigations }),
  });
});

Browser compatibility

There is no browser-compat-data (BCD) entry for this API yet (checked api/Performance.json directly — neither getSpeculations nor speculations is present), so the table below is an interim view built from ChromeStatus data and public signals — not from BCD.

Specifications

See also

• WICG — Speculative load measurement explainer
• Origin trial feedback — WICG issues
• blink-dev intent thread
• Chrome origin trials — registration
• Chrome Platform Showcase — Speculative load measurement (also: unused preload auditor, pagehide beacon, speculation rules lab)