#1231: Question: How should `Document`-scoped objects interact with `window.navigator`?

Visit on Github

Opened May 18, 2026

WebMCP provides navigator.modelContext, which returns an object that tracks a per-Document set of tools. This is unfortunate since navigator and window are both reused between the initial about:blank Document and the next same-origin document. This means navigator.modelContext should be "reset" after navigations like this, to return a different object, since the associated Document has changed.

Since modelContext is effectively per-Document, it actually makes more sense to just have it live on document.modelContext, but we wanted to keep the door open to adding this API in workers—particularly Service Workers—in the future, and since self.navigator is shared both contexts, the consistency of navigator felt nice.

Should we just move it to document.modelContext now, and if worker support ever comes, introduce self.modelContext or navigator.modelContext only for workers, since that's more honest about the scoping? Or should we keep this very Document-specific object on the navigator object in Window contexts for consistency with workers in the future, and just have it change values after navigation away from the initial about:blank Document?

This means navigator.modelContext should be "reset" after navigations like this, to return a different object, since the associated Document has changed.

Or, should we NOT reset the modelContext object, and instead keep it stable forever, and just "reset" its internal state when we detect that the document has changed from the initial about:blank Document to the next same-origin one after navigation. This is elegant and conceals most of the complexity from the developers, but it's doing a lot under the hood to conceal and work around the fact that everything is really document-scoped here, so maybe it's not worth it.

See also https://github.com/webmachinelearning/webmcp/issues/173 and https://github.com/webmachinelearning/webmcp/pull/177.

Penny for your thoughts?

<!-- Content below this is maintained by @w3c-tag-bot -->

Track conversations at https://tag-github-bot.w3.org/gh/w3ctag/design-reviews/1231

Discussions

Log in to see TAG-private discussions.

Comment by @christianliebel May 20, 2026 (See Github)

@domfarolino Thanks for reaching out. We agree with you that if an API is effectively per-Document, it should live on document.

The TAG has been discussing a new design principle (https://github.com/w3ctag/design-principles/issues/448) to provide guidance on this question. Our response draws on that discussion and on the HTML Standard, which states:

Instances of Navigator represent the identity and state of the user agent (the client).

The model context does not fall into that category. Furthermore, the navigator-based alternative either pushes complexity onto implementations or conceals the document-scoped nature of the API behind reset logic. That doesn't seem worth it, especially given that a new Document object is created on every navigation anyway.

We'd therefore recommend document.modelContext. Should WebMCP later gain worker support, a worker-only self.modelContext could be added. There's also precedent for this pattern: the FontFaceSet API is exposed as document.fonts and as self.fonts in workers (see The FontFaceSource mixin).