Instruction file imported from w3c/encrypted-media (.github/instructions/html.instructions.md). Copyright stays with the author.

Review Instructions for the Encrypted Media Extensions Specification

You are reviewing pull requests to a W3C specification. Follow the rules in the sections below. Flag issues, uncertainties, and inconsistencies, and make concrete suggestions.

This repository hosts the main EME spec (encrypted-media-respec.html) plus several ReSpec registries: hdcp-version-registry-respec.html, and the initdata / stream format registries under format-registry/. These rules apply to all of them.

1. ReSpec linking is correct and consistent (no raw <a> for internal links).
2. Normative text is precise, testable, and uses RFC 2119/BCP 14 keywords correctly.
3. Algorithms are deterministic, fully defined, and implementable.
4. WebIDL is valid and matches algorithm behavior.
5. CDM boundary is respected: the spec does not mandate unobservable CDM internals, and does not leave user-agent-observable behaviour to "the CDM" without a testable hook.
6. Clear Key baseline is preserved: new normative behaviour must be implementable for the mandatory Clear Key system.
7. Security, privacy (including fingerprinting), a11y, and i18n concerns are not obviously violated.
8. Commit messages follow the project's conventions. If you are unable to perform a comprehensive review of a PR, prioritize checking these key areas.

• [[HTML]] — HTML Standard (HTMLMediaElement, media pipeline, mixed content hooks)
• [[Infra]] — Infra Standard
• [[WEBIDL]] — Web IDL Standard
• [[ECMA-262]] — ECMAScript
• [[PERMISSIONS-POLICY]] — Permissions Policy (EME is gated by the encrypted-media policy-controlled feature, default allowlist 'self')
• [[MIXED-CONTENT]] — Mixed Content
• [[MEDIA-SOURCE]] — Media Source Extensions
• [[ENCODING]] — Encoding
• [[COOKIES]] — HTTP State Management (for Persistent Data clearing parity)
• [[CENC]] — ISO/IEC 23001-7 Common Encryption (defined in localBiblio of the main spec and the mp4 stream-format registry)
• [[RFC2119]]
• [[RFC6381]], [[RFC6838]] — media type and codec parameters
• [[RFC7515]], [[RFC7517]] — JOSE / JWK (Clear Key license format)
• [[ENCRYPTED-MEDIA]] — the main EME spec; used by sibling registry documents to cite back into it
• EME registries: [[EME-INITDATA-REGISTRY]], [[EME-STREAM-REGISTRY]], [[EME-INITDATA-CENC]], [[EME-INITDATA-KEYIDS]], [[EME-INITDATA-WEBM]], [[EME-HDCP-VERSION-REGISTRY]]

The spec's ReSpec xref config is ["dom", "html", "infra", "mimesniff", "webaudio"]. Of those, html and infra are also cited directly via [[HTML]] and [[Infra]]; dom, mimesniff, and webaudio are available for cross-references into their defined terms but are not themselves cited with [[SHORTNAME]].

• Normative requirements are typically addressed to "the user agent", "implementations", "user agent and [=CDM=] implementations", or (less often) "[=CDM=]s", "[=Key System=] implementations", and "applications". All of these are legitimate targets — do not mechanically rewrite every CDM-addressed MUST into a user-agent MUST. Do flag requirements that pick an incoherent target (e.g., addressing the application when the behaviour is only implementable by the user agent).
• When the spec delegates to the CDM (e.g., "let the CDM process the license"), the user-agent-observable outcome (promise resolution, event dispatch, key status, session close reason) must still be specified so a test can be written.
• Flag any step that mandates CDM internals the user agent cannot observe or test (no way to tell whether the CDM complied).
• Flag any user-agent-observable behaviour that is left entirely to "the CDM" without a testable hook.

• Any new mandatory feature must be implementable under Clear Key, not only under proprietary systems.
• When adding a new key-system-configurable property, consider what the Clear Key answer is, and check the Clear Key section is updated accordingly.
• Behaviour that assumes hardware-backed protection (e.g., HDCP enforcement, secure decoders) should be optional, with sensible Clear Key defaults.

• Hooks into HTML concepts (blocked-media-element, current-playback-position, readyState, HAVE_ENOUGH_DATA, fatal-decode-error, timed text tracks, media data) should use data-cite="html#…" fragments that are already established in this spec rather than new ad-hoc anchors.
• Flag changes that fork HTML's observable behaviour rather than extending it.
• Event ordering and promise resolution must be compatible with HTML's task queue model — prefer [=queue a task=] and [[Infra]] operations.
• Any change to blocked/unblocked transitions or to what counts as a decode error should be cross-checked against the HTML Standard text it references.

• HDCP Version Registry (hdcp-version-registry-respec.html)
• Initialization Data Format Registry (format-registry/initdata/) with entries for cenc, keyids, webm
• Stream Format Registry (format-registry/stream/) with entries for mp4, webm

• security-privacy-questionnaire.md — update when changing what information is exposed, persistence, fingerprinting surface, or platform-level data flow.
• hdcp-detection-explainer.md — update when changing getStatusForPolicy() or HDCP-related behaviour.
• key-rotation.md — update when changing session lifecycle, key status semantics, or rotation flow.
• If a PR changes observable behaviour but leaves these files stale, flag it.

Normative changes: Commit messages for normative changes normally have no prefix.

Breaking normative changes: For normative changes that are breaking (i.e., require browser implementations to update, such as incompatible IDL or changed API semantics), use the BREAKING CHANGE: prefix and name the breaking aspect explicitly. See below.

Examples that can be improved:

• fix stuff
• update spec
• should work now
• edit: tweaks