CustomEvent documentation missing cloneInto information for web extension scripts

[marcustyphoon]

MDN URL

https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent

What specific section or headline is this issue about?

Section was removed in #9920.

What information was incorrect, unhelpful, or incomplete?

As per https://stackoverflow.com/a/46081249, CustomEvents with a non-string detail property will throw with "Permission denied to access property" in Firefox when they are used to communicate between the web extension content script isolated world and main world (this is the current state of the art in web extensions for cross-world communication, as I understand it). Calling cloneInto on the payload is required to avoid this.

There used to be a section describing this, but it was removed per #9920 (comment):

It was removed because the section talked about Firefox XUL/XPCOM extension code. We are trying to make MDN Web Docs only about Web technologies. XUL/XPCOM Firefox extensions don't exist anymore so it was removed for that reason. "privileged" referred to privileged code in an extension context.

XUL extensions may be gone, but WebExtensions certainly aren't, and this is the logical place where one who ran into this permission error would probably be looking for this information!

What did you expect to see?

An updated form of the removed passage, detailing this Firefox behavior and the cloneInto(/* whatever */, doc.defaultView) method required to use it, with the example changed to a web extension context and a note that Chromium does not have this behavior.

Link to the previous copy: https://github.com/mdn/content/blob/2279e5ae6c229c707a014a22aa1ec4635a0f981f/files/en-us/web/api/customevent/index.md

Do you have any supporting links, references, or citations?

No response

Do you have anything more you want to share?

Not sure if I should make an issue at https://github.com/w3c/webextensions/ describing this? It seems like a platform discrepancy that has gone largely uncommented-upon.

MDN metadata

Page report details

• Folder: en-us/web/api/customevent
• MDN URL: https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent
• GitHub URL: https://github.com/mdn/content/blob/main/files/en-us/web/api/customevent/index.md
• Last commit: b280ea1
• Document last modified: 2023-02-19T06:34:57.000Z

[wbamberg]

Do you think it would be OK to document this in the WebExtensions documentation, perhaps in the content scripts guide? This already has a section on communicating with the web page.

[marcustyphoon]

Yeah, for sure! This is certainly WebExtension-specific, to my knowledge (there are no isolated worlds in normal web code, right?)

That section could definitely use a description of the CustomEvent communication method as well as the iframe-based method to pass a secure MessageChannel (w3c/webextensions#77 (comment)), as those seem to be the current best practices but they aren't really documented anywhere.

[wbamberg]

@rebloor , what do you think?

[rebloor]

Seem reasonable to me - any comment @mdn/yari-content-mozilla-add-ons

[Rob--W]

Seem reasonable to me - any comment @mdn/yari-content-mozilla-add-ons

I'm in favor of documenting this more explicitly. Perhaps in the form of a small note stating the requirement when used in WebExtensions' content scripts to communicate with the web page, with a link to the extension documentation.