Not a document API

[martinthomson]

If the information the API exposes is a property of the browser (or indeed the user), why use document rather than navigator?

[jkarlin]

It's always fun trying to figure out where these APIs belong :) We chose document because the result varies by the calling context due to filtering.

[martinthomson]

Yes, fun. The information source not being bound to the document is something that carries more weight (at least in my view).

As for conditional on context, calls to navigator.geolocation.getCurrentPosition() or navigator.mediaDevices.getUserMedia() produce results that depend on the calling context in some way, just to name two things that come to mind.

[jkarlin]

It's a good question. I brought it up to the TAG as part of the review w3ctag/design-reviews#726.

[domenic]

With my HTML editor hat on, window is the best place for such APIs. I'm not sure where people get the idea that navigator is a good namespace to put these things... seems like someone started doing that a long time ago and now it's being copied, but it never made sense. See also https://matrixlogs.bakkot.com/WHATWG/2022-05-01#L1

[bershanskiy]

Please consider this: using navigator.browsingTopics() will enable exposing Topics API to workers in the future (e.g., as WorkerNavigator.browsingTopics). Making Topics API usable in background contexts makes sense because a page or a frame might legitimately want to offload the main context by putting all the ad-selection logic into a background worker. Yes, document.browsingTopics() is asynchronous (and I'm really glad about it), but the site-provided ad-selection logic might be time-consuming and might be extracted into a worker. Message passing between main context and worker might not be very elegant (but admittedly not too bad).

[martinthomson]

@domenic, I'm not sure that it is a superstition. It's about asking the appropriate entity. If you see window as being a representation of the browser, then I guess window is the right thing. I had inferred (perhaps incorrectly) that navigator was the browser and window was the browsers projection of the current tab.

[domenic]

Mmm, they're both global objects to the current tab, so just using the actual global object instead of nesting under navigator makes the most sense.

[jkarlin]

So how does window.browsingTopics sound to folks? window.topics might be a bit risky in terms of collisions. @slightlyoff for input as well.

[RByers]

+1 for avoiding window.topics. I don't want a repeat of window.Report and given only a small number of developers are likely to ever write code calling this API, I don't think it's worth worrying about brevity.

[jkarlin]

In terms of precedent, I see cookies are on document (I think this is actually originally why floc, and now topics are there as they're also cross-site information based on origin) and so are private state tokens.

Is there a document written somewhere with guidance with what should hang off of what object? Wiithout such a reference I'm unclear on how we should proceed here and would prefer to just keep it on document.