Skip to content

Document Isolation Policy #1332

Open
Open

Description

@adamsilverstein

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.

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.

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:

  1. 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.

  2. Resolve the remaining WebKit questions. Done: the portability and device independence concerns were resolved on 2026-09-26, leaving venue (step 1).

  3. 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:

  4. File the WebKit implementation bug. Done: https://bugs.webkit.org/show_bug.cgi?id=325516, with implementation now underway.

  5. Register a web-features id. Done: document-isolation-policy. This lets future proposals and dashboards pick up standards positions and BCD data automatically.

  6. 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?

Activity

  1. adamsilverstein commented on Sep 3, 2026

    @adamsilverstein
    Author
  2. ai commented on Sep 7, 2026

    @ai

    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/COEP headers but can't work require-corp to load third-party images)

  3. tommygaessler commented on Sep 24, 2026

    @tommygaessler

    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.

  4. annevk commented on Sep 25, 2026

    @annevk
    Member

    Is there a plan for getting this properly standardized in time?

  5. zcorpan commented on Sep 25, 2026

    @zcorpan
    Member

    @annevk not required for investigation efforts.

  6. annevk commented on Sep 25, 2026

    @annevk
    Member

    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.

  7. zcorpan commented on Sep 25, 2026

    @zcorpan
    Member

    I agree, the bulk of the roadmap appear to be general standardization.

  8. adamsilverstein commented on Sep 25, 2026

    @adamsilverstein
    Author

    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.

    @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!

  9. annevk commented on Sep 26, 2026

    @annevk
    Member

    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.

  10. adamziel commented on Sep 28, 2026

    @adamziel

    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.

  11. adamsilverstein commented on Sep 28, 2026

    @adamsilverstein
    Author

    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?

  12. adamsilverstein commented on Sep 28, 2026

    @adamsilverstein
    Author

    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

  13. jgraham commented on Oct 15, 2026

    @jgraham
    Contributor

    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.

  14. nairnandu commented on Oct 15, 2026

    @nairnandu
    Contributor

    Changing this to a focus area proposal

  15. github-actions commented on Oct 15, 2026

    @github-actions

    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

    • ID: document-isolation-policy
    • Name: Document-Isolation-Policy
    • Description: The Document-Isolation-Policy HTTP header makes a document cross-origin isolated, giving it access to APIs such as SharedArrayBuffer, without requiring the document or those it embeds to send Cross-Origin-Opener-Policy or Cross-Origin-Embedder-Policy headers.
    • Baseline status: Limited Availability
    • Developer signals: 0 votes (details)
    • More information: See the web-features explorer
  16. adamsilverstein commented on Oct 21, 2026

    @adamsilverstein
    Author

    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.

    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).

  17. adamsilverstein commented on Nov 6, 2026

    @adamsilverstein
    Author

    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:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions