update coop docs, particularly with -report-only

[steve-a-walsh]

Description

This PR adds comprehensive documentation for the Cross-Origin-Opener-Policy-Report-Only header and the report-to parameter, which were previously missing from the MDN documentation. The update includes a new reporting section explaining how to set up and use COOP violation reporting, enhanced syntax documentation showing both header variants, and practical examples demonstrating how to test policies using the report-only variant.

Motivation

The MDN documentation for Cross-Origin-Opener-Policy was missing critical information that developers need to effectively implement and monitor COOP policies:

1. Missing Cross-Origin-Opener-Policy-Report-Only header: This header is part of the official specification and is commonly used in production codebases to test policies before enforcement, but was completely absent from MDN documentation.

2. Missing report-to parameter: The specification supports a report-to parameter for both COOP headers (similar to CSP), allowing developers to monitor policy violations. This functionality is already being used in real-world implementations but was undocumented.

3. No reporting guidance: Developers had no documentation on how to set up reporting endpoints, what reports contain, or when they are generated.

These gaps made it difficult for developers to:

• Test COOP policies safely before enforcement
• Monitor policy violations in production
• Understand the complete COOP feature set as specified in the WHATWG HTML specification

The updates align the MDN documentation with the official specification (WHATWG HTML Living Standard, section 7.1.3) and provide developers with the complete information needed to implement COOP effectively.

Additional details

• Specification reference: WHATWG HTML Living Standard - Cross-Origin Opener Policies
  • Section 7.1.3.1: The headers (defines both COOP and COOP-Report-Only)
  • Section 7.1.3.3: Reporting (explains reporting functionality)
• Related MDN pages:
  • {{HTTPHeader("Reporting-Endpoints")}} - Required for setting up reporting endpoints
  • Reporting API - The underlying API used for COOP reports
• Real-world usage: The report-to parameter and Cross-Origin-Opener-Policy-Report-Only header are already in use in production codebases (e.g., for monitoring policy violations before enforcement)

Related issues and pull requests

Relates to #39880
Fixes #39432

[github-actions]

Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit

mdn-linter

---

[mdn-linter] _{reported by reviewdog 🐶}

content/files/en-us/web/http/reference/headers/cross-origin-opener-policy/COOP_ANALYSIS.md

Line 201 in 3b8037d

---

[mdn-linter] _{reported by reviewdog 🐶}

content/files/en-us/web/http/reference/headers/cross-origin-opener-policy/index.md

Line 21 in 3b8037d

- **`Cross-Origin-Opener-Policy`**: Enforces the policy and controls browsing context group behavior.

---

[mdn-linter] _{reported by reviewdog 🐶}

content/files/en-us/web/http/reference/headers/cross-origin-opener-policy/index.md

Line 116 in 3b8037d

- `Cross-Origin-Opener-Policy` controls the actual behavior

---

[mdn-linter] _{reported by reviewdog 🐶}

content/files/en-us/web/http/reference/headers/cross-origin-opener-policy/index.md

Line 206 in 3b8037d

- The actual policy is `unsafe-none` (permissive)

[github-actions]

[mdn-linter] _{reported by reviewdog 🐶}

Suggested change

	- **`Cross-Origin-Opener-Policy`**: Enforces the policy and controls browsing context group behavior.
	- **`Cross-Origin-Opener-Policy`**: Enforces the policy and controls browsing context group behavior.

[github-actions]

[mdn-linter] _{reported by reviewdog 🐶}

Suggested change

	- `Cross-Origin-Opener-Policy` controls the actual behavior
	- `Cross-Origin-Opener-Policy` controls the actual behavior

[github-actions]

[mdn-linter] _{reported by reviewdog 🐶}

Suggested change

	- The actual policy is `unsafe-none` (permissive)
	- The actual policy is `unsafe-none` (permissive)

[wbamberg]

Thanks for your PR! I know it's still in draft, but a couple of quick comments that might be helpful.

• if you have an editor that can install extensions, and you install the markdownlint and prettier extensions to make them auto-format on save (or just install the tools and run them manually before you commit) then you'll avoid a lot of these [mdn-linter] comments in the PR.
• since Cross-Origin-Opener-Policy and Cross-Origin-Opener-Policy-Report-Only are two different headers, they need two different pages. See for example Content-Security-Policy and Content-Security-Policy-Report-Only.

[Josh-Cena]

Also this in its proper form will fix #39432

[hamishwillee]

See also #39880 where I made a good start on this. I've been stalled for a while on #39880 (comment)

Usually violations that do reporting use the reporting API https://developer.mozilla.org/en-US/docs/Web/API/Reporting_API which has both a JavaScript side and an HTTP endpoint side. Normally you document the report format methodically in the reporting API part and then reference it from the HTTP header side.
This was the first case I ran into where reporting only had HTTP reporting defined, and it wasn't and still isn't clear if the API part exists

Given response time/bandwidth probably worth documenting this HTTP side much as you have done and and we can add the reporting API and "fix this up" later.

[steve-a-walsh]

Thanks for your PR! I know it's still in draft, but a couple of quick comments that might be helpful.

• if you have an editor that can install extensions, and you install the markdownlint and prettier extensions to make them auto-format on save (or just install the tools and run them manually before you commit) then you'll avoid a lot of these [mdn-linter] comments in the PR.
• since Cross-Origin-Opener-Policy and Cross-Origin-Opener-Policy-Report-Only are two different headers, they need two different pages. See for example Content-Security-Policy and Content-Security-Policy-Report-Only.

Thanks for the advice. I will make this adjustment based on how the CSP and CSP-RO pages relate to one-another. Sorry for the delays given the Thanksgiving holiday.

[steve-a-walsh]

See also #39880 where I made a good start on this. I've been stalled for a while on #39880 (comment)

Usually violations that do reporting use the reporting API https://developer.mozilla.org/en-US/docs/Web/API/Reporting_API which has both a JavaScript side and an HTTP endpoint side. Normally you document the report format methodically in the reporting API part and then reference it from the HTTP header side. This was the first case I ran into where reporting only had HTTP reporting defined, and it wasn't and still isn't clear if the API part exists

Given response time/bandwidth probably worth documenting this HTTP side much as you have done and and we can add the reporting API and "fix this up" later.

This is great, thanks! It would be beneficial to incrementally improve the docs here so at least more/better documentation is available to the developing public.