Repository navigation
Question: How should Document-scoped objects interact with window.navigator? #1231
Description
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.modelContextshould 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 webmachinelearning/webmcp#173 and webmachinelearning/webmcp#177.
Penny for your thoughts?
Track conversations at https://tag-github-bot.w3.org/gh/w3ctag/design-reviews/1231
Activity
christianliebel commentedon May 20, 2026
@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 (w3ctag/design-principles#448) to provide guidance on this question. Our response draws on that discussion and on the HTML Standard, which states:
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 newDocumentobject is created on every navigation anyway.We'd therefore recommend
document.modelContext. Should WebMCP later gain worker support, a worker-onlyself.modelContextcould be added. There's also precedent for this pattern: theFontFaceSetAPI is exposed asdocument.fontsand asself.fontsin workers (see TheFontFaceSourcemixin).WebMCP: Expose document.modelContext
WebMCP: Expose document.modelContext
WebMCP: Expose document.modelContext
WebMCP: Expose document.modelContext
Bug 2042248 [wpt PR 60158] - WebMCP: Expose document.modelContext, a=âĶ
Bug 2042248 [wpt PR 60158] - WebMCP: Expose document.modelContext, a=âĶ
Bug 2042248 [wpt PR 60158] - WebMCP: Expose document.modelContext, a=âĶ
Bug 2042248 [wpt PR 60158] - WebMCP: Expose document.modelContext, a=âĶ
Bug 2042248 [wpt PR 60158] - WebMCP: Expose document.modelContext, a=âĶ