Controlled Frame API

When a controlledframe element element is inserted into a document whose browsing context is non-null, run the following steps:

1. If element’s src is not empty, then:

   1. Initialize a controlledframe given element.

When a controlledframe element element is removed from a document, run the following steps:

1. TODO: destroy element’s embedded navigable.

To initialize a controlledframe element element, run the following steps:

1. Assert that element’s embedded navigable is null.

2. Let group be a new browsing context group.

3. Let document be the second return value of creating a new browsing context and document given element’s node document, element, and group.

4. Let documentState be a new document state, whose document is document.

5. Let traversable be a new traversable navigable.

6. Initialize the navigable traversable given documentState.

7. Set traversable’s embedderParent to element.

8. Set element’s embedded navigable to traversable.

9. Let initialHistoryEntry be traversable’s active session history entry.

10. Set initialHistoryEntry’s step to 0.

11. Append initialHistoryEntry to traversable’s session history entries.

    These steps are needed to initialize History.length in the new navigable. This is an existing issue in the HTML Standard.

12. Set element’s contentWindow to document’s WindowProxy.

13. Navigate a controlledframe given element and element’s src.

To navigate a controlledframe element element given a USVString urlString, run the following steps:

1. If urlString is not an absolute-URL string, return.

2. Let url be the result of running the URL parser given urlString.

3. Let historyHandling be "auto".

4. If element’s embedded navigable’s active document is not completely loaded, then set historyHandling to "replace".

5. Navigate element’s embedded navigable to url using element’s node document, with a NavigationHistoryBehavior of historyHandling.

The HTMLControlledFrameElement() constructor steps are:

1. Let webRequest be this’s request.

2. Set the eventName and webRequest fields of webRequest[onBeforeRequest] to "beforeRequest" and webRequest respectively.

3. Set the eventName and webRequest fields of webRequest[onBeforeSendHeaders] to "beforeSendHeaders" and webRequest respectively.

4. Set the eventName and webRequest fields of webRequest[onSendHeaders] to "sendHeaders" and webRequest respectively.

5. Set the eventName and webRequest fields of webRequest[onHeadersReceived] to "headersReceived" and webRequest respectively.

6. Set the eventName and webRequest fields of webRequest[onAuthRequired] to "authRequired" and webRequest respectively.

7. Set the eventName and webRequest fields of webRequest[onBeforeRedirect] to "beforeRedirect" and webRequest respectively.

8. Set the eventName and webRequest fields of webRequest[onResponseStarted] to "responseStarted" and webRequest respectively.

9. Set the eventName and webRequest fields of webRequest[onCompleted] to "completed" and webRequest respectively.

10. Set the eventName and webRequest fields of webRequest[onErrorOccurred] to "errorOccurred" and webRequest respectively.

The partition IDL attribute setter steps are:

1. If this’s embedded navigable is not null, then:

   1. Throw a "NotSupportedError" DOMException.

   2. Do not change the value of partition.

The src IDL attribute setter steps are:

1. If this is not in a document tree, then return.

2. If this’s embedded navigable is null, then:

   1. Initialize a controlledframe given this.

3. Otherwise:

   1. Navigate a controlledframe given this and this’s src.

To traverse an embedded navigable’s history, given a controlledframe controlledframe and an integer stepDelta, run the following steps:

1. Let resultPromise be a new promise.

2. Return resultPromise and run the remaining steps in parallel.

3. If controlledframe’s embedded navigable is null, then resolve resultPromise with false.

4. Let currentStep be controlledframe’s embedded navigable’s current session history step.

5. Let step be the sum of currentStep and stepDelta.

6. If step is negative, then resolve resultPromise with false.

7. If step is greater than or equal to the size of the controlledframe’s embedded navigable’s session history entries, then resolve resultPromise with false.

8. Let result be the result of applying the traverse history step given step, controlledframe’s embedded navigable, and a user navigation involvement of "browser UI".

9. If result is not equal to "applied", resolve resultPromise with false.

10. Otherwise, resolve resultPromise with true.

The canGoBack() method steps are:

We can’t actually synchronously access the embedded navigable’s history state. In the future we should update this method to return a Promise.

1. If this’s embedded navigable is null, then return false.

2. If this’s embedded navigable’s current session history step is greater than 0, return true.

3. Return false.

The canGoForward() method steps are:

1. If this’s embedded navigable is null, then return false.

2. Let step be this’s embedded navigable’s current session history step.

3. Let steps be the result of getting all used history steps given this’s embedded navigable.

4. If step+1 is less than the size of steps, then return true.

5. Return false.

The back() method steps are:

1. Return the result of traversing an embedded navigable’s history given this and -1.

The forward() method steps are:

1. Return the result of traversing an embedded navigable’s history given this and 1.

The go(relativeIndex) method steps are:

1. Return the result of traversing an embedded navigable’s history given this and relativeIndex.

The reload() steps are:

1. If this’s embedded navigable is null, return.

2. Reload this’s embedded navigable given a user navigation involvement of "browser UI".

The stop() steps are:

1. If this’s embedded navigable is null, return.

2. Stop loading this’s embedded navigable.

// One of |code| or |file| must be specified but not both.
dictionary InjectDetails {
  DOMString code;
  DOMString file;
};

dictionary InjectionItems {
  DOMString code;
  sequence<DOMString> files;
};

enum RunAt {
  "document-start",
  "document-end",
  "document-idle",
};

dictionary ContentScriptDetails {
  required DOMString name;
  InjectionItems js;
  InjectionItems css;
  required sequence<DOMString> matches;
  sequence<DOMString> excludeMatches;
  boolean allFrames;
  boolean matchAboutBlank;
  RunAt runAt;
};

To fetch an injection item given a controlledframe controlledframe, a DOMString urlString, a boolean isCss, a long index, and an algorithm completionSteps, run the following steps:

1. If urlString is not an valid URL string, then:

   1. Run completionSteps given 0 and false.

   2. Return.

2. Let request be a new request with the following fields:

   URL

   The result of running the URL parser given urlString and controlledframe’s node document’s document base URL

   method

   "GET"

   destination

   "style" if isCss is true, "script" otherwise

   client

   controlledframe’s node document’s relevant settings object

   mode

   "cors"

3. Fetch request, with processResponseConsumeBody set to the following steps given a response response and a null, failure, or byte sequence contents:

   1. If response’s status is not 200, or contents is null or failure, then run completionSteps given 0 and false.

   2. Otherwise, run completionSteps given index and contents.

To validate and resolve ContentScriptDetails given a controlledframe controlledframe and a ContentScriptDetails details, run the following steps:

1. Let result be a new promise.

2. If details["js"] and details["css"] are both defined, or both undefined, then reject result with a TypeError and abort these steps.

3. If details["matches"] is empty, then reject result with a TypeError and abort these steps.

4. Return result and run the remaining steps in parallel.

5. Let config be a new content script config with the following values:

   pendingFetchCount

   0

   matches

   details["matches"]

   excludeMatches

   details["excludeMatches"] if defined, otherwise an empty list

   allFrames

   details["allFrames"] if defined, otherwise false

   matchAboutBlank

   details["matchAboutBlank"] if defined, otherwise false

   runAt

   details["runAt"] if defined, otherwise document-idle

6. Let isCss be a boolean equal to true if details["css"] is defined, false otherwise.

7. Let completionSteps be the following algorithm, which takes a long index and a string or boolean source:

   1. If source is not a string, then reject result with a TypeError and abort these steps.

   2. If isCss, then:

      1. Set config’s css[index] to source.

   3. Otherwise:

      1. Set config’s js[index] to source.

   4. Decrement config’s pendingFetchCount.

   5. If config’s pendingFetchCount is greater than 0, then return.

   6. Set controlledframe’s content script map[details[name]] to config.

   7. Resolve result.

8. Let injectionItems be details["css"] if isCss is true, details["js"] otherwise.

9. If injectionItems["code"] and injectionItems["files"] are both defined, or both undefined, reject result with a TypeError and abort these steps.

10. If injectionItems["code"] is defined, then:

    1. Run completionSteps given 0 and injectionItems ["code"].

11. Otherwise:

    1. If injectionItems["files"] is empty, then reject result with a TypeError and abort these steps.

    2. For each urlString of injectionItems ["files"]:

       1. Run fetch an injection item given controlledframe, urlString, isCss, config’s pendingFetchCount, and completionSteps.

       2. Increment config’s pendingFetchCount.

To determine if a content script config applies to a document given a content script config config, a URL url, and a boolean isTopLevel, run the following steps:

1. If isTopLevel is false, and config’s allFrames is false, then return false.

2. If the result of serializing url with exclude fragment equal to true is equal to "about:blank", and config’s matchAboutBlank is false, then return false.

3. Let urlString be the result of serializing url.

4. Let match be false.

5. For each pattern of config’s matches:

   1. If urlString matches a URL pattern pattern, then set match to true.

6. For each pattern of config’s excludeMatches:

   1. If urlString matches a URL pattern pattern, then set match to false.

7. Return match.

To inject content scripts into a document given a Document document, and a RunAt currentPhase, run the following steps:

1. Let embeddedNavigable be document’s node navigable’s traversable navigable.

2. If embeddedNavigable is null or its embedderParent is null, then return.

3. Let controlledframe be embeddedNavigable’s embedderParent.

4. Let url be document’s URL.

5. Let isTopLevel be true if document’s node navigable’s parent is null, false otherwise.

6. For each config of controlledframe’s content script map:

   1. If the result of determining whether a content script config applies to a document given config, url, and isTopLevel equals false, then continue.

   2. If currentPhase is equal to document-start and config’s css is not empty, then:

      1. For each styleSource of config’s css:

         1. Run inject a stylesheet into a document given document and styleSource.

   3. Otherwise, if currentPhase equals config’s runAt, then:

      1. For each scriptSource of config’s js:

         1. Run inject a script into a document given document and scriptSource.

To inject a stylesheet into a document given a Document document and a string styleSource, run the following steps:

1. Let styleSheet be a new CSS style sheet object.

2. Synchronously replace the rules of a CSSStyleSheet given styleSheet and styleSource.

3. Add a CSS style sheet given document and styleSheet.

To inject a script into a document given a Document document and a string scriptSource, run the following steps:

1. Let script be the result of creating a classic script given scriptSource, document’s relevant settings object, document’s URL, and the default script fetch options.

2. Return the result of running a classic script given script.

The addContentScripts(contentScriptList) method steps are:

1. If contentScriptList is empty, return a promise that is rejected with a TypeError.

2. Let promises be an empty list.

3. For each contentScript in contentScriptList:

   1. Let promise be the result of calling validate and resolve ContentScriptDetails given contentScript.

   2. Append promise to promises.

4. Return the result of calling Promise.all given promises.

The removeContentScripts(scriptNameList) method steps are:

1. Let result be a new promise.

2. Return result and run the remaining steps in parallel.

3. If scriptNameList is undefined, then:

   1. Clear this’s content script map.

4. Otherwise, for each name of scriptNameList:

   1. Remove this’s content script map[name].

5. Resolve result.

The executeScript(optional details) method steps are:

1. Let result be a new promise.

2. Return result and run the remaining steps in parallel.

3. If this’s embedded navigable is null, reject result with a TypeError and abort these steps.

4. If details["code"] and details"[file"] are either both defined or both undefined, reject result with a TypeError and abort these steps.

5. Let executionSteps be the following algorithm that takes a long and a string or boolean scriptString:

   1. If scriptString is not a string, then reject result with a TypeError and abort these steps.

   2. Let document be this’s embedded navigable’s active document.

   3. Let status be the result of injecting a script into a document given document and scriptString.

   4. If status is a normal completion, then:

      1. Resolve result with status.[[Value]].

   5. Otherwise:

      1. Reject result with status.[[Value]].

6. If details["code"] is defined, then run executionSteps given 0 and details["code"].

7. Otherwise, fetch an injection item given this, details["file"], false, 0, and executionSteps.

The insertCSS(optional details) method steps are:

1. Let result be a new promise.

2. Return promise and run the remaining steps in parallel.

3. If this’s embedded navigable is null, reject promise with a TypeError and abort these steps.

4. If details["code"] and details["file"] are either both defined or both undefined, reject result with a TypeError and abort these steps.

5. Let executionSteps be the following algorithm that takes a long and a string or boolean styleString:

   1. If styleString is not a string, then reject result with a TypeError and abort these steps.

   2. Let document be this’s embedded navigable’s active document.

   3. Inject a stylesheet into a document given document and styleString.

   4. Resolve promise.

6. If details["code"] is defined, then run executionSteps given 0 and details["code"].

7. Otherwise, fetch an injection item given this, details["file"], false, 0, and executionSteps.

dictionary ClearDataOptions {
  long since;
};

dictionary ClearDataTypeSet {
  boolean appcache;
  boolean cache;
  boolean cookies;
  boolean fileSystems;
  boolean indexedDB;
  boolean localStorage;
  boolean persistentCookies;
  boolean sessionCookies;
  boolean webSQL;
};

The clearData(optional options, optional types) method steps are:

1. Let resultPromise be a new promise.

2. Return resultPromise and run the remaining steps in parallel.

3. Let clearSince be 0. This will represent to clear all items.

4. If options["since"] is set:

   1. Let clearSince be options["since"].

5. If types["appcache"] is set:

   1. Clear the partition’s appcache items with a matching clearSince.

6. If types["cache"] is set:

   1. Clear the partition’s cache items with a matching clearSince.

7. If types["cookies"] is set:

   1. Clear the partition’s cookie items with a matching clearSince.

8. If types["fileSystems"] is set:

   1. Clear the partition’s fileSystem items with a matching clearSince.

9. If types["indexedDB"] is set:

   1. Clear the partition’s indexedDB items with a matching clearSince.

10. If types["localStorage"] is set:

    1. Clear the partition’s localStorage items with a matching clearSince.

11. If types["persistentCookies"] is set:

    1. Clear the partition’s persistentCookies items with a matching clearSince.

12. If types["sessionCookies"] is set:

    1. Clear the partition’s sessionCookies items with a matching clearSince.

13. If types["webSQL"] is set:

    1. Clear the partition’s webSQL items with a matching clearSince.

14. Then, resolve resultPromise.

The getAudioState() method steps are:

1. Let resultPromise be a new promise.

2. Return resultPromise and run the remaining steps in parallel.

3. If this’s embedded navigable is null, then reject resultPromise with a TypeError and abort these steps.

4. Let muteState be the current audio mute state of embedded content.

5. Then, resolve resultPromise with muteState.

The getZoom() method steps are:

1. Let resultPromise be a new promise.

2. Return resultPromise and run the remaining steps in parallel.

3. If this’s embedded navigable is null, then reject resultPromise with a TypeError and abort these steps.

4. Let zoomFactor be the current zoom setting for the embedded content.

5. Then, resolve resultPromise with zoomFactor.

The isAudioMuted() method steps are:

1. Let resultPromise be a new promise.

2. Return resultPromise and run the remaining steps in parallel.

3. If this’s embedded navigable is null, then reject resultPromise with a TypeError and abort these steps.

4. Let muteState be the current audio mute state for embedded content.

5. Then, resolve resultPromise with muteState.

The setAudioMuted(mute) method steps are:

1. If this’s embedded navigable is null, then throw a TypeError.

2. Change the audio mute state for embedded content to match mute state.

The setZoom(zoomFactor) method steps are:

1. Let resultPromise be a new promise.

2. Return resultPromise and run the remaining steps in parallel.

3. If this’s embedded navigable is null, then reject resultPromise with a TypeError and abort these steps.

4. Change the zoom for the embedded content to be zoomFactor.

5. Then, resolve resultPromise.

// One of |code| or |file| must be specified but not both.
dictionary ImageDetails {
  DOMString format;
  DOMString quality;
};

The captureVisibleRegion(optional options) method steps are:

1. Let resultPromise be a new promise.

2. Return resultPromise and run the remaining steps in parallel.

3. If this’s embedded navigable is null, then reject resultPromise with a TypeError and abort these steps.

4. Let optionsFormat be "JPEG" by default.

5. Let optionsQuality be 100 by default.

6. If options has field "format":

   1. Let optionsFormat be options["format"].

7. If optionsFormat is an unrecognized format, reject resultPromise with a TypeError and abort these steps.

8. If options has field "quality":

   1. Let optionsQuality be options["quality"].

9. If optionsQuality is not an integer and is not between 0 and 100 inclusive, reject resultPromise with a TypeError and abort these steps.

10. Create an image in format optionsFormat at quality optionsQuality showing the visible region of embedded content.

11. Then, resolve resultPromise containing the image data.

The print() method steps are:

1. If this’s embedded navigable is null, then throw a TypeError.

2. Initiate the browser print page feature for embedded content.

[Exposed=Window, IsolatedContext]
interface ConsoleMessage {
  readonly attribute long level;
  readonly attribute DOMString message;
};

[Exposed=Window, IsolatedContext]
interface ConsoleMessageEvent : Event {
  constructor(DOMString type, optional ConsoleMessageEventInit eventInitDict = {});
  readonly attribute ConsoleMessage consoleMessage;
};

dictionary ConsoleMessageEventInit: EventInit {
  ConsoleMessage? consoleMessage;
};

To fire a ConsoleMessageEvent e given controlledframe element target and the Printer(logLevel, args[, options]) method arguments.

1. Let consoleMessage be a new ConsoleMessage object.

2. Set the following fields of consoleMessage:

   level

   logLevel.

   message

   The result of implementation-defined formatting to args.

3. Set e’s consoleMessage to consoleMessage.

4. Dispatch e at target.

TODO: monkey patch console Printer.

[Exposed=Window, IsolatedContext]
interface DialogController {
  undefined okay(optional DOMString response);
  undefined cancel();
};

[Exposed=Window, IsolatedContext]
interface DialogMessage {
  readonly attribute DOMString messageType;
  readonly attribute DOMString messageText;
  readonly attribute DialogController dialogController;
};

[Exposed=Window, IsolatedContext]
interface DialogEvent : Event {
  constructor(DOMString type, optional DialogEventInit eventInitDict = {});
  readonly attribute DialogMessage dialogMessage;
};

dictionary DialogEventInit: EventInit {
  DialogMessage? dialogMessage;
};

To fire a DialogEvent e given controlledframe element target, simple-dialogs type dialogType, and message message.

1. Let dialogMessage be a new DialogMessage object.

2. Set the following fields of dialogMessage:

   messageType

   dialogType, one of "alert", "confirm", or "prompt".

   messageText

   message.

3. Set e’s dialogMessage to dialogMessage.

4. Dispatch e at target.

TODO: monkey patch simple-dialogs.

[Exposed=Window, IsolatedContext]
interface NewWindowController {
  undefined attach(HTMLControlledFrameElement controlledFrame);
  undefined discard();
};

[Exposed=Window, IsolatedContext]
interface NewWindow {
  readonly attribute NewWindowController window;
  readonly attribute USVString targetUrl;
  readonly attribute DOMString initialWidth;
  readonly attribute DOMString initialHeight;
  readonly attribute DOMString name;
  readonly attribute DOMString windowOpenDisposition;
};

[Exposed=Window, IsolatedContext]
interface NewWindowEvent : Event {
  constructor(DOMString type, optional NewWindowEventInit eventInitDict = {});
  readonly attribute NewWindow newWindow;
};

dictionary NewWindowEventInit: EventInit {
  NewWindow? newWindow;
};

TODO:.

[Exposed=Window, IsolatedContext]
interface PermissionRequestControllerBase {
  undefined allow();
  undefined cancel();
};

[Exposed=Window, IsolatedContext]
interface PermissionRequest {
  readonly attribute DOMString permission;
  readonly attribute PermissionRequestControllerBase request;
};

[Exposed=Window, IsolatedContext]
interface PermissionRequestEvent : Event {
  constructor(DOMString type, optional PermissionRequestEventInit eventInitDict = {});
  readonly attribute PermissionRequest permissionRequest;
};

dictionary PermissionRequestEventInit: EventInit {
  PermissionRequest? permissionRequest;
};

TODO: Different child interfaces of PermissionRequestControllerBase for different permissions

[Exposed=Window, IsolatedContext]
interface SizeChange {
  readonly attribute long oldWidth;
  readonly attribute long oldHeight;
  readonly attribute long newWidth;
  readonly attribute long newHeight;
};

[Exposed=Window, IsolatedContext]
interface SizeChangedEvent : Event {
  constructor(DOMString type, optional SizeChangedEventInit eventInitDict = {});
  readonly attribute SizeChange sizeChange;
};

dictionary SizeChangedEventInit: EventInit {
  SizeChange? sizeChange;
};

TODO:

[Exposed=Window, IsolatedContext]
interface ZoomChange {
  readonly attribute float oldZoomFactor;
  readonly attribute float newZoomFactor;
};

[Exposed=Window, IsolatedContext]
interface ZoomChangeEvent : Event {
  constructor(DOMString type, optional ZoomChangeEventInit eventInitDict = {});
  readonly attribute ZoomChange zoomChange;
};

dictionary ZoomChangeEventInit: EventInit {
  ZoomChange? zoomChange;
};

TODO:

[Exposed=Window, IsolatedContext]
interface ContentLoadEvent : Event {
  constructor(DOMString type, optional ContentLoadEventInit eventInitDict = {});
};

dictionary ContentLoadEventInit: EventInit {
};

TODO:

[Exposed=Window, IsolatedContext]
interface LoadInfo {
  readonly attribute USVString url;
  readonly attribute boolean isTopLevel;
};

[Exposed=Window, IsolatedContext]
interface LoadAbortInfo : LoadInfo{
  readonly attribute long code;
  readonly attribute DOMString reason;
};

[Exposed=Window, IsolatedContext]
interface LoadAbortEvent : Event {
  constructor(DOMString type, optional LoadAbortEventInit eventInitDict = {});
  readonly attribute LoadAbortInfo loadAbortInfo;
};

dictionary LoadAbortEventInit: EventInit {
  LoadAbortInfo? loadAbortInfo;
};

TODO:

[Exposed=Window, IsolatedContext]
interface LoadCommitEvent : Event {
  constructor(DOMString type, optional LoadCommitEventInit eventInitDict = {});
  readonly attribute LoadInfo loadInfo;
};

dictionary LoadCommitEventInit: EventInit {
  LoadInfo? loadInfo;
};

TODO:

[Exposed=Window, IsolatedContext]
interface LoadStartEvent : Event {
  constructor(DOMString type, optional LoadStartEventInit eventInitDict = {});
  readonly attribute LoadInfo loadInfo;
};

dictionary LoadStartEventInit: EventInit {
  LoadInfo? loadInfo;
};

TODO:

[Exposed=Window, IsolatedContext]
interface LoadStopEvent : Event {
  constructor(DOMString type, optional LoadStopEventInit eventInitDict = {});
};

dictionary LoadStopEventInit: EventInit {
};

TODO:

To determine the network partition key, given an environment environment:

4. Let topLevelSite be the result of obtaining a site, given topLevelOrigin.

5. Let secondKey be null or an implementation-defined value.

6. Let embedderParent be the result of getting an environment’s embedderParent given environment.
7. If embedderParent is not null, then set secondKey to embedderParent’s partition.

8. Return (topLevelSite, secondKey).

To obtain a storage key for non-storage purposes, given an environment environment, run these steps:

1. Let origin be environment’s origin if environment is an environment settings object; otherwise environment’s creation URL’s origin.

2. Let embedderParent be the result of getting an environment’s embedderParent given environment.
3. If embedderParent is not null, then return a tuple consisting of embedderParent’s partition and origin.

4. Return a tuple consisting of origin.

To get an environment’s embedderParent given an environment environment, run the following steps:

1. If environment is an environment settings object whose global object is a Window object, then:

   This algorithm doesn’t work for Shared or Service Workers because embedderParent is only defined on a navigable, and it’s not always possible to go from a non-Window environment to a navigable.

   1. Let navigable be environment’s global object’s navigable.

   2. Let top be the top-level traversable of navigable.

   3. If top’s embedderParent is not null, then return top’s embedderParent.

2. Return null.

enum ResourceType {
  "main_frame",
  "sub_frame",
  "stylesheet",
  "script",
  "image",
  "font",
  "object",
  "xmlhttprequest",
  "ping",
  "csp_report",
  "media",
  "websocket",
  "webbundle",
  "other",
};

callback interface WebRequestEventListener {
  BlockingResponse? handleEvent(WebRequestEventDetails details);
};

dictionary RequestFilter {
  sequence<ResourceType> types;
  sequence<USVString> urls;
};

enum ExtraInfoSpec {
  "asyncBlocking",
  "blocking",
  "extraHeaders",
  "requestHeaders",
  "responseHeaders",
};

[Exposed=Window, IsolatedContext]
interface WebRequestEvent {
  undefined addListener(WebRequestEventListener listener,
                        optional RequestFilter filter = {},
                        optional sequence<ExtraInfoSpec> extraInfoSpec);
  boolean hasListener(WebRequestEventListener listener);
  boolean hasListeners();
  undefined removeListener(WebRequestEventListener listener);
};

dictionary WebRequestAuthCredentials {
  required DOMString username;
  required DOMString password;
};

dictionary BlockingResponse {
  WebRequestAuthCredentials authCredentials;
  boolean cancel;
  USVString redirectUrl;
  sequence<HttpHeader> requestHeaders;
  sequence<HttpHeader> responseHeaders;
};

enum DocumentLifecycle {
  "prerender",
  "active",
  "cached",
  "pending_deletion",
};

enum FrameType {
  "outermost_frame",
  "fenced_frame",
  "sub_frame",
};

dictionary WebRequestEventDetails {
  DOMString documentId;
  DocumentLifecycle documentLifecycle;
  required long frameId;
  FrameType frameType;
  USVString initiator;
  required DOMString method;
  DOMString parentDocumentId;
  required long parentFrameId;
  required DOMString requestId;
  required long timeStamp;
  required ResourceType type;
  required USVString url;
};

dictionary UploadData {
  ArrayBuffer bytes;
  DOMString file;
};
dictionary RequestBody {
  DOMString error;
  any formData;
  sequence<UploadData> raw;
};

dictionary WebRequestBeforeRequestDetails : WebRequestEventDetails {
  RequestBody requestBody;
};

dictionary HttpHeader {
  required DOMString name;
  DOMString value;
  sequence<byte> binaryValue;
};

dictionary WebRequestBeforeSendHeadersDetails : WebRequestEventDetails {
  sequence<HttpHeader> requestHeaders;
};

dictionary WebRequestSendHeadersDetails : WebRequestEventDetails {
  sequence<HttpHeader> requestHeaders;
};

dictionary WebRequestResponseEventDetails : WebRequestEventDetails {
  required long statusCode;
  required DOMString statusLine;
  sequence<HttpHeader> responseHeaders;
};

dictionary WebRequestHeadersReceivedDetails : WebRequestResponseEventDetails {};

dictionary AuthChallenger {
  DOMString host;
  long port;
};
dictionary WebRequestAuthRequiredDetails : WebRequestResponseEventDetails {
  required AuthChallenger challenger;
  required boolean isProxy;
  required DOMString scheme;
  DOMString realm;
};

dictionary WebRequestResponseWithIpEventDetails : WebRequestResponseEventDetails {
  required boolean fromCache;
  DOMString ip;
};

dictionary WebRequestBeforeRedirectDetails : WebRequestResponseWithIpEventDetails {
  required USVString redirectUrl;
};

dictionary WebRequestResponseStartedDetails : WebRequestResponseWithIpEventDetails {};

dictionary WebRequestCompletedDetails : WebRequestResponseWithIpEventDetails {};

dictionary WebRequestErrorOccurredDetails : WebRequestEventDetails {
  required DOMString error;
  required boolean fromCache;
  DOMString ip;
};

callback HandlerBehaviorChangedCallback = undefined ();

[Exposed=Window, IsolatedContext]
interface WebRequest {
  readonly attribute WebRequestEvent onBeforeRequest;
  readonly attribute WebRequestEvent onBeforeSendHeaders;
  readonly attribute WebRequestEvent onSendHeaders;
  readonly attribute WebRequestEvent onHeadersReceived;
  readonly attribute WebRequestEvent onAuthRequired;
  readonly attribute WebRequestEvent onBeforeRedirect;
  readonly attribute WebRequestEvent onResponseStarted;
  readonly attribute WebRequestEvent onCompleted;
  readonly attribute WebRequestEvent onErrorOccurred;

  undefined handlerBehaviorChanged(optional HandlerBehaviorChangedCallback callback);
};

The addListener(listener, filter, extraInfoSpec) method steps are:

1. Call removeListener with listener.

2. Let eventName be this’s eventName.

3. Let handlerConfig be a new WebRequest handler config with the following items:

   handler

   listener

   filter

   filter

4. Let specSet be a set containing the items in extraInfoSpec.

5. If eventName equals "beforeRequest", then:

   1. If specSet is not a subset of the set « "blocking", "requestBody", "extraHeaders" », then throw a TypeError.

   2. If specSet contains "blocking", then set handlerConfig’s blocking to true.

   3. If specSet contains "requestBody", then set handlerConfig’s requestsBody to true.

   4. If specSet contains "extraHeaders", then set handlerConfig’s requestsAllHeaders to true.

6. Otherwise, if eventName equals "beforeSendHeaders", then:

   1. If specSet is not a subset of the set « "blocking", "requestHeaders", "extraHeaders" », then throw a TypeError.

   2. If specSet contains "blocking", then set handlerConfig’s blocking to true.

   3. If specSet contains "requestHeaders", then set handlerConfig’s requestsHeaders to true.

   4. If specSet contains "extraHeaders", then set handlerConfig’s requestsAllHeaders to true.

7. Otherwise, if eventName equals "sendHeaders", then:

   1. If specSet is not a subset of the set « "requestHeaders", "extraHeaders" », then throw a TypeError.

   2. If specSet contains "requestHeaders", then set handlerConfig’s requestsHeaders to true.

   3. If specSet contains "extraHeaders", then set handlerConfig’s requestsAllHeaders to true.

8. Otherwise, if eventName equals "headersReceived", then:

   1. If specSet is not a subset of the set « "blocking", "responseHeaders", "extraHeaders" », then throw a TypeError.

   2. If specSet contains "blocking", then set handlerConfig’s blocking to true.

   3. If specSet contains "responseHeaders", then set handlerConfig’s requestsHeaders to true.

   4. If specSet contains "extraHeaders", then set handlerConfig’s requestsAllHeaders to true.

9. Otherwise, if eventName equals "authRequired", then:

   1. If specSet is not a subset of the set « "asyncBlocking", "blocking", "responseHeaders", "extraHeaders" », then throw a TypeError.

   2. If specSet contains "asyncBlocking", then set handlerConfig asyncBlocking to true.

   3. If specSet contains "blocking", then set handlerConfig’s blocking to true.

   4. If specSet contains "responseHeaders", then set handlerConfig’s requestsHeaders to true.

   5. If specSet contains "extraHeaders", then set handlerConfig’s requestsAllHeaders to true.

10. Otherwise, if eventName equals "beforeRedirect", then:

    1. If specSet is not a subset of the set « "responseHeaders", "extraHeaders" », then throw a TypeError.

    2. If specSet contains "responseHeaders", then set handlerConfig’s requestsHeaders to true.

    3. If specSet contains "extraHeaders", then set handlerConfig’s requestsAllHeaders to true.

11. Otherwise, if eventName equals "responseStarted", then:

    1. If specSet is not a subset of the set « "responseHeaders", "extraHeaders" », then throw a TypeError.

    2. If specSet contains "responseHeaders", then set handlerConfig’s requestsHeaders to true.

    3. If specSet contains "extraHeaders", then set handlerConfig’s requestsAllHeaders to true.

12. Otherwise, if eventName equals "completed", then:

    1. If specSet is not a subset of the set « "responseHeaders", "extraHeaders" », then throw a TypeError.

    2. If specSet contains "responseHeaders", then set handlerConfig’s requestsHeaders to true.

    3. If specSet contains "extraHeaders", then set handlerConfig’s requestsAllHeaders to true.

13. Otherwise, if eventName equals "errorOccurred", then:

    1. If specSet is not a subset of the set « "extraHeaders" », then throw a TypeError.

    2. If specSet contains "extraHeaders", then set handlerConfig’s requestsAllHeaders to true.

14. Otherwise, throw a TypeError.

15. Let handlerMap be the handler map of this’s webRequest.

16. Append handlerConfig to handlerMap[eventName].

The hasListener(listener) method steps are:

1. Let handlerMap be the handler map of this’s webRequest.

2. Let event name be this’s eventName.

3. For each handlerConfig in handlerMap[event name]:

   1. If handlerConfig’s handler equals listener, return true.

4. Return false.

The hasListeners() method steps are:

1. Let handlerMap be the handler map of this’s webRequest.

2. Let event name be this’s eventName.

3. If handlerMap[event name] is empty, return false, otherwise return true.

The removeListener(listener) method steps are:

1. Let handlerMap be the handler map of this’s webRequest.

2. Let event name be this’s eventName.

3. Let handlerConfigs be handlerMap[event name].

4. Remove all items from handlerConfigs whose handler equals listener.

The handlerBehaviorChanged(callback) method steps are:

1. In parallel, clear the HTTP cache associated with the partition used by environments embedded within this HTMLControlledFrameElement.

   Note: The behavior of event handlers registered through the WebRequest API will be reflected in the HTTP cache, which will no longer be valid if the behavior of the event handlers changed. The purpose of this method is to invalidate any cache entries that were affected by WebRequest event handlers.

2. Invoke callback when the HTTP cache has been cleared.

To process beforeRequest events given a request request, run the following steps:

1. Let handlers be the result of calling lookup registered WebRequest handler configs given "beforeRequest", and request.

2. For each handler in handlers:

   1. Let details be the result of calling create a WebRequestEventDetails object given request.

   2. If request’s body is not null, then:

      1. Let requestBody be a new RequestBody.

      2. Let body be request’s body.

         TODO: serialize stream if present.

      3. Switch on body’s source:

         byte sequence

         Append a new UploadData with bytes equal to the serialized body’s source to requestBody’s raw.

         Blob

         Append a new UploadData with bytes equal to the serialized body’s source to requestBody’s raw.

         FormData

         1. Let formData be a new object.

         2. For each entry in body’s source’s entry list:

            1. Switch on entry[1]:

            File

            Append a new UploadData with file equal to entry[1]'s name to requestBody’s raw.

            USVString

            1. If formData[entry[0]] does not exist, then set formData[entry[0]] equal to an empty list.

            2. Append entry[1] to formData[entry[0]].

         3. Set details’s formData to formData.

      4. Set details’s requestBody to requestBody.

   3. If handler’s blocking flag is true, then:

      1. Let result be the result of calling handler[handler] given details.

      2. If any key in result is not contained in the set « "cancel", "redirect" », then throw a TypeError.

      3. Return result.

   4. Call handler[handler] given details in parallel.

   5. Return null.

To process beforeSendHeaders events given a request request, run the following steps:

1. Let handlers be the result of calling lookup registered WebRequest handler configs given "beforeSendHeaders", and request.

2. For each handler in handlers:

   1. Let details be the result of calling create a WebRequestEventDetails object given request.

   2. If handler’s requestsHeaders is true, then set details’s requestHeaders to the result of calling convert a header list to an HttpHeader sequence given request’s header list, handler’s requestsAllHeaders, and isRequest equal to true.

   3. If handler’s blocking flag is true, then:

      1. Let result be the result of calling handler[handler] given details.

      2. If any key in result is not contained in the set « "cancel", "requestHeaders" », then throw a TypeError.

      3. Return result.

   4. Call handler[handler] given details in parallel.

   5. Return null.

To process sendHeaders events given a request request, run the following steps:

1. Let handlers be the result of calling lookup registered WebRequest handler configs given "sendHeaders", and request.

2. For each handler in handlers:

   1. Let details be the result of calling create a WebRequestEventDetails object given request.

   2. If handler’s requestsHeaders is true, then set details’s requestHeaders to the result of calling convert a header list to an HttpHeader sequence given request’s header list, handler’s requestsAllHeaders, and isRequest equal to true.

   3. Call handler[handler] given details in parallel.

To process headersReceived events given a request request and a response response, run the following steps:

1. Let handlers be the result of calling lookup registered WebRequest handler configs given "headersReceived", and request.

2. For each handler in handlers:

   1. Let details be the result of calling create a WebRequestResponseEventDetails object given request and response.

   2. If handler’s requestsHeaders is true, then set details’s responseHeaders to the result of calling convert a header list to an HttpHeader sequence given response’s header list, handler’s requestsAllHeaders, and isRequest equal to false.

   3. If handler’s blocking flag is true, then:

      1. Let result be the result of calling handler[handler] given details.

      2. If any key in result is not contained in the set « "cancel", "redirectUrl", "responseHeaders" », then throw a TypeError.

      3. Return result.

   4. Call handler[handler] given details in parallel.

   5. Return null.

To process authRequired events given a request request and a response response, run the following steps:

1. Let handlers be the result of calling lookup registered WebRequest handler configs given "authRequired", and request.

2. Let challenger be an AuthChallenger with host and port equal to the host and port of response’s URL.

3. If response’s status is 401, then:

   1. Let isProxy be false.

   2. Let scheme be the scheme from response’s WWW-Authenticate header, parsed as defined by the [HTML] specification, or null if the header is missing or invalid.

   3. Let realm be the realm from response’s WWW-Authenticate header, parsed as defined by the [HTML] specification.

4. Otherwise:

   1. Let isProxy be true.

   2. Let scheme be the scheme from response’s Proxy-Authenticate header, parsed as defined by the [HTML] specification, or null if the header is missing or invalid.

   3. Let realm be the realm from response’s Proxy-Authenticate header, parsed as defined by the [HTML] specification.

5. If scheme is null, then return.

6. For each handler in handlers:

   1. Let details be the result of calling create a WebRequestResponseEventDetails object given request and response.

   2. If handler’s requestsHeaders is true, then set details’s responseHeaders to the result of calling convert a header list to an HttpHeader sequence given response’s header list, handler’s requestsAllHeaders, and isRequest equal to false.

      1. Set details challenger, isProxy, scheme, and realm fields equal to challenger, isProxy, scheme, and realm respectively.

   3. If handler’s blocking flag is true, then:

      1. Let result be the result of calling handler[handler] given details.

      2. Return the result of calling process an authRequired response given result.

   4. Otherwise, if handler’s asyncBlocking flat is true, then:

      1. Let result be null.

      2. Let callback be a function that takes a BlockingResponse blockingResponse argument and when executed calls process an authRequired response with blockingResponse and sets result equal to its return value.

      3. Let result be the result of calling handler[handler] given details and callback.

      4. Pause these steps until callback has been invoked.

      5. Return result.

   5. Call handler[handler] given details in parallel.

   6. Return null.

To process an authRequired response given a BlockingResponse blockingResponse, run the following steps:

1. If any key in blockingResponse is not contained in the set « "cancel", "authCredentials" », or if blockingResponse ["authCredentials"] does not contain two keys equal to "username" and "password", then throw a TypeError.

2. Return blockingResponse.

To process beforeRedirect events given a request request and a response response, run the following steps:

1. Let handlers be the result of calling lookup registered WebRequest handler configs given "beforeRedirect", and request.

2. For each handler in handlers:

   1. Let details be the result of calling create a WebRequestResponseWithIpEventDetails object given request and response.

   2. If handler’s requestsHeaders is true, then set details’s responseHeaders to the result of calling convert a header list to an HttpHeader sequence given response’s header list, handler’s requestsAllHeaders, and isRequest equal to false.

   3. Let internalResponse be response, if response is not a filtered response; otherwise response’s internal response.

   4. Set details’s redirectUrl to internalResponse’s location URL given request’s current URL’s fragment.

   5. Call handler[handler] given details in parallel.

To process responseStarted events given a request request and a response response, run the following steps:

1. Let handlers be the result of calling lookup registered WebRequest handler configs given "responseStarted", and request.

2. For each handler in handlers:

   1. Let details be the result of calling create a WebRequestResponseWithIpEventDetails object given request and response.

   2. If handler’s requestsHeaders is true, then set details’s responseHeaders to the result of calling convert a header list to an HttpHeader sequence given response’s header list, handler’s requestsAllHeaders, and isRequest equal to false.

   3. Call handler[handler] given details in parallel.

To process completed events given a request request and a response response, run the following steps:

1. Let handlers be the result of calling lookup registered WebRequest handler configs given "completed", and request.

2. For each handler in handlers:

   1. Let details be the result of calling create a WebRequestResponseWithIpEventDetails object given request and response.

   2. If handler’s requestsHeaders is true, then set details’s responseHeaders to the result of calling convert a header list to an HttpHeader sequence given response’s header list, handler’s requestsAllHeaders, and isRequest equal to false.

   3. Call handler[handler] given details in parallel.

To process errorOccurred events given a request request and a response response, run the following steps:

1. Let handlers be the result of calling lookup registered WebRequest handler configs given "errorOccurred", and request.

2. For each handler in handlers:

   1. Let details be the result of calling create a WebRequestResponseWithIpEventDetails object given request and response.

   2. If handler’s requestsHeaders is true, then set details’s responseHeaders to the result of calling convert a header list to an HttpHeader sequence given response’s header list, handler’s requestsAllHeaders, and isRequest equal to false.

   3. Set handler’s error field to an implementation-defined error message describing the error in response.

   4. Call handler[handler] given details in parallel.

To create a WebRequestEventDetails object given a request request, run the following steps:

1. Let environmentSettingsObject be request’s client.

2. Let crossOriginIsolatedCapability be environmentSettingsObject’s cross-origin isolated capability, or false if environmentSettingsObject is null.

3. Let details be a new WebRequestEventDetails with the following fields:

   timeStamp

   The coarsened shared current time given crossOriginIsolatedCapability.

   url

   The last element of request’s URL list.

   method

   request’s method.

   initiator

   The serialization of an origin given request’s origin.

   Note: An opaque origin will result in initiator being set to the string "null".

   type

   The result of calling get a request’s ResourceType given request.

   requestId

   request’s requestId.

   frameId

   -1

   parentFrameId

   -1

4. If environmentSettingsObject’s global object is a Window object, then:

   1. Let window be environmentSettingsObject’s global object.

   2. Update the following fields of details:

      documentId

      environmentSettingsObject’s id.

      documentLifecycle

      It’s unclear if DocumentLifecycle values map to existing concepts.

      frameId

      The frameId of window’s navigable.

      frameType

      "fenced_frame" if window’s fence is non-null, "outermost_frame" if window’s top equals window, "sub_frame" otherwise.

      1. If window’s parent is not equal to window, then update the following values of details:

         parentDocumentId

         The id of window’s parent’s active document’s relevant global object.

         parentFrameId

         The frameId of window’s parent’s navigable.

5. Return details.

To create a WebRequestResponseEventDetails object given a request request, a response response, a boolean requestsHeaders, and a boolean requestsAllHeaders, run the following steps:

1. Let details be the result of creating a WebRequestEventDetails object given request.

2. Update the following fields in details:

   statusCode

   response’s status.

   statusLine

   response’s status message.

3. If requestsHeaders is true, then set details’s responseHeaders to the result of calling convert a header list to an HttpHeader sequence given response’s header list, requestsAllHeaders, and isRequest equal to false.

4. Return details.

To create a WebRequestResponseWithIpEventDetails object given a request request, a response response, a boolean requestsHeaders, and a boolean requestsAllHeaders, run the following steps:

1. Let details be the result of creating a WebRequestResponseEventDetails object given request, response, requestsHeaders, and requestsAllHeaders.

2. If response’s cache state is "local", then set details’s fromCache to true.

3. Set details’s ip to the ip address from which response was received if the request involved a network request.

   The [FETCH] spec currently doesn’t specify storing the remote IP address used when sending request.

4. Return details.

To convert a header list to an HttpHeader sequence given a header list fetchHeaders, a boolean requestsAllHeaders, and a boolean isRequest, run the following steps:

1. Let headers be a an empty list of HttpHeader objects.

2. For each fetchHeader in fetchHeaders:

   1. If each of the following conditions are true, then continue:

      • isRequest is true

      • requestsAllHeaders is false

      • fetchHeader[0] is not a CORS-safelisted request-header

   2. If each of the following conditions are true, then continue:

      • isRequest is false

      • requestsAllHeaders is false

      • fetchHeader[0] is not a CORS-safelisted response-header name

   3. Let header be a new HttpHeader.

   4. Set header["name"] to the isomorphic decoding of fetchHeader[0].

   5. Let value be the isomorphic decoding of fetchHeader[1] .

   6. If value is a scalar value string, then set header ["value"] to value.

   7. Otherwise, set header["binaryValue"] to fetchHeader[1].

   8. Append header to headers.

3. Return headers.

To convert an HttpHeader sequence to a header list given a HttpHeader headers, run the following steps:

1. Let headerList be a an empty header list.

2. For each header in headers:

   1. If any of the following conditions are true, throw a TypeError:

      • header["name"] is not a string.

      • header["value"] is not a string or header["binaryValue"] is not an list of Numbers.

   2. Let value be header["value"] if it exists, or the isomorphic decoding of header["binaryValue"] otherwise.

   3. Append a new tuple with values « header["name"], value » to headerList.

3. Return headerList.

To get a request’s ResourceType given a request request, run the following steps:

1. Return request’s initiator type.

   TODO: initiator type doesn’t exactly map to ResourceType. Define this mapping.

To create a redirect response given a string redirectUrl, return a response with the following fields:

status

301

header list

« ("Location", redirectUrl) »

A string url matches a URL pattern string url pattern if the following steps return true:

1. url url pattern TODO: Spec this, ideally referring to a not-yet-defined Match pattern spec.

To lookup registered WebRequest handler configs given a string event name, and a request request, run the following steps:

1. Let client be request’s client.

2. If client is null, return an empty list.

3. If client’s corresponding global object is not a Window, return an empty list.

4. Let navigable be the navigable that client’s global object is within.

5. If navigable’s embedderParent is null, return an empty list.

6. Let controlledFrame be the HTMLControlledFrameElement corresponding to navigable’s embedderParent.

7. Let valid handlers be an empty list.

8. Let handlerMap be controlledFrame’s request’s handler map.

9. For each handlerConfig in handlerMap[event name]:

   1. Let filter be handlerConfig’s filter

   2. Let types be filter[types].

   3. If types is not empty and types does not contain the result of calling get a request’s ResourceType given request, then continue.

   4. Let urls be filter[urls].

   5. Let is valid url be true if urls is empty, false otherwise.

   6. For each url pattern in urls:

      1. If request’s URL matches a URL pattern given url pattern, set is valid url to true.

   7. Append handlerConfig to valid handlers.

10. Return valid handlers.

enum ContextType {
    "all",
    "page",
    "frame",
    "selection",
    "link",
    "editable",
    "image",
    "video",
    "audio",
};

enum ItemType {
    "normal",
    "checkbox",
    "radio",
    "separator",
};

dictionary OnClickData {
    boolean checked;
    required boolean editable;
    long frameId;
    USVString frameUrl;
    USVString linkUrl;
    DOMString mediaType;
    required (DOMString or long) menuItemId;
    USVString pageUrl;
    (DOMString or long) parentMenuId;
    DOMString selectionText;
    USVString srcUrl;
    boolean wasChecked;
};

callback ContextMenusCallback = undefined (optional OnClickData info);

[Exposed=Window, IsolatedContext]
interface ContextMenusEvent {
    undefined addListener(ContextMenusCallback callback);
    undefined removeListener(ContextMenusCallback callback);
    boolean hasListener(ContextMenusCallback callback);
    boolean hasListeners();
    undefined dispatch(any data);
};

[Exposed=Window, IsolatedContext]
interface OnClickedEvent : ContextMenusEvent {};

[Exposed=Window, IsolatedContext]
interface OnShowEvent : ContextMenusEvent {};

dictionary ContextMenusProperties {
    boolean checked;
    sequence<ContextType> context;
    sequence<USVString> documentUrlPatterns;
    boolean enabled;
    (DOMString or long) parentId;
    sequence<USVString> targetUrlPatterns;
    DOMString title;
    ItemType type;
    ContextMenusCallback onclick;
};

dictionary ContextMenusCreateProperties : ContextMenusProperties {
    required DOMString id;
};

[Exposed=Window, IsolatedContext]
interface ContextMenus {
    attribute OnClickedEvent onClicked;
    attribute OnShowEvent onShow;

    Promise<undefined> create(ContextMenusCreateProperties properties);
    Promise<undefined> remove(DOMString id);
    Promise<undefined> removeAll();
    Promise<undefined> update(DOMString id, optional ContextMenusProperties properties = {});
};

The create(properties) method steps are:

1. Let p be a new promise.

2. Run the following steps in parallel:

   1. Let contextMenusMap be this’s context menu map.

   2. Let id be the properties["menuItemId"].

   3. If contextMenusMap[id] exists, reject p with a TypeError and abort these steps.

   4. Set contextMenusMap[id] to properties.

   5. Resolve p with undefined.

The remove(id) method steps are:

1. Let p be a new promise.

2. Run the following steps in parallel:

   1. Let contextMenusMap be this’s context menu map.

   2. Remove contextMenusMap[id].

   3. Resolve p with undefined.

The removeAll() method steps are:

1. Let p be a new promise.

2. Run the following steps in parallel:

   1. Let contextMenusMap be this’s context menu map.

   2. Clear contextMenusMap.

   3. Resolve p with undefined.

The update(id, properties) method steps are:

1. Let p be a new promise.

2. Run the following steps in parallel:

   1. Let contextMenusMap be this’s context menu map.

   2. If contextMenusMap[id] does not exist, reject p with a TypeError and abort these steps.

   3. Set contextMenusMap[id] to properties.

   4. Resolve p with undefined.

When a context menu is opened at HTMLElement element inside the embedded document, to return a boolean value for whether the context menu item associated with a ContextMenusProperties properties will be shown:

1. Let documentUrl be the URL of the document that element belongs to.

2. Let targetUrl be an empty string.

   1. If element is an instance of HTMLImageElement, then set targetUrl to the src attribute of element.

   2. If element is an instance of HTMLVideoElement, then set targetUrl to the src attribute of element.

   3. If element is an instance of HTMLAudioElement, then set targetUrl to the src attribute of element.

   4. If element is an instance of HTMLAnchorElement, then set targetUrl to the href attribute of element.

3. If properties["context"] is not empty:

   1. Let result be a boolean value that is initially false.

   2. For each context in properties["context"]:

      1. If element matches context, set result to true and break;

      There is no standardized specifications for matching a HTMLElement against a ContextType.

   3. If result is false, return false.

4. If properties["documentUrlPatterns"] is not empty:

   1. Let result be a boolean value that is initially false.

   2. For each urlPattern in properties["documentUrlPatterns"]:

      1. If documentUrl matches a URL pattern, given urlPattern, set result to true and break;

   3. If result is false, return false.

5. If properties["targetUrlPatterns"] is not empty:

   1. Let result be a boolean value that is initially false.

   2. For each urlPattern in properties["targetUrlPatterns"]:

      1. If targetUrl matches a URL pattern, given urlPattern, set result to true and break;

   3. If result is false, return false.

Note: Different user agents may implement additional conditions.

1. Return true.

The addListener(callback) method steps are:

1. Let callbackList be the event listener list of the ContextMenusEvent.

2. If callbackList[callback] exists, return.

3. Append callback to callbackList.

The removeListener(callback) method steps are:

1. Let callbackList be the event listener list of the ContextMenusEvent.

2. If callbackList[callback] exists, remove callback from callbackList.

The hasListener(callback) method steps are:

1. Let callbackList be the event listener list of the ContextMenusEvent.

2. If callbackList[callback] exists, return true.

3. Otherwise, return false.

The hasListeners() method steps are:

1. Let callbackList be the event listener list of the ContextMenusEvent.

2. If callbackList is empty, return false.

3. Otherwise, return true.

The dispatch(data) method steps are:

1. Let callbackList be the event listener list of the ContextMenusEvent.

2. For each callback in callbackList:

   1. Invoke callback with data.

To dispatched an onShow event:

1. Invoke onShow’s dispatch(data) with no argument.

To dispatch an onClicked event, given element as the HTMLElement inside the embedded document where the context menu is opened at, id as the key of the context menu map’s entry that is associated with the context menu item.

1. Let info be a new OnClickData.

   1. Update the following fields of info:

      editable

      Whether element is editable. what is "editable"?

      frameId

      The frameId of the navigable container from which the contextmenu event is dispatched.

      frameUrl

      The URL of the navigable container from which the contextmenu event is dispatched.

      menuItemId

      id.

      pageUrl

      The URL of the embedded navigable.

   2. Update the following optional fields of info:

      Note: Different user agents may set these fields differently.

      checked

      Whether the context menu item is checked.

      linkUrl

      If element is an instance of HTMLAnchorElement, element’s href attribute.

      mediaType

      One of "image", "video", or "audio", if any, based on element.

      parentMenuId

      The ID of the parent, if a parent exists.

      selectionText

      The text for the context selection, if any.

      srcUrl

      The "src" attribute of element, if it exists.

      wasChecked

      The state of a checkbox or radio item before it was clicked.

2. Invoke onShow’s dispatch(data) with info.

3. Let properties be the result of getting the value of the entry in context menu map given the key id.

4. If the onclick field of properties is not null, invoke onclick with info.