New principle: Document whether to add things to Document, Navigator, Window, or SomeOtherInterface

[jyasskin]

API designers often wonder how to namespace their new thing, and I don't think we have any existing guidance. #426 has some argument for and against using Window, but I think the principle should be broader than that. Some considerations:

Navigator "represent[s] the identity and state of the user agent", so it should hold objects that tend to be the same across different documents.

Document and Window are nearly equivalent, but adding things to Window means developers can use them without an object prefix, and they also risk colliding with things developers defined. Maybe we should say that infrequent use argues to put things on Document?

SomeOtherInterface.Thing and SomeOtherInterfaceThing are also nearly equivalent, as discussed in #426.

I'm sure other folks can think of more considerations. The more we can give these decisions a technical basis, the less likely they are to turn into prolonged bikeshedding discussions.

[bathos]

It may be worth noting that, ahead of considerations of semantic appropriateness, the lifecycles & relationships of candidate interfaces can impact whether they’re viable options. For example, the Window’s associated CustomElementRegistry couldn’t have belonged to the Document instead — though the conditions where this both occurs and is observed are uncommon, a Window’s associated Document can change one time (the registry could not have similarly changed underfoot soundly).

(I suppose a Document member could have steps like “return the associated Window’s associated Foo” to get around that, but personally I wouldn’t expect non-DOM/non-DOM-related specs to want to extend Document much anyway?)

[LeaVerou]

Completely agree about documenting guidance about this. Another consideration is whether the API in question may ever be useful in non-browser runtimes, we don't want to e.g. hang something on Navigator that may eventually become useful in Node and have to define a new API for it.

[domenic]

In addition to my points of view expressed in #426, let me comment specifically on the question of when each of Navigator, Document, and Window/WindowOrWorkerGlobalScope are appropriate. (The following are my opinions and don't reflect any larger consensus.)

• The default should be Window, or WindowOrWorkerGlobalScope for APIs that can work in workers.

• APIs that are tightly scoped to the original meaning of Navigator, i.e. data about the user agent or operating system environment, should go there.

  • Good examples: deviceMemory, hardwareConcurrency, language, userAgentData, webdriver.

  • Bad examples: contacts and scheduling (general web APIs that aren't device or OS-specific), serviceWorker and locks (definitely not user-agent wide; their behavior is intimately tied to the current origin), userActivation (similarly, very specific to the current Window).

  • Perhaps-borderline examples, but I think Navigator was the wrong choice: device APIs (usb, hid, keyboard), graphics-ish APIs (xr, gpu), and OS APIs that are sufficiently abstracted over by a web standard (clipboard, virtualKeyboard)

• APIs that are specifically about manipulating DOM structure and the node tree, or APIs that give info about the state of the currently-displayed document (such that you would expect completely different results after navigation), can go on Document

  • Good examples: activeElement, fragmentDirective, featurePolicy, URL (except the casing), startViewTransition(), pictureInPictureElement.

  • Borderline, probably-fine examples: browsingTopics(), fonts

  • Bad examples: implementation, hasStorageAccess(), requestStorageAccess()