WebDriver BiDi

When an algorithm algorithm running in parallel awaits a set of events events, and resume id:

1. Pause the execution of algorithm.

2. Assert: wait queue does not contain resume id.

3. Set wait queue[resume id] to (events, algorithm).

To resume given name, id and parameters:

1. If wait queue does not contain id, return.

2. Let (events, algorithm) be wait queue[id]

3. For each event in events:

   1. If event equals name:

      1. Remove id from wait queue.

      2. Resume running the steps in algorithm from the point at which they were paused, passing name and parameters as the result of the await.

         Should we have something like microtasks to ensure this runs before any other tasks on the event loop?

Note: this algorithm allows accessing the WebDriver configuration for a given navigable by checking values in navigables, then in user contexts and finally in global. Returns unset if configuration is not set.

To get WebDriver configuration value of WebDriver configuration configuration for navigable navigable:

1. Let top-level traversable be navigable’s top-level traversable.

2. If configuration’s navigables contains top-level traversable:

   1. Let navigable configuration value be configuration’s navigables[top-level traversable].

   2. If navigable configuration value is not unset, return navigable configuration value.

3. Let user context be navigable’s associated user context.

4. If configuration’s user contexts contains user context:

   1. Let user context configuration value be configuration’s user contexts[user context].

   2. If user context configuration value is not unset, return user context configuration value.

5. Return configuration’s global.

Note: this is a generic algorithm for storing WebDriver configuration per target, which can be either navigable, user context, or store it globally if the target is null or omitted.

To store WebDriver configuration configuration’s value value in optional target which is a navigable, a user context or null if not provided:

1. If target is null, set configuration’s global to value.

2. If target is a user context, set configuration’s user contexts[target] to value.

3. If target is a navigable, set configuration’s navigables[target] to value.

Note: This generic algorithm stores WebDriver configuration’s value in global, user contexts, or navigables, depending on the presence of "userContexts" and "contexts" in command parameters. These parameters are mutually exclusive. If neither is provided, the configuration is stored globally.

To store WebDriver configuration WebDriver configuration configuration’s value value for given command parameters:

1. If command parameters contains "userContexts" and command parameters contains "contexts", return error with error code invalid argument.

2. Let affected navigables be an empty set.

3. If command parameters contains "contexts":

   1. Let navigables be the result of trying to get valid top-level traversables by ids with command parameters["contexts"].

   2. For each navigable of navigables:

      1. Append navigable to affected navigables.

      2. Store configuration’s value in navigable.

4. Otherwise, if command parameters contains "userContexts":

   1. Let user contexts be the result of trying to get valid user contexts with command parameters["userContexts"].

   2. For each user context of user contexts:

      1. For each top-level traversable in the list of all top-level traversables whose associated user context is user context:

         1. Append top-level traversable to affected navigables.

      2. Store configuration’s value in user context.

5. Otherwise:

   1. For each top-level traversable of all top-level traversables, append top-level traversable to affected navigables.

   2. Store configuration’s value.

6. Return affected navigables.

Command = {
  id: js-uint,
  CommandData,
  Extensible,
}

CommandData = (
  BrowserCommand //
  BrowsingContextCommand //
  EmulationCommand //
  InputCommand //
  NetworkCommand //
  ScriptCommand //
  SessionCommand //
  StorageCommand //
  WebExtensionCommand
)

EmptyParams = {
   Extensible
}

Message = (
  CommandResponse /
  ErrorResponse /
  Event
)

CommandResponse = {
  type: "success",
  id: js-uint,
  result: ResultData,
  Extensible
}

ErrorResponse = {
  type: "error",
  id: js-uint / null,
  error: ErrorCode,
  message: text,
  ? stacktrace: text,
  Extensible
}

ResultData = (
  BrowserResult /
  BrowsingContextResult /
  EmulationResult /
  InputResult /
  NetworkResult /
  ScriptResult /
  SessionResult /
  StorageResult /
  WebExtensionResult
)

EmptyResult = {
  Extensible
}

Event = {
  type: "event",
  EventData,
  Extensible
}

EventData = (
  BrowsingContextEvent //
  InputEvent //
  LogEvent //
  NetworkEvent //
  ScriptEvent
)

Extensible = (*text => any)

js-int = -9007199254740991..9007199254740991
js-uint = 0..9007199254740991

The list of active BiDi sessions is given by:

1. Let BiDi sessions be a new list.

2. For each session in active sessions:

   1. If session is a BiDi session append session to BiDi sessions.

3. Return BiDi sessions.

ErrorCode = "invalid argument" /
            "invalid selector" /
            "invalid session id" /
            "invalid web extension" /
            "move target out of bounds" /
            "no such alert" /
            "no such network collector" /
            "no such element" /
            "no such frame" /
            "no such handle" /
            "no such history entry" /
            "no such intercept" /
            "no such network data" /
            "no such node" /
            "no such request" /
            "no such screencast" /
            "no such script" /
            "no such storage partition" /
            "no such user context" /
            "no such web extension" /
            "session not created" /
            "unable to capture screen" /
            "unable to close browser" /
            "unable to set cookie" /
            "unable to set file input" /
            "unavailable network data" /
            "underspecified storage partition" /
            "unknown command" /
            "unknown error" /
            "unsupported operation"

The set of sessions for which an event is enabled given event name and navigables is:

1. Let sessions be a new set.

2. For each session in active BiDi sessions:

   1. If event is enabled with session, event name and navigables, append session to sessions.

3. Return sessions.

To determine if an event is enabled given session, event name and navigables:

Note: navigables is a set because a shared worker can be associated with multiple contexts.

1. Let top-level traversables be get top-level traversables with navigables.

2. For each subscription in session’s subscriptions:

   1. If subscription’s event names do not contains event name, continue.

   2. If subscription is global return true.

   3. If user context ids is not empty:

      1. For each navigable in top-level traversables:

         1. If subscription’s user context ids contains navigable’s associated user context’s user context id, return true.

   4. Otherwise:

      1. Let subscription top-level traversables be get navigables by ids with subscription’s top-level traversable ids.

      2. If the intersection of top-level traversables and subscription top-level traversables is not empty return true.

3. Return false.

The set of top-level traversables for which an event is enabled given event name and session is:

1. Let result be a new set.

2. For each subscription in session’s subscriptions:

   1. If subscription’s event names does not contain event name, continue.

   2. If subscription’s is global:

      1. For each traversable in remote end’s top-level traversables:

         1. Append traversable to result.

      2. Break.

   3. Otherwise, if user context ids is not empty:

      1. For each traversable in remote end’s top-level traversables:

         1. Append traversable to result if subscription’s user context ids contains traversable’s associated user context’s user context id.

   4. Otherwise:

      1. Let top-level traversables be get navigables by ids with subscription’s top-level traversable ids.

      2. Append each item of top-level traversables to result.

3. Return result.

To obtain a set of event names given a name:

1. Let events be an empty set.

2. If name contains a U+002E (period):

   1. If name is the event name for an event, append name to events and return success with data events.

   2. Return an error with error code invalid argument

3. Otherwise name is interpreted as representing all the events in a module. If name is not a module name return an error with error code invalid argument.

4. Append the event name for each event in the module with name name to events.

5. Return success with data events.

To construct a WebSocket resource name given a session session:

1. If session is null, return "/session"

2. Return the result of concatenating the string "/session/" with session’s session ID.

To construct a WebSocket URL given a WebSocket listener listener and session session:

1. Let resource name be the result of construct a WebSocket resource name with session.

2. Return a WebSocket URI constructed with host set to listener’s host, port set to listener’s port, path set to resource name, following the wss-URI construct if listener’s secure flag is set and the ws-URL construct otherwise.

To get a session ID for a WebSocket resource given resource name:

1. If resource name doesn’t begin with the byte string "/session/", return null.

2. Let session id be the bytes in resource name following the "/session/" prefix.

3. If session id is not the string representation of a UUID, return null.

4. Return session id.

To start listening for a WebSocket connection given a session session:

1. If there is an existing WebSocket listener in active listeners which the remote end would like to reuse, let listener be that listener. Otherwise let listener be a new WebSocket listener with implementation-defined host, port, secure flag, and an empty list of WebSocket resources.

2. Let resource name be the result of construct a WebSocket resource name with session.

3. Append resource name to the list of WebSocket resources for listener.

4. Append listener to the remote end’s active listeners.

5. Return listener.

To handle an incoming message given a WebSocket connection connection, type type and data data:

1. If type is not text, send an error response given connection, null, and invalid argument, and finally return.

2. Assert: data is a scalar value string, because the WebSocket handling errors in UTF-8-encoded data would already have failed the WebSocket connection otherwise.

   Nothing seems to define what status code is used for UTF-8 errors.

3. If there is a BiDi Session associated with connection connection, let session be that session. Otherwise if connection is in WebSocket connections not associated with a session, let session be null. Otherwise, return.

4. Let parsed be the result of parsing JSON into Infra values given data. If this throws an exception, then send an error response given connection, null, and invalid argument, and finally return.

5. If session is not null and not in active sessions then return.

6. Match parsed against the remote end definition. If this results in a match:

   1. Let matched be the map representing the matched data.

   2. Assert: matched contains "id", "method", and "params".

   3. Let command id be matched["id"].

   4. Let method be matched["method"]

   5. Let command be the command with command name method.

   6. If session is null and command is not a static command, then send an error response given connection, command id, and invalid session id, and return.

   7. Run the following steps in parallel:

      1. Let result be the result of running the remote end steps for command given session and command parameters matched["params"]

      2. If result is an error, then send an error response given connection, command id, and result’s error code, and finally return.

      3. Let value be result’s data.

      4. Assert: value matches the definition for the result type corresponding to the command with command name method.

      5. If method is "session.new", let session be the entry in the list of active sessions whose session ID is equal to the "sessionId" property of value, append connection to session’s session WebSocket connections, and remove connection from the WebSocket connections not associated with a session.

      6. Let response be a new map matching the CommandResponse production in the local end definition with the id field set to command id and the value field set to value.

      7. Let serialized be the result of serialize an infra value to JSON bytes given response.

      8. Send a WebSocket message comprised of serialized over connection.

7. Otherwise:

   1. Let command id be null.

   2. If parsed is a map and parsed["id"] exists and is an integer greater than or equal to zero, set command id to that integer.

   3. Let error code be invalid argument.

   4. If parsed is a map and parsed["method"] exists and is a string, but parsed["method"] is not in the set of all command names, set error code to unknown command.

   5. Send an error response given connection, command id, and error code.

To get related navigables given an settings object settings:

1. Let related navigables be an empty set.

2. If settings’ relevant global object is a Window:

   1. Let navigable be relevant global object’s associated Document’s node navigable.

   2. If navigable is not null, append navigable to related navigables.

3. Otherwise if the global object specified by settings is a WorkerGlobalScope, for each owner in the global object’s owner set:

   1. Let navigable be null.

   2. If owner is a Document, set navigable to owner’s node navigable.

   3. If navigable is not null, append navigable to related navigables.

4. Return related navigables.

To get navigables by ids given a list of context ids navigable ids:

1. Let result be an empty set.

2. For each navigable id in navigable ids:

   1. Let navigable be the navigable with id navigable id if such navigable exists, and null otherwise.

   2. Append navigable to result if navigable is not null.

3. Return result.

To get top-level traversables given a list of navigables navigables:

1. Let result be an empty set.

2. For each navigable in navigables:

   1. Append navigable’s top-level traversable to result.

3. Return result.

To get valid navigables by ids given a list of context ids navigable ids:

1. Let result be an empty set.

2. For each navigable id in navigable ids:

   1. Let navigable be the result of trying to get a navigable with navigable id.

   2. Append navigable to result.

3. Return success with data result.

To get valid top-level traversables by ids given a list of context ids navigable ids:

1. Let result be an empty set.

2. For each navigable id in navigable ids:

   1. Let navigable be the result of trying to get a navigable with navigable id.

   2. If navigable is not a top-level traversable, return error with error code invalid argument.

   3. Append navigable to result.

3. Return success with data result.

To emit an event given session, and body:

1. Assert: body matches the Event production.

2. Let serialized be the result of serialize an infra value to JSON bytes given body.

3. For each connection in session’s session WebSocket connections:

   1. Send a WebSocket message comprised of serialized over connection.

To send an error response given a WebSocket connection connection, command id, and error code:

1. Let error data be a new map matching the ErrorResponse production in the local end definition, with the id field set to command id, the error field set to error code, the message field set to an implementation-defined string containing a human-readable definition of the error that occurred and the stacktrace field optionally set to an implementation-defined string containing a stack trace report of the active stack frames at the time when the error occurred.

2. Let response be the result of serialize an infra value to JSON bytes given error data.

   Note: command id can be null, in which case the id field will also be set to null, not omitted from response.

3. Send a WebSocket message comprised of response over connection.

To handle a connection closing given a WebSocket connection connection:

1. If there is a BiDi session associated with connection connection:

   1. Let session be the BiDi session associated with connection connection.

   2. Remove connection from session’s session WebSocket connections.

2. Otherwise, if WebSocket connections not associated with a session contains connection, remove connection from that set.

Note: This does not end any session.

Need to hook in to the session ending to allow the UA to close the listener if it wants.

To close the WebSocket connections given session:

1. For each connection in session’s session WebSocket connections:

   1. Start the WebSocket closing handshake with connection.

      Note: this will result in the steps in handle a connection closing being run for connection, which will clean up resources associated with connection.

The WebDriver new session algorithm defined by this specification, with parameters session, capabilities, and flags is:

1. If flags contains "bidi", return.

2. Let webSocketUrl be the result of getting a property named "webSocketUrl" from capabilities.

3. If webSocketUrl is undefined, return.

4. Assert: webSocketUrl is true.

5. Let listener be the result of start listening for a WebSocket connection given session.

6. Set webSocketUrl to the result of construct a WebSocket URL with listener and session.

7. Set a property on capabilities named "webSocketUrl" to webSocketUrl.

8. Set session’s BiDi flag to true.

9. Append "bidi" to flags.

Implementations should also allow clients to establish a BiDi Session which is not a HTTP Session. In this case the URL to the WebSocket server is communicated out-of-band. An implementation that allows this supports BiDi-only sessions. At the time such an implementation is ready to accept requests to start a WebDriver session, it must:

1. Start listening for a WebSocket connection given null.

To get or create a sandbox realm given name and navigable:

1. If name is an empty string, then return error with error code invalid argument.

2. Let window be navigable’s active window.

3. If sandbox map does not contain window, set sandbox map[window] to a new map.

4. Let sandboxes be sandbox map[window].

5. If sandboxes does not contain name, set sandboxes[name] to create a sandbox realm with navigable.

6. Return success with data sandboxes[name].

To create a sandbox realm with window:

Define creation of sandbox realm. This is going to return a SandboxWindowProxy wrapping window.

To get a sandbox name given target realm:

1. Let realms maps be get the values of sandbox map.

2. For each realms map in realms maps:

   1. For each name → realm in realms map:

      1. If realm is target realm, return name.

3. Return null.

To get unwrapped object:

1. While object is SandboxProxy or SandboxWindowProxy, set object to it’s wrapped object.

2. Return object.

To remove user context subscriptions:

1. For each session in active sessions:

   1. Let subscriptions to remove be a set.

   2. For each subscription in session’s subscriptions:

      1. If subscription’s user context ids contains navigable’s associated user context’s user context id;

         1. Remove navigable’s associated user context’s user context id from subscription’s user context ids.

         2. If subscription’s user context ids is empty:

            1. Append subscription to subscriptions to remove.

   3. Remove subscriptions to remove from session’s subscriptions.

To get user context given user context id:

1. For each user context in the set of user contexts:

2. If user context’s user context id equals user context id:

   1. Return user context.

3. Return null.

To get valid user contexts given user context ids:

1. Let result be an empty set.

2. For each user context id of user context ids:

   1. Set user context to get user context with user context id.

   2. If user context is null, return error with error code no such user context.

   3. Append user context to result.

3. Return result.

SessionCommand = (
  session.End //
  session.New //
  session.Status //
  session.Subscribe //
  session.Unsubscribe
)

SessionResult = (
  session.EndResult /
  session.NewResult /
  session.StatusResult /
  session.SubscribeResult /
  session.UnsubscribeResult
)

To end the session given session:

1. Remove session from active sessions.

2. If active sessions is empty, set the webdriver-active flag to false.

To cleanup the session given session:

1. Close the WebSocket connections with session.

2. For each user context in the set of user contexts:

   1. Remove session’s user context to accept insecure certificates override map[user context].

   2. Remove session’s user context to proxy configuration map[user context].

3. For each request id → (request, phase, response) in session’s blocked request map:

   1. Resume with "continue request", request id and (response, "incomplete").

4. For each collector in session’s network collectors:

   1. Let collector id be collector’s collector.

   2. For each collected data in collected network data, remove collector from data with collected data and collector id.

5. For each screencast recording in session’s screencast recordings map:

   1. Stop a screencast recording given screencast recording.

   2. Remove screencast recording from screencast recordings map.

6. If active sessions is empty, cleanup remote end state.

7. Perform any implementation-specific cleanup steps.

To cleanup remote end state.

1. Clear the before request sent map.

2. Set the default cache behavior to "default".

3. Clear the navigable cache behavior map.

4. Perform implementation-defined steps to enable any implementation-specific resource caches that are usually enabled in the current remote end configuration.

session.CapabilitiesRequest = {
  ? alwaysMatch: session.CapabilityRequest,
  ? firstMatch: [*session.CapabilityRequest]
}

session.CapabilityRequest = {
  ? acceptInsecureCerts: bool,
  ? browserName: text,
  ? browserVersion: text,
  ? platformName: text,
  ? proxy: session.ProxyConfiguration,
  ? unhandledPromptBehavior: session.UserPromptHandler,
  Extensible
}

The additional capability deserialization algorithm for the "webSocketUrl" capability, with parameter value is:

1. If value is not a boolean, return error with code invalid argument.

2. Return success with data value.

The matched capability serialization algorithm for the "webSocketUrl" capability, with parameter value is:

1. If value is false, return success with data null.

2. Return success with data true.

session.ProxyConfiguration = {
   session.AutodetectProxyConfiguration //
   session.DirectProxyConfiguration //
   session.ManualProxyConfiguration //
   session.PacProxyConfiguration //
   session.SystemProxyConfiguration
}

session.AutodetectProxyConfiguration = (
   proxyType: "autodetect",
   Extensible
)

session.DirectProxyConfiguration = (
   proxyType: "direct",
   Extensible
)

session.ManualProxyConfiguration = (
   proxyType: "manual",
   ? httpProxy: text,
   ? sslProxy: text,
   ? session.SocksProxyConfiguration,
   ? noProxy: [*text],
   Extensible
)

session.SocksProxyConfiguration = (
   socksProxy: text,
   socksVersion: 0..255,
)

session.PacProxyConfiguration = (
   proxyType: "pac",
   proxyAutoconfigUrl: text,
   Extensible
)

session.SystemProxyConfiguration = (
   proxyType: "system",
   Extensible
)

session.UserPromptHandler = {
  ? alert: session.UserPromptHandlerType,
  ? beforeUnload: session.UserPromptHandlerType,
  ? confirm: session.UserPromptHandlerType,
  ? default: session.UserPromptHandlerType,
  ? file: session.UserPromptHandlerType,
  ? prompt: session.UserPromptHandlerType,
}

session.UserPromptHandlerType = "accept" / "dismiss" / "ignore";

session.Subscription = text

session.SubscribeParameters = {
  events: [+text],
  ? contexts: [+browsingContext.BrowsingContext],
  ? userContexts: [+browser.UserContext],
}

session.UnsubscribeByIDRequest = {
  subscriptions: [+session.Subscription],
}

session.UnsubscribeByAttributesRequest = {
  events: [+text],
}

The remote end steps given session, and command parameters are:

1. Let body be a new map with the following properties:

   "ready"

   The remote end’s readiness state.

   "message"

   An implementation-defined string explaining the remote end’s readiness state.

2. Return success with data body

The remote end steps given session and command parameters are:

1. If session is not null, return an error with error code session not created.

2. If the implementation is unable to start a new session for any reason, return an error with error code session not created.

3. Let flags be a set containing "bidi".

4. Let capabilities json be the result of trying to process capabilities with command parameters and flags.

5. Let capabilities be convert a JSON-derived JavaScript value to an Infra value with capabilities json.

6. Let session be the result of trying to create a session with capabilities and flags.

7. Set session’s BiDi flag to true.

   Note: the connection for this session will be set to the current connection by the caller.

8. Let body be a new map matching the session.NewResult production, with the sessionId field set to session’s session ID, and the capabilities field set to capabilities.

9. Return success with data body.

The remote end steps given session and command parameters are:

1. End the session with session.

2. Return success with data null, and in parallel run the following steps:

   1. Wait until the Send a WebSocket message steps have been called with the response to this command.

      this is rather imprecise language, but hopefully it’s clear that the intent is that we send the response to the command before starting shutdown of the connections.

   2. Cleanup the session with session.

The remote end steps with session and command parameters are:

1. Let event names be an empty set.

2. For each entry name in command parameters["events"], let event names be the union of event names and the result of trying to obtain a set of event names with name.

3. Let input user context ids be create a set with command parameters[userContexts].

4. Let input context ids be create a set with command parameters[contexts].

5. If input user context ids is not empty and input context ids is not empty, return error with error code invalid argument.

6. Let subscription navigables be a set.

7. Let top-level traversable context ids be a set.

8. If input context ids is not empty:

   1. Let navigables be the result of trying to get valid navigables by ids with input context ids.

   2. Set subscription navigables be get top-level traversables with navigables.

   3. For each navigable in subscription navigables:

      1. Append navigable’s navigable id to top-level traversable context ids.

9. Otherwise, if input user context ids is not empty:

   1. For each user context id of input user context ids:

      1. Let user context be get user context with user context id.

      2. If user context is null, return error with error code no such user context.

      3. For each top-level traversable in the list of all top-level traversables whose associated user context is user context:

         1. Append top-level traversable to subscription navigables.

10. Otherwise, set subscription navigables to a set of all top-level traversables in the remote end.

11. Let subscription be a subscription with subscription id set to the string representation of a UUID, event names set to event names, top-level traversable ids set to top-level traversable context ids and user context ids set to input user context ids.

12. Let subscribe step events be a new map.

13. For each event name in the event names:

    1. If the event with event name event name does not define remote end subscribe steps, continue;

    2. Let existing navigables be a set of top-level traversables for which an event is enabled with session and event name.

    3. Set subscribe step events[event name] to difference of subscription navigables and existing navigables.

14. Append subscription to session’s subscriptions.

15. Append subscription’s subscription id to session’s known subscription ids.

16. Sort in ascending order subscribe step events using the following less than algorithm given two entries with keys event name one and event name two:

    1. Let event one be the event with name event name one

    2. Let event two be the event with name event name two

    3. Return true if event one’s subscribe priority is less than event two’s subscribe priority, or false otherwise.

17. If subscription is global, let include global be true, otherwise let include global be false.

18. For each event name → navigables in subscribe step events:

    1. Run the remote end subscribe steps for the event with event name event name given session, navigables and include global.

19. Let body be a new map matching the session.SubscribeResult production, with the subscription field set to subscription’s subscription id.

20. Return success with data body.

The remote end steps with session and command parameters are:

1. If command parameters does not contain "subscriptions":

   Note: The condition implies that command parameters is matching the session.UnsubscribeByAttributesRequest production.

   1. Let event names be an empty set.

   2. For each entry name in command parameters["events"], let event names be the union of event names and the result of trying to obtain a set of event names with name.

   3. Let new subscriptions to be a list.

   4. Let matched events to be a set.

   5. For each subscription of session’s subscriptions:

      1. If intersection of subscription’s event names and event names is an empty set:

         1. append subscription to new subscriptions.

         2. Continue.

      2. If subscription is not global:

         1. append subscription to new subscriptions.

         2. Continue.

      3. Let subscription event names be clone of subscription’s event names.

      4. For each event name of event names:

         1. If subscription event names contains event name:

            1. Append event name to matched events.

            2. Remove event name from subscription event names.

      5. If subscription event names is not empty:

         1. Let cloned subscription be a subscription with subscription id set to subscription’s subscription id, event names set to a new set containing subscription event names.

         2. append cloned subscription to new subscriptions.

   6. If matched events is not equal to event names, return error with error code invalid argument.

   7. Set session’s subscriptions to new subscriptions.

2. Otherwise:

   1. Let subscriptions be create a set with command parameters[subscriptions].

   2. Let unknown subscription ids to difference between subscriptions and session’s known subscription ids.

   3. If unknown subscription ids is not empty:

      1. Return error with error code invalid argument.

   4. Let subscriptions to remove be an empty set.

   5. For each subscription in session’s subscriptions:

      1. If subscriptions contains subscription’s subscription id:

         1. Append subscription to subscriptions to remove.

   6. Set session’s known subscription ids to difference between session’s known subscription ids and subscriptions.

   7. Remove each item in subscriptions to remove from session’s subscriptions.

3. Return success with data null.

BrowserCommand = (
  browser.Close //
  browser.CreateUserContext //
  browser.GetClientWindows //
  browser.GetUserContexts //
  browser.RemoveUserContext //
  browser.SetClientWindowState //
  browser.SetDownloadBehavior
)

BrowserResult = (
  browser.CloseResult /
  browser.CreateUserContextResult /
  browser.GetClientWindowsResult /
  browser.GetUserContextsResult /
  browser.RemoveUserContextResult /
  browser.SetClientWindowStateResult /
  browser.SetDownloadBehaviorResult
)

To get the client window state given window:

1. Let documents be an empty list.

2. Let visible documents be an empty list.

3. For each top-level traversable traversable:

   1. If traversable’s client window is not window then continue.

   2. Let document be traversable’s active document.

   3. Append document to documents.

   4. If document’s visibility state is "visible", Append document to visible documents.

4. For each document in visible documents:

   1. If document’s fullscreen element is not null, return "fullscreen".

5. If visible documents is empty but documents is not empty, or if window is otherwise in an OS-specific minimized state, return "minimized".

   Note: This will usually, but not necessarily, mean that window’s width and height are equal to 0.

6. If window is in an OS-specific maximized state return "maximized".

   Note: This will usually, but not necessarily, mean that window’s width is equal to the width of the web-exposed screen area and window’s height is equal to the height of the web-exposed screen area.

7. Return "normal".

To set the client window state given window and state:

1. Let current state be get the client window state with window.

2. If current state is "fullscreen", "maximized", or "minimized" and is equal to state, return success with data null.

3. In the following list of conditions and associated steps, run the first set of steps for which the associated condition is true:

   "fullscreen"

   If not fullscreen is supported return error with error code unsupported operation.

   "normal"

   If not restore client window is supported for window return error with error code unsupported operation.

   "maximize"

   If not maximize client window is supported for window return error with error code unsupported operation.

   "minimize"

   If not minimize client window is supported for window return error with error code unsupported operation.

4. Let documents be an empty list.

5. For each top-level traversable traversable:

   1. If traversable’s associated client window is not window then continue.

   2. Let document be traversable’s active document.

   3. Append document to documents.

6. If documents is empty return error with error code no such client window.

7. If current state is "fullscreen":

   1. For each document in documents:

      1. Fully exit fullscreen with document.

         Note: This is a no-op for documents in window that are not fullscreen.

8. If current state is "maximized" or "minimized":

   1. Restore the client window window.

9. Switch on the value of state:

   "fullscreen"

   1. For each document in documents:

      1. If document’s visibility state is "visible", fullscreen an element with document’s document element.

      2. Break.

   "maximize"

   1. Maximize the client window window.

   "minimize"

   1. Minimize the client window window.

10. Return success with data null.

browser.ClientWindow = text;

browser.ClientWindowInfo = {
  active: bool,
  clientWindow: browser.ClientWindow,
  height: js-uint,
  state: "fullscreen" / "maximized" / "minimized" / "normal",
  width: js-uint,
  x: js-int,
  y: js-int,
}

To get the client window info given client window:

1. Let client window id be the client window id for client window.

2. Let state be get the client window state with client window.

3. If client window can receive keyboard input channeled from the operating system, let active be true, otherwise let active be false.

   Note: This could mean that a top-level traversable whose client window is client window has system focus, or it could mean that the user interface of the browser itself currently has focus.

4. Let client window info be a map matching the browser.ClientWindowsInfo production with the clientWindow field set to client window id, state field set to state, the x field set to client window’s x-coordinate, the y field set to client window’s y-coordinate, the width field set to client window’s width, the height field set to client window’s height, and the active field set to active.

5. Return client window info

browser.UserContext = text;

browser.UserContextInfo = {
  userContext: browser.UserContext
}

The remote end steps with session and command parameters are:

1. End the session with session.

2. If active sessions is not empty an implementation may return error with error code unable to close browser, and then run the following steps in parallel:

   1. Wait until the Send a WebSocket message steps have been called with the response to this command.

   2. Cleanup the session with session.

   Note: The behaviour in cases where the browser has multiple automation sessions is currently unspecified. It might be that any session can close the browser, or that only the final open session can actually close the browser, or only the first session started can. This behaviour might be fully specified in a future version of this specification.

3. For each active session in active sessions:

   1. End the session active session.

   2. Cleanup the session with active session

4. Return success with data null, and run the following steps in parallel.

   1. Wait until the Send a WebSocket message steps have been called with the response to this command.

   2. Cleanup the session with session.

   3. Close any top-level traversables without prompting to unload.

   4. Perform implementation defined steps to clean up resources associated with the remote end under automation.

      Note: For example this might include cleanly shutting down any OS-level processes associated with the browser under automation, removing temporary state, such as user profile data, created by the remote end while under automation, or shutting down the WebSocket Listener. Because of differences between browsers and operating systems it is not possible to specify in detail precise invariants local ends can depend on here.

The remote end steps with session and command parameters are:

1. Let user context be a new user context.

2. If command parameters contain "acceptInsecureCerts":

   Note: If "acceptInsecureCerts" is set, it overrides the accept insecure TLS flag’s behavior.

   1. Let acceptInsecureCerts be command parameters["acceptInsecureCerts"]:

   2. If acceptInsecureCerts is true and endpoint node doesn’t support accepting insecure TLS connections, return error with error code unsupported operation.

   3. Set session’s user context to accept insecure certificates override map[user context] to acceptInsecureCerts.

3. If command parameters contains "unhandledPromptBehavior", set unhandled prompt behavior overrides map[user context] to command parameters["unhandledPromptBehavior"].

4. If command parameters contains "proxy":

   1. Let proxy configuration be command parameters["proxy"].

   2. If the remote end is unable to configure proxy settings per user context, or is unable to configure the proxy with proxy configuration, return error with error code unsupported operation.

   3. Set session’s user context to proxy configuration map[user context] to proxy configuration.

5. Append user context to the set of user contexts.

6. Let user context info be a map matching the browser.UserContextInfo production with the userContext field set to user context’s user context id.

7. Return success with data user context info.

The remote end steps are:

1. Let client window ids be an empty set.

2. Let client windows be an empty list.

3. For each top-level traversable traversable:

   1. Let client window be traversable’s associated client window

   2. Let client window id be the client window id for client window.

   3. If client window ids contains client window id, continue.

   4. Append client window id to client window ids.

   5. Let client window info be get the client window info with client window.

   6. Append client window info to client windows.

4. Let result be a map matching the browser.GetClientWindowsResult production with the clientWindows field set to client windows.

5. Return success with data result.

The remote end steps are:

1. Let user contexts be an empty list.

2. For each user context in the set of user contexts:

   1. Let user context info be a map matching the browser.UserContextInfo production with the userContext field set to user context’s user context id.

   2. Append user context info to user contexts.

3. Let result be a map matching the browser.GetUserContextsResult production with the userContexts field set to user contexts.

4. Return success with data result.

The remote end steps with command parameters are:

1. Let user context id be command parameters["userContext"].

2. If user context id is "default", return error with error code invalid argument.

3. Set user context to get user context with user context id.

4. If user context is null, return error with error code no such user context.

5. For each top-level traversable navigable:

   1. If navigable’s associated user context is user context:

      1. Close navigable without prompting to unload.

6. Remove user context for the set of user contexts.

7. Return success with data null.

The remote end steps with session and command parameters are:

1. If the implementation does not support setting the client window state at all, then return error with error code unsupported operation.

2. If there is a client window with client window id command parameters["clientWindow"], let client window be that client window. Otherwise return error with error code no such client window.

3. Try to set the client window state with client window and command parameters["state"].

4. If command parameters["state"] is "normal":

   1. If command parameters contains "x" and the implementation supports positioning client windows, set the x-coordinate of client window to a value that is as close as possible command parameters["x"].

   2. If command parameters contains "y" and the implementation supports positioning client windows, set the y-coordinate of client window to a value that is as close as possible command parameters["y"].

   3. If command parameters contains "width" and the implementation supports resizing client windows, set the width of client window to a value that is as close as possible command parameters["width"].

   4. If command parameters contains "width" and the implementation supports resizing client windows, set the width of client window to a value that is as close as possible command parameters["width"].

5. Let client window info be get the client window info with client window.

6. Return success with data client window info.

Note: For simplicity this models all client window operations as synchronous. Therefore the returned client window dimensions are expected to be those after the window has reached its new state.

To get download behavior given navigable:

1. Let user context be navigable’s associated user context.

2. If download behavior’s user context download behavior contains user context, return download behavior’s user context download behavior[user context].

3. Return download behavior’s default download behavior.

The remote end steps with session and command parameters are:

1. If command parameters["downloadBehavior"] is null, let download behavior be null.

2. Otherwise:

   1. If command parameters["downloadBehavior"]["type"] is "allowed", let allowed be true, otherwise let allowed be false.

   2. If command parameters["downloadBehavior"] contains "destinationFolder", let destinationFolder be command parameters["downloadBehavior"]["destinationFolder"], otherwise let destinationFolder be null.

   3. Let download behavior be a download behavior struct with allowed set to allowed and destinationFolder set to destinationFolder.

3. If the implementation does not support required download behavior, then return error with error code unsupported operation.

4. If the userContexts field of command parameters is present:

   1. Let user contexts be the result of trying to get valid user contexts with command parameters["userContexts"].

   2. For each user context of user contexts:

      1. If download behavior is null, remove user context from download behavior’s user context download behavior.

      2. Otherwise, set download behavior’s user context download behavior[user context] to download behavior.

5. Otherwise, set download behavior’s default download behavior to download behavior.

6. Return success with data null.

BrowsingContextCommand = (
  browsingContext.Activate //
  browsingContext.CaptureScreenshot //
  browsingContext.Close //
  browsingContext.Create //
  browsingContext.GetTree //
  browsingContext.HandleUserPrompt //
  browsingContext.LocateNodes //
  browsingContext.Navigate //
  browsingContext.Print //
  browsingContext.Reload //
  browsingContext.SetBypassCSP //
  browsingContext.SetViewport //
  browsingContext.StartScreencast //
  browsingContext.StopScreencast //
  browsingContext.TraverseHistory
)

BrowsingContextResult = (
  browsingContext.ActivateResult /
  browsingContext.CaptureScreenshotResult /
  browsingContext.CloseResult /
  browsingContext.CreateResult /
  browsingContext.GetTreeResult /
  browsingContext.HandleUserPromptResult /
  browsingContext.LocateNodesResult /
  browsingContext.NavigateResult /
  browsingContext.PrintResult /
  browsingContext.ReloadResult /
  browsingContext.SetBypassCSPResult /
  browsingContext.SetViewportResult /
  browsingContext.StartScreencastResult /
  browsingContext.StopScreencastResult /
  browsingContext.TraverseHistoryResult
)

BrowsingContextEvent = (
  browsingContext.ContextCreated //
  browsingContext.ContextDestroyed //
  browsingContext.DomContentLoaded //
  browsingContext.DownloadEnd //
  browsingContext.DownloadWillBegin //
  browsingContext.FragmentNavigated //
  browsingContext.HistoryUpdated //
  browsingContext.Load //
  browsingContext.NavigationAborted //
  browsingContext.NavigationCommitted //
  browsingContext.NavigationFailed //
  browsingContext.NavigationStarted //
  browsingContext.UserPromptClosed //
  browsingContext.UserPromptOpened
)

To start a screencast recording given a screencast recording recording and mime type:

1. Run the following steps in parallel:

   1. Begin encoding recording’s stream using mime type, producing successive chunks of encoded data as byte sequences. Produce a new chunk at the implementation defined interaval while recording’s state is "recording".

   2. For each chunk bytes produced for recording, run the following steps:

      1. Append bytes to the file at recording’s path. If this fails:

         1. Set recording’s writeError to an implementation-defined string describing the write failure.

         2. Stop a screencast recording given recording.

To stop a screencast recording given a screencast recording recording:

1. If recording’s state is not "recording" then return.

2. Set recording’s state to "stopping".

3. Stop producing new chunks for recording, flush any remaining encoded data as a final chunk (processed as in start a screencast recording), stop capturing from recording’s stream and release its video track and, if present, its audio track, and then set recording’s state to "stopped".

4. Wait until recording’s state is "stopped".

browsingContext.BrowsingContext = text;

To get a navigable given navigable id:

1. If navigable id is null, return success with data null.

2. If there is no navigable with navigable id navigable id return error with error code no such frame

3. Let navigable be the navigable with id navigable id.

4. Return success with data navigable.

browsingContext.InfoList = [*browsingContext.Info]

browsingContext.Info = {
  children: browsingContext.InfoList / null,
  clientWindow: browser.ClientWindow,
  context: browsingContext.BrowsingContext,
  originalOpener: browsingContext.BrowsingContext / null,
  url: text,
  userContext: browser.UserContext,
  ? parent: browsingContext.BrowsingContext / null,
}

To get the child navigables given navigable:

TODO: make this return a list in document order

1. Let child navigables be a set containing all navigables that are a child navigable of navigable.

2. Return child navigables.

To get the navigable info given navigable, max depth and include parent id:

1. Let navigable id be the navigable id for navigable.

2. Let parent navigable be navigable’s parent.

3. If parent navigable is not null let parent id be the navigable id of parent navigable. Otherwise let parent id be null.

4. Let document be navigable’s active document.

5. Let url be the result of running the URL serializer, given document’s URL.

   Note: This includes the fragment component of the URL.

6. Let child infos be null.

7. If max depth is null, or max depth is greater than 0:

   1. Let child navigables be get the child navigables given navigable.

   2. Let child depth be max depth - 1 if max depth is not null, or null otherwise.

   3. Set child infos to an empty list.

   4. For each child navigable of child navigables:

      1. Let info be the result of get the navigable info given child navigable, child depth, and false.

      2. Append info to child infos

8. Let user context be navigable’s associated user context.

9. Let opener id be the navigable id for navigable’s original opener, if navigable’s original opener is not null, and null otherwise.

10. Let top-level traversable be navigable’s top-level traversable.

11. Let client window id be the client window id for top-level traversable’s associated client window.

12. Let navigable info be a map matching the browsingContext.Info production with the context field set to navigable id, the parent field set to parent id if include parent id is true, or unset otherwise, the url field set to url, the userContext field set to user context’s user context id, originalOpener field set to opener id, the children field set to child infos, and the clientWindow field set to client window id.

13. Return navigable info.

To await a navigation given navigable, request, wait condition, and optionally history handling (default: "default") and ignore cache (default: false):

1. Let navigation id be the string representation of a UUID based on truly random, or pseudo-random numbers.

2. Navigate navigable with resource request, and using navigable’s active document as the source Document, with navigation id navigation id, and history handling behavior history handling. If ignore cache is true, the navigation must not load resources from the HTTP cache.

   property specify how the ignore cache flag works. This needs to consider whether only the first load of a resource bypasses the cache (i.e. whether this is like initially clearing the cache and proceeding like normal), or whether resources not directly loaded by the HTML parser (e.g. loads initiated by scripts or stylesheets) also bypass the cache.

3. Let (event received, navigation status) be await given «"navigation started", "navigation failed", "fragment navigated"», and navigation id.

4. Assert: navigation status’s id is navigation id.

5. If navigation status’s status is "complete":

   1. Let body be a map matching the browsingContext.NavigateResult production, with the navigation field set to navigation id, and the url field set to the result of the URL serializer given navigation status’s url.

   2. Return success with data body.

   Note: this is the case if the navigation only caused the fragment to change.

6. If navigation status’s status is "canceled" return error with error code unknown error.

   TODO: is this the right way to handle errors here?

7. Assert: navigation status’s status is "