Batch: Support browser extensions, Google Translate, fix Html.map, and more

[lydell]

Intro

This PR:

• Fixes basically all bugs related to the (virtual) DOM.
• Makes Elm work with browser extensions and Google Translate – and might be the first framework to do so. End users for the win!
• Does not change performance in any way that I’ve been able to measure.
• Is 99.99 % backwards compatible.
• Is used in production at Insurello since 2025-05-26.

For those who would like to use this PR in their own app – see https://github.com/lydell/elm-safe-virtual-dom.

The above link also explains exactly what is changed, in a way that should be somewhat understandable even if you’re not super into the real and virtual DOM.

Below is a more technical, condensed version of the above link.

Summary of changes and fixed issues

• A new algorithm for pairing virtual DOM nodes with the corresponding real DOM nodes, that should be robust against browser extensions and third-party scripts. It is in the code for the old algorithm where most crashes happen. Closes elm/html#44, closes elm/browser#121, closes elm/browser#66, closes elm/virtual-dom#147, closes Chrome extensions (Grammarly in our case) cause runtime errors #182
• Support for the page being translated, for example Google Translate. This requires the above change (being robust), and then a little bit of extra code to make sure that translated text isn’t left behind on the page, and so that translated text that should change actually updates.
• The Html.map bug where messages of the wrong type can appear in update functions is fixed, by completely changing how Html.map works. The old code was very clever and could theoretically skip more work in some cases, but was also a bit difficult to understand. The new code is instead very simple, leaving little room for errors. Closes elm/virtual-dom#105, closes elm/virtual-dom#162, closes elm/virtual-dom#171, closes elm/virtual-dom#166 (PR), closes elm/html#160, closes elm/compiler#2069
• Improved Html.Keyed. The new algorithm is slightly smarter without losing performance, and uses the new Element.prototype.moveBefore API, if available, which allows moving an element on the page without “resetting” it (scroll position, animations, loaded state for iframes and video, etc.). Element.prototype.moveBefore was added to the specification recently. Closes elm/virtual-dom#175, closes elm/virtual-dom#178, closes elm/virtual-dom#183, closes Use Object.create(null) instead of {} to compute keyed diffs #180
• _VirtualDom_virtualize is now completed, making it usable in practice, for example for elm-pages. This means that server-side rendered pages no longer have to redraw the whole page when Elm initializes (which seems to have been the intention for _VirtualDom_virtualize all along, but hasn’t worked in practice).
• CSS custom properties, like --primary-color, can now be set with Html.Attributes.style "--primary-color" "salmon". CSS custom properties are incredibly useful for implementing theming (such as a dark mode). Closes elm/html#177, closes Allow CSS custom properties by using style.setProperty() #127.
• Svg.Attributes.xlinkHref no longer mutates the DOM on every single render, which caused flickering in Safari sometimes. This was due to an oversight in the diffing of namespaced attributes. Closes elm/virtual-dom#62, closes Fix diffing for namespaced attributes (Fixes #62) #159
• lazy no longer changes behavior for <input>. Closes Lazy is too lazy for inputs #189

The key changes

Making Elm work well with browser extensions, third-party scripts and page translators required three key changes.

1. Attaching DOM nodes on the virtual nodes

A render in Elm currently works like this:

1. Run view.
2. Diff with the previous virtual DOM, producing patches.
3. Attach a DOM node to each patch (_VirtualDom_addDomNodes).
4. Apply the patches.

It’s step 3 that can crash if a browser extension has changed the DOM.

With this PR, there is no more step 3. Instead, we store the DOM node on the virtual node. This means that we don’t even need patches. While diffing in step 2, we simply make the changes immediately to the correct DOM node. Since there’s no walking of the DOM tree, it doesn’t matter what changes a browser extension makes.

(However, since the same virtual DOM node can appear more than once in the tree, it’s a bit more complicated than that – see New algorithm for pairing virtual DOM nodes.)

2. Cooperating with page translators

There’s some new code for cooperating with page translators (Google Translate, as well as the translators built into Firefox and Safari). If the diff tells us to update a text node, but we detect that the text node in question has been translated, we tell the parent element of that text node to delete all text node children and re-render them. The page translator then kicks in and re-translates that element (taking the entire text of the element into account for a more accurate translation).

(Evan, if you remember us talking about this at Elm Camp 2024 – don’t worry, there is no “bug” introduced on purpose regarding <font> elements – they can still be created by Elm just fine. Google Translate oddly uses <font> tags for translated text, but it turned out to easy to tell the difference between <font> tags created by Elm and by others.)

3. Virtualizing more conservatively

When using Browser.document and Browser.application, Elm takes charge of <body>. Third-party scripts and browser extensions put things in <body> too, and crucially they might do so before Elm initializes. Currently, Elm virtualizes all elements in the mount node (<body>) in this case, which most likely results in the extra things in <body> added by third-party scripts and browser extensions being removed.

This PR changes the virtualization behavior to only virtualize text nodes, and elements that have the data-elm attribute, leaving everything else alone. I add data-elm automatically to all elements created by Elm, so if you server-side render your page by running your Elm code on the server, you get that for free without having to do anything. You can read more about how this can be used in practice at elm-pages PR 519.

Note: This is the reason the PR is only 99.99 % backwards compatible. Read more in the “Breaking” changes section below.

The other changes

So, I’ve talked about the key changes. But the “Summary of changes and fixed issues” section mentions a few more things. Why are they in this PR?

• Fixed Html.map: I needed to work on Html.map anyway to make it work with the new DOM node pairing algorithm.
• Improved Html.Keyed: Same thing.
• Virtualization: I needed to touch virtualization to support third-party scripts better, so I ended up going all the way with it.
• CSS custom properties and namespaced attributes: I needed to work on the diffing code anyway, since it now applies changes directly to DOM nodes instead of creating patches, and it was way easier to do all the changes in one batch and test it thoroughly once in production, rather than juggling with a stack of PR:s.
• lazy fix for inputs: It was incredibly easy to fix thanks to the other changes in this PR.

Detailed descriptions of changes

• New algorithm for pairing virtual DOM nodes
• Page translation support
• Html.map
• Html.Keyed
• Virtualization

“Breaking” changes

I haven’t changed the Elm interface at all (no added functions, no changed functions, no removed functions, or types). All behavior except one detail should be equivalent, except less buggy.

The goal was to be 100 % backwards compatible. For some people, it is. For others, there’s one change that is in “breaking change territory” which can be summarized as: Elm no longer empties the mount element. It’s easily fixed by adding the data-elm attribute to select elements in the HTML.

That’s how users will perceive it. In reality, the actual change is which elements are virtualized (to support third-party scripts better, as mentioned in the “Virtualizing more conservatively” section).

Read all about these “Breaking” changes in the safe-virtual-dom documentation.

Performance

• The well-known js-framework-benchmark includes Elm. I ran that Elm benchmark on my computer, with and without my PR:s, and got the same numbers (no significant difference).
• When testing with some large Elm applications at work, I couldn’t tell any performance difference with the PR:s. (Neither by eye nor by profiling.)
• Both the official elm/virtual-dom and my PR have O(n) complexity.
• The official elm/virtual-dom algorithm sometimes does more work, but other times this PR does more work. It seems to even out.

Related PR:s

• To make virtualization work 100 %: Use attributes instead of properties html#259
• Allow virtualization to set up <a> click listeners: Allow virtualization to set up link click listeners browser#137
• Fix debugger virtualization: Fix debugger virtualization browser#140
• Avoid requestAnimationFrame error loop on virtual DOM crashes: Fix animation frames browser#138

Code style

I’ve done my best to:

• Follow the existing code style.
• Not introduce any unnecessary changes.
• Use the same object key order when constructing objects (for performance).