Repository navigation
Description
Description
Hi! Adam here from the WordPress project where we recently landed client-side media handling that relies on worker threads and SharedArrayBuffer and required document isolation. DIP worked out to be a much better solution for us that COOP/COEP headers where embeds and iframes broke.
I used Claude to collect the technical details here are reviewed for accuracy. Everything Claude-drafted is wrapped in <details> per the WPT AI policy.
web-features: document-isolation-policy
The rest of this description was drafted by Claude and checked against the spec, the WPT directory, and chromestatus.
Document-Isolation-Policy (DIP) is an HTTP response header that lets one document opt into cross-origin isolation by itself, without its embedder or its embedded content having to cooperate. It leans on out-of-process iframes for the isolation guarantee instead of the COOP + COEP header pair.
The practical difference: with COOP + COEP, every document in the frame chain has to agree, and the top-level document gives up cross-origin popups and unrestricted third-party embeds to get there. With DIP, a document that needs SharedArrayBuffer or WASM threads turns them on for itself, and the pages around it are unaffected.
In scope: the Document-Isolation-Policy header, its isolate-and-require-corp and isolate-and-credentialless values, the resulting crossOriginIsolated state, inheritance into dedicated and shared workers, and the report-only variant. The isolate-agent-cluster value and service worker behaviour are open questions rather than assumed in scope (see the roadmap).
Explainer: https://github.com/WICG/document-isolation-policy
Spec draft: https://wicg.github.io/document-isolation-policy/
TAG review: w3ctag/design-reviews#995
Tests: https://github.com/web-platform-tests/wpt/tree/master/html/document-isolation-policy (46 tests, all still named .tentative.; WebKit has been adding to them since October, eg. web-platform-tests/wpt#63601)
Rationale
The rationally below was drafted by Claude with fact checking and some editing by me:
Details
The COOP + COEP model has been available since late 2021 and is still painful enough that real products route around it. Sites are not asking for a new capability, they already have SharedArrayBuffer. They are asking to stop choosing between isolation and embedding. Two named cases, both already on the public standards position threads:
WordPress. Client-side media processing shipped in WordPress 7.1 on 2026-08-19. Release: https://wordpress.org/news/2026/08/mary-lou/ and dev note: https://make.wordpress.org/core/2026/07/22/client-side-media-processing-in-wordpress-7-1/
It uses wasm-vips to convert uploads to smaller images in the browser before upload, which both widens format support beyond what a typical PHP host offers and provides new capabilities hosts do not offer. That needs SharedArrayBuffer. But the post editor renders content in an iframe, some hosts render the whole admin panel in an iframe, and WordPress Playground renders an entire ephemeral site in an iframe. The feature was first built on COOP/COEP, hit exactly the frame-chain problem, and moved to DIP: WordPress/gutenberg#75991
WordPress now sends Document-Isolation-Policy: isolate-and-credentialless on block editor screens for Chromium 137+. Everywhere else the feature is unavailable, so Firefox and Safari users fall back to the server-side path. This is a released feature in the most widely deployed CMS on the web, with the capability already varying by browser.
Playground went as far as rewriting COOP/COEP into DIP to make it work: WordPress/wordpress-playground#3028
The mixed case is the one COEP cannot express at all: an isolated editor that still embeds a YouTube video. Details from @adamziel: mozilla/standards-positions#1074 (comment)
HDR photos are a second WordPress motivation, since gain map transcoding also runs through the WASM pipeline: WebKit/standards-positions#399 (comment)
Zoom. Zoom Meetings on web uses COOP/COEP to get SharedArrayBuffer for audio and video processing. Their other products (Docs, Whiteboard) deliberately do not, because it would break embedding YouTube or Asana. That means Zoom cannot offer Meetings inside its own collaboration suite. The Zoom Web SDKs are the mirror image: third-party developers embedding Zoom alongside other iframes in education, healthcare, and finance products. Full comment from @tommygaessler: WebKit/standards-positions#399 (comment)
Related interop demand: #1226 proposed allow="cross-origin-isolated" on iframes for Interop 2026, a narrower attempt at the same underlying problem. It arrived after the window closed and was not carried forward.
Standards positions.
- Mozilla: positive, resolved 2026-08-10. Document-Isolation-Policy mozilla/standards-positions#1074
- WebKit: no formal position yet, but the only remaining concern is venue. Document-Isolation-Policy WebKit/standards-positions#399
On 2026-09-26 @annevk wrote that the portability concerns have been addressed and that the remaining concern is venue: the work should be upstreamed to Fetch and HTML. WebKit/standards-positions#399 (comment). The concerns: portability and concerns: device independence labels were replaced with concerns: venue the same day. For background, the device independence concern came from Chrome's initial desktop-only launch plan; Chrome revised it and shipped to all Android devices: WebKit/standards-positions#399 (comment).
Worth flagging: https://chromestatus.com/feature/5141940204208128 still records the Safari view as "Negative", with a note describing the since-revised Android plan. That no longer matches the WebKit thread and is the first thing most people check.
Current state.
- Chrome and Edge: shipped in 137 on desktop and 146 on Android, after an origin trial through 136.
- Firefox: not implemented. Implementation bug filed 2026-08-13: https://bugzilla.mozilla.org/show_bug.cgi?id=2063367. Since 2026-11-02 it blocks a Zoom webcompat bug (the browser version of Zoom showing a popup blocked error): https://bugzilla.mozilla.org/show_bug.cgi?id=2079463
- Safari: implementation in progress in WebKit, behind the off-by-default
DocumentIsolationPolicyEnabledpreference and only honored with site isolation enabled. Tracking bug: https://bugs.webkit.org/show_bug.cgi?id=325516. Landed so far: header parsing andisolate-and-require-corpchecks (https://bugs.webkit.org/show_bug.cgi?id=326321), agent cluster separation (https://bugs.webkit.org/show_bug.cgi?id=326665), blob document inheritance (https://bugs.webkit.org/show_bug.cgi?id=327090), and cross-origin isolated processes (https://bugs.webkit.org/show_bug.cgi?id=327253). - WPT: 46 tests, all
.tentative.. On the September aligned run, before the newer WebKit tests were added, Chrome and Edge passed 189 of 190 subtests on the current aligned run. Firefox nightly passed 123 of 190, but those are the subtests whose expected result does not depend on the header being honoured (credentials-omitted fetches, the missing-HTTPS case, and similar); the maincrossOriginIsolatedcase fails. Safari runs report harness errors rather than results. https://wpt.fyi/results/html/document-isolation-policy - web-features id:
document-isolation-policy, added in web-features 3.45.0 (Add Document-Isolation-Policy feature web-platform-dx/web-features#4561). Its support data comes from the BCD keyhttp.headers.Document-Isolation-Policy(Add Document-Isolation-Policy HTTP header mdn/browser-compat-data#30939). - The WICG spec repo has had no commits since April 2025, but WebKit's review produced spec issues covering the Fetch integration, workers, cross-origin iframes and agent clusters (Normative fixes to the Fetch integration and headers WICG/document-isolation-policy#10 through How workers obtain a document isolation policy WICG/document-isolation-policy#13, plus Editorial: fix typos and broken links WICG/document-isolation-policy#9). Upstreaming is tracked in Upstream Document-Isolation-Policy to HTML and Fetch WICG/document-isolation-policy#8.
Investigation Roadmap
Claude drafted the roadmap below. I'm new to the process here so I'm passing on this verbatim.
Details
This was first filed as an Investigation Effort and changed to a focus area proposal on 2026-10-15. Two of the essential criteria are not met yet: the spec is a WICG Community Group draft rather than a WHATWG or W3C Recommendation Track document, and all of the tests are still tentative. Steps, roughly in order:
-
Move the spec to a recognised venue. DIP changes agent cluster keying and document loading, so HTML and Fetch are the natural homes, and this is now WebKit's only remaining concern. Upstreaming is tracked in Upstream Document-Isolation-Policy to HTML and Fetch WICG/document-isolation-policy#8, and the spec issues from WebKit's review (Allow anyone to label these issues #10 through Typography bucket #13) are the groundwork for it. This is standards work and belongs in WHATWG, not in Interop.
-
Resolve the remaining WebKit questions.Done: the portability and device independence concerns were resolved on 2026-09-26, leaving venue (step 1). -
Get the tests out of tentative. The 46 existing tests are a real starting point, not a greenfield, and WebKit's implementation work is adding more. Once the spec has a stable home, they can be renamed and reviewed against it. Gaps to check while doing that:
- worker inheritance, including the shared worker cases Chromium still fails
- reporting under Report-Only: Reporting behavior between normal vs. Report-Only WICG/document-isolation-policy#6
- interaction with pages already isolated via COOP/COEP
- agent cluster keying between same-origin documents with and without DIP (the partial-deployment behaviour described in the rationale)
- the meta tag question: Document-Isolation-Policy Header via meta tag WICG/document-isolation-policy#3
-
File the WebKit implementation bug.Done: https://bugs.webkit.org/show_bug.cgi?id=325516, with implementation now underway. -
Register a web-features id.Done:document-isolation-policy. This lets future proposals and dashboards pick up standards positions and BCD data automatically. -
Settle
isolate-agent-cluster. What's "isolate-agent-cluster"? WICG/document-isolation-policy#5 is an open question about a value that is not clearly defined in the explainer. Either specify it or drop it from scope.
Upstreaming to HTML and Fetch is the main open dependency. One question for the Interop team: if that work is in progress but not finished by the selection deadline, does that rule DIP out for 2027, or could it be selected with upstreaming as a condition?
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsTodo
Activity
adamsilverstein commentedon Sep 3, 2026
cc: @tommygaessler @camillelamy @adamziel.
ai commentedon Sep 7, 2026
I also want to support this feature in Interop 2027 because it would be very handy for local-first apps (when we have SQLite which need
COOP/COEPheaders but can't workrequire-corpto load third-party images)tommygaessler commentedon Sep 24, 2026
Likewise, thank you @adamsilverstein . With Chrome/Edge supporting already, and Mozilla's position being marked as positive, I also am in favor to support in Interop 2027.
annevk commentedon Sep 25, 2026
Is there a plan for getting this properly standardized in time?
zcorpan commentedon Sep 25, 2026
@annevk not required for investigation efforts.
annevk commentedon Sep 25, 2026
Oh sorry, I missed the label. But then I'm not sure what this is for. I thought investigations were for areas with a poor specification and lack of interoperability. Not for something that just hasn't been standardized & implemented yet.
zcorpan commentedon Sep 25, 2026
I agree, the bulk of the roadmap appear to be general standardization.
adamsilverstein commentedon Sep 25, 2026
@annevk this is probably due to my being new to the process. Can you help me understand what the next step should actually be, maybe a link to a previous similar effort or documentation on the process? I'd love to contribute however I can - I don't know where to start though!
annevk commentedon Sep 26, 2026
This feature needs upstreaming to Fetch & HTML and then it would qualify as a Focus Area proposal, which seems more appropriate as I'm not sure what we'd investigate here. I'm not sure what timeline requirements Interop has around all that though.
adamziel commentedon Sep 28, 2026
Standardizing this would indeed be very useful for WordPress and WordPress Playground. Thank you for posting this @adamsilverstein, and thank you @annevk for clarifying the right path.
adamsilverstein commentedon Sep 28, 2026
Thanks for clarifying the path forward @annevk - that is extremely helpful!
Shall I go ahead and close this issue out since we are very unlikely to have the upstream work in place before this year's deadline, or shall I leave it open as a reference?
adamsilverstein commentedon Sep 28, 2026
I opened WICG/document-isolation-policy#8 to track upstreaming. I also opened a WebKit enhancement bug report: https://bugs.webkit.org/show_bug.cgi?id=325516
jgraham commentedon Oct 15, 2026
It would be helpful if someone could define a web-feature for this. That makes it easier to track related bugs / standards-positions / implementation status etc.
nairnandu commentedon Oct 15, 2026
Changing this to a focus area proposal
github-actions commentedon Oct 15, 2026
This comment was automatically generated based on the information you provided. Please don't edit it.
Below is additional information about the web feature (from the web-features project) which is referenced in your proposal.
If this doesn't accurately correspond to your proposal, please update your initial comment to include
web-features: <feature-id>.To find feature IDs, use the web-features explorer.
Feature Document-Isolation-Policy
Document-Isolation-PolicyHTTP header makes a document cross-origin isolated, giving it access to APIs such asSharedArrayBuffer, without requiring the document or those it embeds to sendCross-Origin-Opener-PolicyorCross-Origin-Embedder-Policyheaders.adamsilverstein commentedon Oct 21, 2026
Thanks @jgraham, good idea. I opened a PR to add it: web-platform-dx/web-features#4561
BCD didn't have the header yet either, so there is a companion PR for that: mdn/browser-compat-data#30939. Until that lands the web-features entry carries a hand-set status (Chrome/Edge 137, Chrome Android 146).
adamsilverstein commentedon Nov 6, 2026
Thanks again @jgraham for the web-features suggestion. I added the ID to the description and refreshed the rest of it.
A quick roundup from Claude: