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, as well as at NoRedInk since 2025-11-03. There are at least two more companies using it in production as reported by people on Discord.

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
• The above Html.map improvements removes the need for the hidden _Json_equality function in elm/json, which was buggy. Closes elm/json#13, closes elm/json#15, closes elm/core#904. This PR might still be nice to merge, for those who encountered the bug but don’t have time to upgrade everything at once: elm/json#32 (PR)
• 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. Keeping our own tree of DOM 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 nodes in our own tree. While diffing in step 2, we simply make the changes immediately to the correct DOM node, by reading it from our own tree. Since there’s no walking of the real DOM tree, it doesn’t matter what changes a browser extension makes.

See New algorithm for pairing virtual DOM nodes for all the details.

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 three details should be equivalent, except less buggy.

The goal was to be 100 % backwards compatible. For some people, it is. For others, there are two changes that are in “breaking change territory”. The first one 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).

The second detail can be summarized as properties are diffed against the real DOM. This can uncover mistakes in Elm code, where the you forgot to set selected properly on options in a <select> element, for example.

The third detail can be summarized as setters should have getters on custom elements. Otherwise the setter will unnecessarily run on every render.

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).

[r-k-b]

We hit the Html.map bug (getting unexpected values like {$: 'UserBlurredRows'} instead of "some string" in unrelated msgs), this week in our ~200kloc Elm app.

@lydell's great work on elm-safe-virtual-dom helped a lot! 🎉 We're now using that to patch the files in elm_home in our build process, and that change will be in production within a few weeks.

[lydell]

This backwards compatibility (and some more later in the file) could be replaced by:

• Use _VirtualDom_toTest instead of decoding hacks elm-explorations/test#250, via lydell@d472bad
• elm-pages using _VirtualDom_toString via lydell@3f4648d + lydell@9a55ea3