Intent to Ship: Deprecate Mutation Events

600 views
Skip to first unread message

Mason Freed

unread,
May 15, 2024, 3:03:47 PMMay 15
to blink-dev

Contact emails

mas...@chromium.org

Explainer

None

Specification

https://w3c.github.io/uievents/#legacy-event-types

Summary

Mutation Events, including `DOMSubtreeModified`, `DOMNodeInserted`, `DOMNodeRemoved`, `DOMNodeRemovedFromDocument`, `DOMNodeInsertedIntoDocument`, and `DOMCharacterDataModified`, are quite bad for page performance, and also significantly increase the complexity of adding new features to the Web. These APIs were deprecated from the spec (https://w3c.github.io/uievents/#legacy-event-types) in 2011, and were replaced (in 2012) by the much better-behaved Mutation Observer API. Usage of the obsolete Mutation Events must now be migrated to Mutation Observer. Mutation event support will be disabled by default starting in Chrome 127, around July 30, 2024. Code should be migrated before that date to avoid site breakage. If more time is needed, there are a few options: - The Mutation Events Deprecation Trial (https://developer.chrome.com/origintrials/#/view_trial/919297273937002497) can be used to re-enable the feature for a limited time on a given site. This can be used through Chrome 134, ending March 25, 2025. - A MutationEventsEnabled enterprise policy (https://chromeenterprise.google/policies/#MutationEventsEnabled) can also be used for the same purpose, also through Chrome 134. Please see this blog post for more detail: https://developer.chrome.com/blog/mutation-events-deprecation Report bugs here: https://issues.chromium.org/new?component=1456718&template=1948649



Blink component

Blink>DOM

Search tags

MutationEventDOMSubtreeModifiedDOMNodeInsertedDOMNodeRemovedDOMNodeRemovedFromDocumentDOMNodeInsertedIntoDocumentDOMCharacterDataModified

TAG review

None

TAG review status

Not applicable

Chromium Trial Name

MutationEvents

Origin Trial documentation link

https://developer.chrome.com/blog/mutation-events-deprecation

WebFeature UseCounter name

kDOMNodeRemovedEvent

Risks



Interoperability and Compatibility

There are technically 9 Mutation Events, but Chromium only implements 6 of them. Their use counters vary significantly: - DOMNodeInsertedIntoDocument: 0.008% - DOMNodeRemovedFromDocument: 0.009% - DOMCharacterDataModified: 0.011% - DOMNodeRemoved: 0.73% - DOMSubtreeModified: 0.68% - DOMNodeInserted: 1.086% Chrome has shipped an experiment since M124 that disables all Mutation Events for 99% of users of Canary, Dev, and Beta versions of Chrome. Very few bugs have been filed in the intervening months, and all that were filed have been resolved quickly via the site owner making changes to not rely on the deprecated events. This gives me significant confidence that removing the events will not be as big of a deal as the use counters would suggest. Still, due to the still-high numbers, extreme care will be taken in the removal process. I plan to disable the events via Finch only, so that if issues are encountered, Finch will be a safe way to re-enable the events. Additionally, there are the deprecation trial and enterprise policies to offer an easy relief valve for affected sites.



Gecko: Positive (https://github.com/mozilla/standards-positions/issues/807) "very strong positive position"

WebKit: No signal (https://github.com/WebKit/standards-positions/issues/192)

Web developers: No signals

Other signals:

Activation

This npm package attempts to polyfill Mutation Events using Mutation Observer: https://www.npmjs.com/package/mutation-events.



WebView application risks

Does this intent deprecate or change behavior of existing APIs, such that it has potentially high risk for Android WebView-based applications?

None



Debuggability



Will this feature be supported on all six Blink platforms (Windows, Mac, Linux, ChromeOS, Android, and Android WebView)?

Yes

Is this feature fully tested by web-platform-tests?

No

Flag name on chrome://flags

mutation-events

Finch feature name

MutationEvents

Requires code in //chrome?

False

Tracking bug

https://crbug.com/1446498

Estimated milestones

Shipping on desktop127
Origin trial desktop first124
Origin trial desktop last134
Shipping on Android127
OriginTrial Android last134
OriginTrial Android first124
Shipping on WebView127
OriginTrial webView last134
OriginTrial webView first124


Anticipated spec changes

Open questions about a feature may be a source of future web compat or interop issues. Please list open issues (e.g. links to known github issues in the project for the feature specification) whose resolution may introduce web compat/interop risk (e.g., changing to naming or structure of the API in a non-backward-compatible way).

None

Link to entry on the Chrome Platform Status

https://chromestatus.com/feature/5083947249172480?gate=5111010140094464

Links to previous Intent discussions

Intent to Deprecate: https://groups.google.com/a/chromium.org/g/blink-dev/c/qDsKRU-cQ_4/m/isA1mZ_aAAAJ

Intent to Experiment: https://groups.google.com/a/chromium.org/g/blink-dev/c/z-VIfSOco4k/m/KDz9c_goAAAJ


This intent message was generated by Chrome Platform Status.

Yoav Weiss (@Shopify)

unread,
May 15, 2024, 9:27:20 PMMay 15
to Mason Freed, blink-dev
1% is a *lot*. Did UKM reveal anything interesting about this usage? Do we know if all of it is driven by site content, vs e.g. extensions?
--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAM%3DNeDjonGju3YX1WkXtEJrMGLo4bH9AqtwV0QoqvopdGNioAg%40mail.gmail.com.

Vladimir Levin

unread,
May 16, 2024, 12:36:19 AMMay 16
to Yoav Weiss (@Shopify), Mason Freed, blink-dev
I recall that some of this usage was feature detected: if mutation events are supported, use them; otherwise, use something else. Unfortunately, that makes it difficult to estimate the expected number of breakages. I agree though that it would be nice to understand the type of usage that still exists and the likelihood of real breakage


Mason Freed

unread,
May 16, 2024, 11:56:59 AMMay 16
to Vladimir Levin, Yoav Weiss (@Shopify), blink-dev

On Wed, May 15, 2024 at 9:36 PM Vladimir Levin <vmp...@chromium.org> wrote:
I recall that some of this usage was feature detected: if mutation events are supported, use them; otherwise, use something else. Unfortunately, that makes it difficult to estimate the expected number of breakages. I agree though that it would be nice to understand the type of usage that still exists and the likelihood of real breakage

That's right - some of the usage is definitely feature-detected. I also believe other usage simply doesn't matter to the functioning of the site. I.e a listener is attached (which triggers the use counter) but it is either never fired or doesn't do anything material if it does fire. See below for a comment on breakage.

P.S. Congrats on being added to the API owners. Thanks for your service. :-)
 
On Wed, May 15, 2024 at 9:27 PM Yoav Weiss (@Shopify) <yoav...@chromium.org> wrote:
1% is a *lot*. Did UKM reveal anything interesting about this usage? Do we know if all of it is driven by site content, vs e.g. extensions? 

I totally agree, 1% is a ton of usage, so it's right to be very careful and concerned about this deprecation. Note that deprecating things with this level of usage isn't unprecedented, as my team and I have successfully (and without major breakage) removed Web Components v0 with >2% usage, and event.path with close to 20% usage. But still, let's be sure we're taking all due precaution.

I looked into the UKM data about three months ago, before I started the experiment to disable all mutation events on Canary/Dev/Beta. I looked at the top ~30 UKM hits and dug into the site's code to see what the usage was. Many (~40% or so?) of the top sites usage was due to quilljs which has since updated their code to not rely on mutation events. Another maybe 10% was due to a Sharepoint 2016 mquery.js utility, for which several folks have requested support from MS, but it's a bit unclear what the plan is. The rest of the sites appeared to have bespoke code looking at mutation events.

You asked about extensions, which is a good question. I don't have a great way to track extensions via UKM, at least that I know of. Let me know if you do! I did receive one bug report that an extension was using mutation events, and the extension author quickly patched the extension. 

Very importantly, on literally none of the sites I investigated did I find any broken functionality. That includes the quilljs and mquery sites I mentioned above. Of course, I'm not an expert on those particular sites, and some aren't in my native language. But I could not find the effect of turning off mutation events. Similarly, I've been running my own browser with mutation events disabled for over a year now, and I have yet to find any site with broken functionality. And again, most convincingly to me, I've had these events disabled for all of Canary, Dev, and Beta for the better part of three months, and I've only received the one bug mentioned above about an extension. While that's not a guarantee that nothing will break, of course, I view it as a very strong sign that the effect of turning off these events will be less than what the 1% use counter would suggest.

And finally, of course, assuming I'm approved to disable in M127, I'll be very mindful of breakage and will flip the events back on immediately in the case that there is more breakage than I'm expecting.

Let me know if anything else would help make the case that we should go forward with this.

Thanks,
Mason

Vladimir Levin

unread,
May 16, 2024, 2:00:13 PMMay 16
to Mason Freed, Yoav Weiss (@Shopify), blink-dev
On Thu, May 16, 2024 at 11:56 AM Mason Freed <mas...@chromium.org> wrote:

On Wed, May 15, 2024 at 9:36 PM Vladimir Levin <vmp...@chromium.org> wrote:
I recall that some of this usage was feature detected: if mutation events are supported, use them; otherwise, use something else. Unfortunately, that makes it difficult to estimate the expected number of breakages. I agree though that it would be nice to understand the type of usage that still exists and the likelihood of real breakage

That's right - some of the usage is definitely feature-detected. I also believe other usage simply doesn't matter to the functioning of the site. I.e a listener is attached (which triggers the use counter) but it is either never fired or doesn't do anything material if it does fire. See below for a comment on breakage.

P.S. Congrats on being added to the API owners. Thanks for your service. :-)

Thanks!
 
 
On Wed, May 15, 2024 at 9:27 PM Yoav Weiss (@Shopify) <yoav...@chromium.org> wrote:
1% is a *lot*. Did UKM reveal anything interesting about this usage? Do we know if all of it is driven by site content, vs e.g. extensions? 

I totally agree, 1% is a ton of usage, so it's right to be very careful and concerned about this deprecation. Note that deprecating things with this level of usage isn't unprecedented, as my team and I have successfully (and without major breakage) removed Web Components v0 with >2% usage, and event.path with close to 20% usage. But still, let's be sure we're taking all due precaution.

I looked into the UKM data about three months ago, before I started the experiment to disable all mutation events on Canary/Dev/Beta. I looked at the top ~30 UKM hits and dug into the site's code to see what the usage was. Many (~40% or so?) of the top sites usage was due to quilljs which has since updated their code to not rely on mutation events. Another maybe 10% was due to a Sharepoint 2016 mquery.js utility, for which several folks have requested support from MS, but it's a bit unclear what the plan is. The rest of the sites appeared to have bespoke code looking at mutation events.

Is Sharepoint 10% of the 1% usage? According to the thread you linked they will fix it in a Sept 2024 release but seem like they won't backport the fix to previous versions. That seems a bit risky, but also I'm not sure what the breakage looks like and as you say, things seem to work.


You asked about extensions, which is a good question. I don't have a great way to track extensions via UKM, at least that I know of. Let me know if you do! I did receive one bug report that an extension was using mutation events, and the extension author quickly patched the extension. 

Very importantly, on literally none of the sites I investigated did I find any broken functionality. That includes the quilljs and mquery sites I mentioned above. Of course, I'm not an expert on those particular sites, and some aren't in my native language. But I could not find the effect of turning off mutation events. Similarly, I've been running my own browser with mutation events disabled for over a year now, and I have yet to find any site with broken functionality. And again, most convincingly to me, I've had these events disabled for all of Canary, Dev, and Beta for the better part of three months, and I've only received the one bug mentioned above about an extension. While that's not a guarantee that nothing will break, of course, I view it as a very strong sign that the effect of turning off these events will be less than what the 1% use counter would suggest.

And finally, of course, assuming I'm approved to disable in M127, I'll be very mindful of breakage and will flip the events back on immediately in the case that there is more breakage than I'm expecting.

Is the plan to do a finch rollout, something like 1% stable increasing week by week? Or were you just thinking of enabling it in 127 without finch?
 

Mason Freed

unread,
May 17, 2024, 3:28:57 PMMay 17
to Vladimir Levin, Yoav Weiss (@Shopify), blink-dev
On Thu, May 16, 2024 at 11:00 AM Vladimir Levin <vmp...@chromium.org> wrote:
I looked into the UKM data about three months ago, before I started the experiment to disable all mutation events on Canary/Dev/Beta. I looked at the top ~30 UKM hits and dug into the site's code to see what the usage was. Many (~40% or so?) of the top sites usage was due to quilljs which has since updated their code to not rely on mutation events. Another maybe 10% was due to a Sharepoint 2016 mquery.js utility, for which several folks have requested support from MS, but it's a bit unclear what the plan is. The rest of the sites appeared to have bespoke code looking at mutation events.

Is Sharepoint 10% of the 1% usage? According to the thread you linked they will fix it in a Sept 2024 release but seem like they won't backport the fix to previous versions. That seems a bit risky, but also I'm not sure what the breakage looks like and as you say, things seem to work.

I don't have a great way to break down how much of the 1% is represented by the Sharepoint library, because it just shows up as a JS dependency on affected sites. And yes that's what the public thread there says, though I'm not sure how authoritative that is. I've reached out privately to MS to see if there's more info I can glean. Just to confirm, I can't "see" any breakage on those sites. The most "visible" thing, which is what gets folks to report issues like the Sharepoint one, is the console warning that mutation events are being used and might break. Those had the intended effect in all of these cases, which is a good thing. 
 
And finally, of course, assuming I'm approved to disable in M127, I'll be very mindful of breakage and will flip the events back on immediately in the case that there is more breakage than I'm expecting.

Is the plan to do a finch rollout, something like 1% stable increasing week by week? Or were you just thinking of enabling it in 127 without finch?

So I'm definitely planning to launch this via Finch, so I can be guaranteed that un-launching it that way will "work" for all platforms. But I could go either way on the question of whether to ramp up slowly or go directly to 100% with the 127 release. I was leaning toward 100% of 127 on stable release day, because I think that'll be the least confusing for people experiencing issues. I.e. they relaunch their browser into 127 and something breaks - they now understand what caused it. When the breakage starts on some random day, and isn't repeatable across computers, they have a harder time knowing they should report a bug. And I want to maximize the chance that issues get reported quickly.

Thanks,
Mason

Philip Jägenstedt

unread,
May 19, 2024, 11:19:00 AMMay 19
to Mason Freed, Vladimir Levin, Yoav Weiss (@Shopify), blink-dev
Hi Mason,

This is quite exciting! Mutation events is something I've long assumed we'd have to live with forever, but your findings here are extremely encouraging. Most compelling to me is (1) your analysis of UKM data and the lack of clear breakage on any of the ~30 checked sites, and (2) that disabling the events on canary, dev and beta only resulted in a single bug report. The previous success of Shadow DOM v0 and event.path deprecation also shows that use counter numbers aren't always a good proxy for risk of breakage.

In https://github.com/WebKit/standards-positions/issues/192 the point is made that there are other events that fire with the same timing as mutation events, so this removal doesn't unblock everything. Nevertheless, I share the assessment that mutation events "significantly increase the complexity of adding new features to the Web"  so if removal is within reach I think we should go for it. From https://github.com/mozilla/standards-positions/issues/807 it's clear that there is enthusiasm beyond the Chromium project too.

Rolling this out with Finch is definitely prudent, and I agree with the argument for going directly to 100% in 127 to make for a less confusing debugging experience.

LGTM1 to this plan, while being ready to adapt to things that come up in the process.

Best regards,
Philip

Domenic Denicola

unread,
May 20, 2024, 1:09:50 AMMay 20
to Philip Jägenstedt, Mason Freed, Vladimir Levin, Yoav Weiss (@Shopify), blink-dev
LGTM2. This is extremely exciting. I hope that in a year, the deprecation process is fully complete, and we get to enjoy deleting a lot of code/specs/maybe tests.

I agree with your instinct to go to 100% directly with the 127 release.

Mike Taylor

unread,
May 21, 2024, 9:37:18 AMMay 21
to Domenic Denicola, Philip Jägenstedt, Mason Freed, Vladimir Levin, Yoav Weiss (@Shopify), blink-dev

LGTM3.

I had a slight concern about the quilljs usage - even though they've minted a new version, we know that getting sites to update is a major hurdle. That said, after reading through the comments and linked issues on upstream repos (react-quill, etc) - nobody seems to be describing any breakage, they just want the warning to go away. :)

Mason Freed

unread,
May 21, 2024, 12:09:51 PMMay 21
to Mike Taylor, Domenic Denicola, Philip Jägenstedt, Vladimir Levin, Yoav Weiss (@Shopify), blink-dev
Thank you all! I will proceed cautiously. A few comments below...

On Tue, May 21, 2024 at 6:37 AM Mike Taylor <mike...@chromium.org> wrote:

I had a slight concern about the quilljs usage - even though they've minted a new version, we know that getting sites to update is a major hurdle. That said, after reading through the comments and linked issues on upstream repos (react-quill, etc) - nobody seems to be describing any breakage, they just want the warning to go away. :)

I agree that in all of the cases where I've seen public issues discussing this, it was just users saying there was a funny warning that made them uncomfortable, not reporting something "broken". Which is good on two fronts: 1) things might not break, and 2) console warnings do work sometimes!

On 5/20/24 1:09 AM, Domenic Denicola wrote:
LGTM2. This is extremely exciting. I hope that in a year, the deprecation process is fully complete, and we get to enjoy deleting a lot of code/specs/maybe tests.
I look forward to deleting that code/spec also! That's the dopamine reward at the end of all painful deprecations. 
I agree with your instinct to go to 100% directly with the 127 release.
Thanks.
On Mon, May 20, 2024 at 12:18 AM Philip Jägenstedt <foo...@chromium.org> wrote:
In https://github.com/WebKit/standards-positions/issues/192 the point is made that there are other events that fire with the same timing as mutation events, so this removal doesn't unblock everything. Nevertheless, I share the assessment that mutation events "significantly increase the complexity of adding new features to the Web"  so if removal is within reach I think we should go for it. From https://github.com/mozilla/standards-positions/issues/807 it's clear that there is enthusiasm beyond the Chromium project too.
The team working on the "state preserving atomic moves" API has managed to navigate around all of the other such synchronous events, leaving only mutation events in their way. So I actually do believe this removal unblocks a new, cool API that is in the works this year. 
Rolling this out with Finch is definitely prudent, and I agree with the argument for going directly to 100% in 127 to make for a less confusing debugging experience.
Thanks. At least two votes for straight-to-100%, so that's what I'll do.
LGTM1 to this plan, while being ready to adapt to things that come up in the process.
I will definitely be very careful in rolling this out.

Thanks,
Mason

Vladimir Levin

unread,
May 21, 2024, 12:31:19 PMMay 21
to Mason Freed, Mike Taylor, Domenic Denicola, Philip Jägenstedt, Yoav Weiss (@Shopify), blink-dev
On Tue, May 21, 2024 at 12:09 PM Mason Freed <mas...@chromium.org> wrote:
Thank you all! I will proceed cautiously. A few comments below...

On Tue, May 21, 2024 at 6:37 AM Mike Taylor <mike...@chromium.org> wrote:

I had a slight concern about the quilljs usage - even though they've minted a new version, we know that getting sites to update is a major hurdle. That said, after reading through the comments and linked issues on upstream repos (react-quill, etc) - nobody seems to be describing any breakage, they just want the warning to go away. :)

I agree that in all of the cases where I've seen public issues discussing this, it was just users saying there was a funny warning that made them uncomfortable, not reporting something "broken". Which is good on two fronts: 1) things might not break, and 2) console warnings do work sometimes!

On 5/20/24 1:09 AM, Domenic Denicola wrote:
LGTM2. This is extremely exciting. I hope that in a year, the deprecation process is fully complete, and we get to enjoy deleting a lot of code/specs/maybe tests.
I look forward to deleting that code/spec also! That's the dopamine reward at the end of all painful deprecations. 
I agree with your instinct to go to 100% directly with the 127 release.
Thanks.
On Mon, May 20, 2024 at 12:18 AM Philip Jägenstedt <foo...@chromium.org> wrote:
In https://github.com/WebKit/standards-positions/issues/192 the point is made that there are other events that fire with the same timing as mutation events, so this removal doesn't unblock everything. Nevertheless, I share the assessment that mutation events "significantly increase the complexity of adding new features to the Web"  so if removal is within reach I think we should go for it. From https://github.com/mozilla/standards-positions/issues/807 it's clear that there is enthusiasm beyond the Chromium project too.
The team working on the "state preserving atomic moves" API has managed to navigate around all of the other such synchronous events, leaving only mutation events in their way. So I actually do believe this removal unblocks a new, cool API that is in the works this year. 
Rolling this out with Finch is definitely prudent, and I agree with the argument for going directly to 100% in 127 to make for a less confusing debugging experience.
Thanks. At least two votes for straight-to-100%, so that's what I'll do.

FWIW, I think both strategies have pros and cons, but I do support the straight-to-100% in this case

Reply all
Reply to author
Forward
0 new messages