Make tools Document-scoped instead of Window-scoped

It's important that tools are document-scoped. Most of the time Window/Navigator and Document are 1:1, however navigations away from the initial about:blank Document share a Window object, which complicates things.

The case where this is observable is when you register tools with the initial about:blank Document, and then navigate away from it. Per the current spec, after the navigation, calls to navigator.modelContext return the same object that holds the same map of tools, which means tools are effectively shared across this navigation.

I recently caught this bug in Chromium when working on the iframe + permission policy implementation, and ended up changing Blink's implementation such that:

The backing ModelContext interface object is stored on Document instead of Navigator
The navigator.modelContext IDL getter doesn't just return the same object; instead it consults its Window's active Document, and returns its ModelContext object. It returns null if the Window isn't available (detached document) or if the document isn't fully active (bf-cache).

I'll update the spec to agree with this.

Follow-up: API placement

An oddity of the above is that the API is effectively scoped to the Document, yet it lives off of navigator. I personally never liked putting things on navigator, and would recommend that we do one of two things:

Move it to Document, giving us document.modelContext. This seems more intuitive
Move it to Window. This has the same scoping oddity as Navigator since both are 1:1, but it follows the guidance in New principle: Avoid adding (non-constructor) functions to the global scope w3ctag/design-principles#426 that most editors seem to have expressed, which is hanging things off of the global instead of a weird namespace like navigator

I agree document is the most intuitive as far as web pages go. If we eventually do implement WebMCP in service workers though, I'm not sure where the best home for modelContext would be, if not Navigator. Maybe self?

Good point about eventual Worker-exposed tools. The global (self) would make sense to cater to all contexts, but if the options really becomes self vs navigator, I'm wondering if we should even bother moving it at all...

The global (i.e. self, window) may be the right compromise here. We could expose the modelContext namespace there but use the currently active document as the backing storage so that tools aren't pesisted across navigations.

Hmm, but that's no different from keeping it on navigator, except for the fact that self is just more "general", but with more risk of collision.

I spoke with the TAG and they recommended that we move the modelContext object to document, which I am supportive of, with a still-reasonable path for extending to workers in the future: w3ctag/design-reviews#1231 (comment). Does anyone object?

SGTM. Thanks for bringing this to the TAG.

I do think self.modelContext could be potentially confusing given window.self in https://html.spec.whatwg.org/multipage/nav-history-apis.html#dom-self but we'll see. I won't oppose to document.modelContext.

Well self.modelContext would mean the same thing as window.modelContext, since they are the same object. But lots of APIs hang off of window without too much confusion. Do you think that's alright?

I meant some developers (or agents nowadays) could be confused because they see self.modelContext without realizing they're in a worker context and start using it now in a window context which suddenly doesn't work because window.self.modelContext is not a thing IIUC, only window.self.document.modelContext right?

That's correct. But you'll have to know what context you're in even if we put the API on self. You need to know that just because self.modelContext exists, you can't always run:

self.modelContext.registerTool({
  name: "scrape_dom",
  description: "the DOM scraper"
  async execute() => document.querySelector('body').textContent;
})

because the DOM doesn't exist in workers.

WebMCP: Expose document.modelContext

chore: bump @runtypelabs/webmcp-polyfill to ^0.3.0 (document.modelCon…

feat(webmcp-polyfill): install on document.modelContext per WebMCP PR #…

Bug 2042248 [wpt PR 60158] - WebMCP: Expose document.modelContext, a=…

feat(widget): WebMCP consumption — snapshot page tools per turn, exec…

Align WebMCP imperative API with Document-scoped modelContext

refactor(webmcp): migrate from navigator.modelContext to document.mod…

Bug 2042248 [wpt PR 60158] - WebMCP: Expose document.modelContext, a=…

Navigation Menu

Repository navigation

Make tools Document-scoped instead of Window-scoped #173

Follow-up: API placement

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Make tools Document-scoped instead of Window-scoped #173

Description

Follow-up: API placement

Activity

bwalderman commented on Apr 28, 2026

domfarolino commented on May 1, 2026

bwalderman commented on May 1, 2026

domfarolino commented on May 18, 2026

domfarolino commented on May 20, 2026

domfarolino commented on May 20, 2026

bwalderman commented on May 21, 2026

beaufortfrancois commented on May 21, 2026

domfarolino commented on May 21, 2026

beaufortfrancois commented on May 22, 2026

domfarolino commented on May 22, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions