Refactor addSpeculationRules to Return Individual DOM References for Removability

[giorgiopellegrino]

Description

The addSpeculationRules function should support dynamic addition and removal of speculation rules in alignment with recent platform capabilities.

Motivation

The current implementation adds all URLs in a single <script type="speculationrules"> element. However, with support for removing speculation rules based on viewport visibility, it's more effective to:

• Insert one speculation rule per URL.
• Return a structured response linking each URL to its corresponding DOM element, allowing the caller to remove individual rules without querying the DOM.

Changes to introduce

• For each URL, a separate speculation rule script should be created and appended to the document.
• The function should return an array of Maps in the format:

{
  "/page1": HTMLScriptElement,
  "/page2": HTMLScriptElement,
  ...
}

Example Usage

const urls = addSpeculationRules(["/page1", "/page2"], "eager");
document.head.removeChild(urls["/page1"]);

This approach improves clarity and simplifies DOM cleanup when rules are no longer needed.

cc @gilbertococchi @addyosmani

[gilbertococchi]

Thanks Giorgio, @tunetheweb @hadyan, @domenic FYI

That sounds like a great plan, I was thinking it that it might be good reference these HTMLScriptElements (the SpeculationRules tags) to the IntersectionObserverTarget itself to make the link between the Link entering or quitting the viewport and the element needed to be added or removed.

Do you agree?

[tunetheweb]

I think Gilberto's suggest might handle the case when two links point to the same URL? So maybe a good idea?

Also nodes can be quite big. Using weakrefs would solve this for HTMLScriptElement, but if holding refs to the links themselves that might be more complicated.

[giorgiopellegrino]

Exactly, @gilbertococchi . My goal is to modify the addSpeculationRules(urlsToPrerender, eagerness) function, located in prerender.mjs, so that when it is invoked by the listen(el) method in index.mjs, the corresponding speculation rules can be removed from the DOM when the associated element exits the IntersectionObserver.
@tunetheweb If you believe it would be more appropriate to manage the map using WeakRef entries, I would be in agreement with that approach. Thank you.
Giorgio

[giorgiopellegrino]

I have submitted the pull request. You can find the details: #446
Please let me know your thoughts.
Thanks.
Giorgio

[XhmikosR]

Closing since #446 has been merged.