WebDriver BiDi

1. Introduction

This section is non-normative.

WebDriver defines a protocol for introspection and remote control of user agents. This specification extends WebDriver by introducing bidirectional communication. In place of the strict command/response format of WebDriver, this permits events to stream from the user agent to the controlling software, better matching the evented nature of the browser DOM.

2. Infrastructure

This specification depends on the Infra Standard. [INFRA]

Network protocol messages are defined using CDDL. [RFC8610]

This specification defines a wait queue which is a map.

Surely there’s a better mechanism for doing this "wait for an event" thing.

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

Pause the execution of algorithm.
Assert: wait queue does not contain resume id.
Set wait queue[resume id] to (events, algorithm).

To resume given name, id and parameters:

If wait queue does not contain id, return.
Let (events, algorithm) be wait queue[id]
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?

3. Protocol

This section defines the basic concepts of the WebDriver BiDi protocol. These terms are distinct from their representation at the transport layer.

The protocol is defined using a CDDL definition. For the convenience of implementors two seperate CDDL definitions are defined; the remote end definition which defines the format of messages produced on the local end and consumed on the remote end, and the local end definition which defines the format of messages produced on the remote end and consumed on the local end

3.1. Definition

Should this be an appendix?

This section gives the initial contents of the remote end definition and local end definition. These are augmented by the definition fragments defined in the remainder of the specification.

Remote end definition

Command = {
  id: uint,
  CommandData,
  *text => any,
}

CommandData = (
  SessionCommand //
  BrowsingContextCommand
)

EmptyParams = { *text }

Local end definition

Message = (
  CommandResponse //
  ErrorResponse //
  Event
)

CommandResponse = {
  id: uint,
  result: ResultData,
  *text => any
}

ErrorResponse = {
  id: uint / null,
  error: "unknown error" / "unknown command" / "invalid argument",
  message: text,
  ?stacktrace: text,
  *text => any
}

ResultData = (
  EmptyResult //
  SessionResult //
  BrowsingContextResult //
  ScriptResult
)

EmptyResult = {}

Event = {
  EventData,
  *text => any
}

EventData = (
  BrowsingContextEvent //
  ScriptEvent
)

3.2. Session

WebDriver BiDi extends the session concept from WebDriver.

A session has a BiDi flag, which is false unless otherwise stated.

A BiDi session is a session which has the BiDi flag set to true.

The set of active BiDi sessions is given by:

Let BiDi sessions be a new set.
For each session in active sessions:
1. If session is a BiDi session append session to BiDi sessions.
Return BiDi sessions

3.3. Modules

The WebDriver BiDi protocol is organized into modules.

Each module represents a collection of related commands and events pertaining to a certain aspect of the user agent. For example, a module might contain functionality for inspecting and manipulating the DOM, or for script execution.

Each module has a module name which is a string. The command name and event name for commands and events defined in the module start with the module name followed by a period ".".

Modules which contain commands define remote end definition fragments. These provide choices in the CommandData group for the module’s commands, and can also define additional definition properties. They can also define local end definition fragments that provide additional choices in the ResultData group for the results of commands in the module.

Modules which contain events define local end definition fragments that are choices in the Event group for the module’s events.

An implementation may define extension modules. These must have a module name that contains a single colon ":" character. The part before the colon is the prefix; this is typically the same for all extension modules specific to a given implementation and should be unique for a given implementation. Such modules extend the local end definition and remote end definition providing additional groups as choices for the defined commands and events.

3.4. Commands

A command is an asynchronous operation, requested by the local end and run on the remote end, resulting in either a result or an error being returned to the local end. Multiple commands can run at the same time, and commands can potentially be long-running. As a consequence, commands can finish out-of-order.

Each command is defined by:

A command type which is defined by a remote end definition fragment containing a group. Each such group has two fields:
- method which is a string literal of the form [module name].[method name]. This is the command name.
- params which defines a mapping containing data that to be passed into the command. The populated value of this map is the command parameters.
A result type, which is defined by a local end definition fragment.
A set of remote end steps which define the actions to take for a command given a BiDi session and command parameters and return an instance of the command return type.

A command that can run without an active session is a static command. Commands are not static commands unless stated in their definition.

When commands are send from the local end they have a command id. This is an identifier used by the local end to identify the response from a particular command. From the point of view of the remote end this identifier is opaque and cannot be used internally to identify the command.

Note: This is because the command id is entirely controlled by the local end and isn’t necessarily unique over the course of a session. For example a local end which ignores all responses could use the same command id for each command.

The set of all command names is a set containing all the defined command names, including any belonging to extension modules.

3.5. Events

An event is a notification, sent by the remote end to the local end, signaling that something of interest has occurred on the remote end.

An event type is defined by a local end definition fragment containing a group. Each such group has two fields:
- method which is a string literal of the form [module name].[event name]. This is the event name.
- params which defines a mapping containing event data. The populated value of this map is the event parameters.
A remote end event trigger which defines when the event is triggered and steps to construct the event type data.
Optionally, a set of remote end subscribe steps, which define steps to take when a local end subscribes to an event. Where defined these steps have an associated subscribe priority which is an integer controlling the order in which the steps are run when multiple events are enabled at once, with lower integers indicating steps that run earlier.

A BiDi session has a global event set which is a set containing the event names for events that are enabled for all browsing contexts. This initially contains the event name for events that are in the default event set.

A BiDi session has a browsing context event map, which is a map with top-level browsing context keys and values that are a set of event names for events that are enabled in the given browsing context.

To obtain a list of event enabled browsing contexts given session and event name:

Let contexts be an empty set.
For each context → events of session’s browsing context event map:
1. If events contains event name, append context to contexts
Return contexts.

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

Let sessions be a new set.
For each session in active BiDI sessions:
1. If event is enabled with session, event name and browsing contexts, append session to sessions.
Return sessions

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

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

Let top-level browsing contexts be an empty set.
For each browsing context of browsing contexts, append browsing context’s top-level browsing context to top-level browsing contexts.
Let event map be the browsing context event map for session.
For each browsing context of top-level browsing contexts:
1. If event map contains browsing context, let browsing context events be event map[browsing context]. Otherwise let browsing context events be null.
2. If browsing context events is not null, and browsing context events contains event name, return true.
If the global event set for session contains event name return true.
Return false.

To obtain a set of event names given an name:

Let events be an empty set.
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
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.
Append the event name for each event in the module with name name to events.
Return success with data events.

4. Transport

Message transport is provided using the WebSocket protocol. [RFC6455]

Note: In the terms of the WebSocket protocol, the local end is the client and the remote end is the server / remote host.

Note: The encoding of commands and events as messages is similar to JSON-RPC, but this specification does not normatively reference it. [JSON-RPC] The normative requirements on remote ends are instead given as a precise processing model, while no normative requirements are given for local ends.

A WebSocket listener is a network endpoint that is able to accept incoming WebSocket connections.

A WebSocket listener has a host, a port, a secure flag, and a list of WebSocket resources.

When a WebSocket listener listener is created, a remote end must start to listen for WebSocket connections on the host and port given by listener’s host and port. If listener’s secure flag is set, then connections established from listener must be TLS encrypted.

A remote end has a set of WebSocket listeners active listeners, which is initially empty.

A remote end has a set of WebSocket connections not associated with a session, which is initially empty.

A WebSocket connection is a network connection that follows the requirements of the WebSocket protocol

A BiDi session has a set of session WebSocket connections whose elements are WebSocket connections. This is initially empty.

A BiDi session session is associated with connection connection if session’s session WebSocket connections contains connection.

Note: Each WebSocket connection is associated with at most one BiDi session.

When a client establishes a WebSocket connection connection by connecting to one of the set of active listeners listener, the implementation must proceed according to the WebSocket server-side requirements, with the following steps run when deciding whether to accept the incoming connection:

Let resource name be the resource name from reading the client’s opening handshake. If resource name is not in listener’s list of WebSocket resources, then stop running these steps and act as if the requested service is not available.
If resource name is the byte string "/session", and the implementation supports BiDi-only sessions:
1. Run any other implementation-defined steps to decide if the connection should be accepted, and if it is not stop running these steps and act as if the requested service is not available.
2. Add the connection to the set of WebSocket connections not associated with a session.
3. Return.
Get a session ID for a WebSocket resource with resource name and let session id be that value. If session id is null then stop running these steps and act as if the requested service is not available.
If there is a session in the list of active sessions with session id as its session ID then let session be that session. Otherwise stop running these steps and act as if the requested service is not available.
Run any other implementation-defined steps to decide if the connection should be accepted, and if it is not stop running these steps and act as if the requested service is not available.
Otherwise append connection to session’s session WebSocket connections, and proceed with the WebSocket server-side requirements when a server chooses to accept an incoming connection.

Do we support > 1 connection for a single session?

When a WebSocket message has been received for a WebSocket connection connection with type type and data data, a remote end must handle an incoming message given connection, type and data.

When the WebSocket closing handshake is started or when the WebSocket connection is closed for a WebSocket connection connection, a remote end must handle a connection closing given connection.

Note: Both conditions are needed because it is possible for a WebSocket connection to be closed without a closing handshake.

To construct a WebSocket resource name given a session session:

If session is null, return "/session"
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:

Let resource name be the result of constructing a WebSocket resource name given session.
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:

If resource name doesn’t begin with the byte string "/session/", return null.
Let session id be the bytes in resource name following the "/session/" prefix.
If session id is not the string representation of a UUID, return null.
Return session id.

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

If there is an existing WebSocket listener in the set of 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.
Let resource name be the result of constructing a WebSocket resource name given session.
Append resource name to the list of WebSocket resources for listener.
Append listener to the remote end's active listeners.
Return listener.

Note: An intermediary node handling multiple sessions can use one or many WebSocket listeners. WebDriver defines that an endpoint node supports at most one session at a time, so it’s expected to only have a single listener.

Note: For an endpoint node the host in the above steps will typically be "localhost".

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

If type is not text, respond with an error given connection, null, and invalid argument, and finally return.
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.
If there is a BiDi Session associated with connection connection, let session be that session. Otherwise if connection is in the set of WebSocket connections not associated with a session, let session be null. Otherwise, return.
Let parsed be the result of parsing JSON into Infra values given data. If this throws an exception, then respond with an error given connection, null, and invalid argument, and finally return.
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"]
  1. Let command be the command with command name method.
  2. If session is null and command is not a static command, then respond with an error given connection, command id, and invalid session id, and return.
  3. 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"]
  4. If result is an error, then respond with an error given connection, command id, and result’s error code, and finally return.
  5. Let value be result’s data.
  6. Assert: value matches the definition for the result type corresponding to the command with command name method.
  7. 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, let session’s WebSocket connection be connection, and remove connection from the set of WebSocket connections not associated with a session.
  8. 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.
  9. Let serialized be the result of serialize an infra value to JSON bytes given response.
  10. Send a WebSocket message comprised of serialized over connection.
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. Respond with an error given connection, command id, and error code.

To get related browsing contexts given an settings object settings:

Let related browsing contexts be an empty set
If settings’ relevant global object is a Window, append settings’ relevant global object's associated Document’s browsing context to related browsing contexts.

Otherwise if the global object specified by settings is a WorkerGlobalScope, for each owner in the global object's owner set, if owner is a Document, append owner’s browsing context to related browsing contexts.
Return related browsing contexts.

To emit an event given session, and body:

Assert: body has size 2 and contains "method" and "params".
Let connection be session’s WebSocket connection.
If connection is null, return.
Let serialized be the result of serialize an infra value to JSON bytes given body.
Send a WebSocket message comprised of serialized over connection.

To respond with an error given a WebSocket connection connection, command id, and error code:

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.
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.
Send a WebSocket message comprised of response over connection.

To handle a connection closing given a WebSocket connection connection:

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.
Otherwise, if the set of 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.

4.1. Establishing a Connection

WebDriver clients opt in to a bidirectional connection by requesting a capability with the name "webSocketUrl" and value true.

This specification defines an additional webdriver capability with the capability name "webSocketUrl".

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

If value is not a boolean, return error with code invalid argument.
Return success with data value.

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

If value is false, return success with data null.
Return success with data true.

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

If flags contains "bidi", return.
Let webSocketUrl be the result of getting a property named "webSocketUrl" from capabilities.
If webSocketUrl is undefined or false, return.
Assert: webSocketUrl is true.
Let listener be the result of start listening for a WebSocket connection given session.
Set webSocketUrl to the result of constructing a WebSocket URL given listener and session.
Set a property on capabilities named "webSocketUrl" to webSocketUrl.
Set session’s BiDi flag to true.
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:

Start listening for a WebSocket connection given null.

5. Sandboxed Script Execution

A common requirements for automation tools is to execute scripts which have access to the DOM of a document, but don’t have information about any changes to the DOM APIs made by scripts running in the browsing context containing the document.

A BiDi session has a context sandbox map which is a weak map in which the keys are browsing contexts and the values are weak maps between strings and SandboxWindowProxy objects.

Note: The definition of sandboxes here is an attempt to codify the behaviour of existing implementations. It exposes parts of the implementations that have previously been considered internal by specifications, in particular the distinction between the internal state of platform objects (which is typically implemented as native objects in the main implementation language of the browser engine) and the ECMAScript-visible state. Because existing sandbox implementations happen at a low level in the engine, implementations converging toward the specficication in all details might be a slow process. In the meantime, implementors are encouraged to provide detailed documentation on any differences with the specification, and users of this feature are encouraged to explicitly test that scripts running in sandboxes work in all implementations.

5.1. Sandbox Realms

Each sandbox is a unique EMCAScript Realm. However the sandbox realm provides access to platform objects in an existing Window realm via SandboxProxy objects.

To get or create a sandbox realm given name and browsing context:

If context sandbox map does not contain browsing context, set context sandbox map[source browsing context] to a new map.
Let sandboxes be context sandbox map[source browsing context].
If sandboxes does not contain name, set sandboxes[name] to create a sandbox realm with source browsing context.
Return sandboxes[name].

To create a sandbox realm with source browsing context:

Define creation of sandbox realm. This is going to return a SandboxWindowProxy wrapping the WindowProxy of source browsing context.

5.2. Sandbox Proxy Objects

A SandboxProxy object is an exotic object that mediates sandboxed access to objects from another realm. Sandbox proxy objects are designed to enforce the following restrictions:

Platform objects are accessible, but property access returns only Web IDL-defined properties and not ECMAScript-defined properties (either "expando" properties that are not present in the underlying interface, or ECMAScript-defined properties that shadow a property in the underlying interface).
Setting a property either runs Web IDL-defined setter steps, or sets a property on the proxy object. This means that properties written outside the sandbox are not accessible, but interface members can be used as normal.

There is no SandboxProxy interface object.

Define in detail how SandboxProxy works

5.3. SandboxWindowProxy

A SandboxWindowProxy is an exotic object that represents a Window object wrapped by a SandboxProxy object. This provides sandboxed access to that data in a Window global.

Define how this works.

6. Common Data Types

6.1. Reference

Each EMCAScript Realm has a corresponding handle object map. This is a strong map from handle ids to their corresponding objects.

OwnershipModel = "root" / "none";

RemoteReference represents a remote reference to an exising ECMAScript object in handle object map in the given Realm.

Handle = text;

RemoteReference = {
   handle: Handle,
   *text => any,
}

handle "stale object reference" case.

To deserialize remote reference given realm and remote reference:

Let handle id be the value of the handle field of remote reference.
Let handle map be realm’s handle object map
If handle map does not contain handle id, then return error with error code invalid argument.
Return handle map[handle id].

6.2. Protocol Value

6.2.1. Primitive Protocol Value

PrimitiveProtocolValue represents values which can only be represented by value, never by reference.

PrimitiveProtocolValue = {
  UndefinedValue //
  NullValue //
  StringValue //
  NumberValue //
  BooleanValue //
  BigIntValue //
}

UndefinedValue = {
  type: "undefined",
}

NullValue = {
  type: "null",
}

StringValue = {
  type: "string",
  value: text,
}

SpecialNumber = "NaN" / "-0" / "+Infinity" / "-Infinity";

NumberValue = {
  type: "number",
  value: number / SpecialNumber,
}

BooleanValue = {
  type: "boolean",
  value: bool,
}

BigIntValue = {
  type: "bigint",
  value: text,
}

6.2.1.1. Serialization

To serialize primitive protocol value given a value:

Let remote value be undefined.
In the following list of conditions and associated steps, run the first set of steps for which the associated condition is true, if any:
Type(value) is undefined
Let remote value be a map matching the UndefinedValue production in the local end definition.
Type(value) is Null
Let remote value be a map matching the NullValue production in the local end definition.
Type(value) is String
Let remote value be a map matching the StringValue production in the local end definition, with the value property set to value.
This doesn’t handle lone surrogates

Type(value) is Number
1. Switch on the value of value:
  
  NaN
  Let serialized be "NaN"
  -0
  Let serialized be "-0"
  +Infinity
  Let serialized be "+Infinity"
  -Infinity
  Let serialized be "-Infinity"
  Otherwise:
  Let serialized be value
2. Let remote value be a map matching the NumberValue production in the local end definition, with the value property set to serialized.
Type(value) is Boolean
Let remote value be a map matching the BooleanValue production in the local end definition, with the value property set to value.
Type(value) is BigInt
Let remote value be a map matching the BigIntValue production in the local end definition, with the value property set to the result of running the ToString operation on value.
Return remote value

6.2.1.2. Deserialization

To deserialize primitive protocol value given a primitive protocol value:

Let type be the value of the type field of primitive protocol value.
Let value be undefined.
If primitive protocol value has field value:
1. Let value be the value of the value field of primitive protocol value.
In the following list of conditions and associated steps, run the first set of steps for which the associated condition is true:
type is the string "undefined"
Return success with data undefined.
type is the string "null"
Return success with data null.
type is the string "string"
Return success with data value.
type is the string "number"
1. If Type(value) is Number, return success with data value.
2. Assert: Type(value) is String.
3. If value is the string "NaN", return success with data NaN.
4. Let number_result be StringToNumber(value).
5. If number_result is NaN, return error with error code invalid argument
6. Return success with data number_result.
type is the string "boolean"
Return success with data value.
type is the string "bigint"
1. Let bigint_result be StringToBigInt(value).
2. If bigint_result is undefined, return error with error code invalid argument
3. Return success with data bigint_result.
Return error with error code invalid argument

6.2.2. Local Value

LocalValue represents both primitive and non-primitive values which can be deserialized to ECMAScript without reference to existing objects.

LocalValue = {
  PrimitiveProtocolValue //
  ArrayLocalValue //
  DateLocalValue //
  MapLocalValue //
  ObjectLocalValue //
  RegExpLocalValue //
  SetLocalValue //
}

ListLocalValue = [*LocalValue];

ArrayLocalValue = {
  type: "array",
  value: ListLocalValue,
}

DateLocalValue = {
  type: "date",
  value: text
}

MappingLocalValue = [*[(LocalValue / text), LocalValue]];

MapLocalValue = {
  type: "map",
  value: MappingLocalValue,
}

ObjectLocalValue = {
  type: "object",
  value: MappingLocalValue,
}

RegExpValue = {
  pattern: text,
  ?flags: text,
}

RegExpLocalValue = {
  type: "regexp",
  value: RegExpValue,
}

SetLocalValue = {
  type: "set",
  value: ListLocalValue,
}

6.2.2.1. Deserialization

To deserialize key-value list given realm and serialized key-value list:

Let deserialized key-value list be a new list.
For each serialized key-value in the serialized key-value list:
1. If size of serialized key-value is not 2, return error with error code invalid argument.
2. Let serialized key be serialized key-value[0].
3. If serialized key is a string, let deserialized key be serialized key.
4. Otherwise let deserialized key be result of trying to deserialize local value given realm and serialized key.
5. Let serialized value be serialized key-value[1].
6. Let deserialized value be result of trying to deserialize local value given realm and serialized value.
7. Append CreateArrayFromList(«deserialized key, deserialized value») to deserialized key-value list.
Return success with data CreateArrayFromList(deserialized key-value list).

TODO distinguish between `List` and `Array`.

To deserialize value list given realm and serialized value list:

Let deserialized values be a new list.
For each serialized value in the serialized value list:
1. Let deserialized value be result of trying to deserialize local value with given realm and serialized value.
2. Append deserialized value to deserialized values;
Return success with data deserialized values.

To deserialize local value given realm and local protocol value:

If local protocol value matches the RemoteReference production, return deserialize remote reference of given realm and local protocol value.
If local protocol value matches the PrimitiveProtocolValue production, return deserialize primitive protocol value with local protocol value.
Let type be the value of the type field of local protocol value or undefined if no such a field.
Let value be the value of the value field of local protocol value or undefined if no such a field.
In the following list of conditions and associated steps, run the first set of steps for which the associated condition is true:
type is the string "array"
1. Let deserialized value list be a result of trying to deserialize value list given realm and value.
2. Return success with data CreateArrayFromList(deserialized value list).
type is the string "date"
1. If value does not match Date Time String Format, return error with error code invalid argument.
2. Return success with data Date.parse(value).
type is the string "map"
1. Let deserialized key-value list be a result of trying to deserialize key-value list given realm and value.
2. Let iterable be CreateArrayFromList(deserialized key-value list)
3. Return success with data Map(iterable).
type is the string "object"
1. Let deserialized key-value list be a result of trying to deserialize key-value list given realm and value.
2. Let iterable be CreateArrayFromList(deserialized key-value list)
3. Return success with data Object.fromEntries(iterable).
type is the string "regexp"
1. Let pattern be the value of the pattern field of local protocol value.
2. Let flags be the value of the flags field of local protocol value or undefined if no such a field.
3. Let regex_result be Regexp(pattern, flags). If this throws exception, return error with error code invalid argument.
4. Return success with data regex_result.
type is the string "set"
1. Let deserialized value list be a result of trying to deserialize value list given realm and value.
2. Let iterable be CreateArrayFromList(deserialized key-value list)
3. Return success with data Set object(iterable).
otherwise
Return error with error code invalid argument.

6.2.3. Remote Value

Values accessible from the ECMAScript runtime are represented by a mirror object, specified as RemoteValue. The value’s type is specified in the type property. In the case of JSON-representable primitive values, this contains the value in the value property; in the case of non-JSON-representable primitives, the value property contains a string representation of the value. For non-primitive objects, the handle property, when present, contains a unique string handle to the object. The handle is unique for each serialization. The remote end will keep objects with a corresponding handle alive until such a time that script.disown is called with that handle, or the realm itself is to be discarded (e.g. due to navigation). For some non-primitive types, the value property contains a representation of the data in the ECMAScript object; for container types this can contain further RemoteValue instances. The value property can be null or omitted if there is a duplicate object i.e. the object has already been serialized in the current RemoteValue, perhaps as part of a cycle, or otherwise when the maximum serialization depth is reached. In case of duplicated objects in the same RemoteValue, the value is provided only for one of the remote values, while the unique-per-ECMAScript-object internalId is provided for all the duplicated objects for a given serialization.

Nodes are also represented by RemoteValue instances. These have a partial serialization of the node in the value property.

reconsider mirror objects' lifecycle.

Note: mirror objects do not keep the original object alive in the runtime. If an object is discarded in the runtime, subsequent attempts to access it via the protocol will result in an error.

To get the handle for an object given realm, ownership type and object:

If ownership type is equal "none", return null.
Let handle id be a new, unique, string handle for object.
Let handle map be realm’s handle object map
Set handle map[handle id] to object.
Return handle id as a result.

To set internal ids if needed given serialization internal map, remote value and object:

If the serialization internal map does not contain object, set serialization internal map[object] to remote value.
Otherwise, run the following steps:
1. Let previously serialized remote value be serialization internal map[object].
2. If previously serialized remote value does not have a field internalId, run the following steps:
  1. Let internal id be a unique across the internalId fields of the values of serialization internal map integer.
  2. Set the internalId field of previously serialized remote value to internal id.
3. Set the internalId field of remote value to a field internalId in previously serialized remote value.

remote end definition and local end definition

RemoteValue = {
  PrimitiveProtocolValue //
  SymbolRemoteValue //
  ArrayRemoteValue //
  ObjectRemoteValue //
  FunctionRemoteValue //
  RegExpRemoteValue //
  DateRemoteValue //
  MapRemoteValue //
  SetRemoteValue //
  WeakMapRemoteValue //
  WeakSetRemoteValue //
  IteratorRemoteValue //
  GeneratorRemoteValue //
  ErrorRemoteValue //
  ProxyRemoteValue //
  PromiseRemoteValue //
  TypedArrayRemoteValue //
  ArrayBufferRemoteValue //
  NodeRemoteValue //
  WindowProxyRemoteValue //
}

InternalId = uint;

ListRemoteValue = [*RemoteValue];

MappingRemoteValue = [*[(RemoteValue / text), RemoteValue]];

SymbolRemoteValue = {
  type: "symbol",
  ?handle: Handle,
  ?internalId: InternalId,
}

ArrayRemoteValue = {
  type: "array",
  ?handle: Handle,
  ?internalId: InternalId,
  ?value: ListRemoteValue,
}

ObjectRemoteValue = {
  type: "object",
  ?handle: Handle,
  ?internalId: InternalId,
  ?value: MappingRemoteValue,
}

FunctionRemoteValue = {
  type: "function",
  ?handle: Handle,
  ?internalId: InternalId,
}

RegExpRemoteValue = {
  RegExpLocalValue,
  ?handle: Handle,
  ?internalId: InternalId,
}

DateRemoteValue = {
  DateLocalValue,
  ?handle: Handle,
  ?internalId: InternalId,
}

MapRemoteValue = {
  type: "map",
  ?handle: Handle,
  ?internalId: InternalId,
  value: MappingRemoteValue,
}

SetRemoteValue = {
  type: "set",
  ?handle: Handle,
  ?internalId: InternalId,
  value: ListRemoteValue
}

WeakMapRemoteValue = {
  type: "weakmap",
  ?handle: Handle,
  ?internalId: InternalId,
}

WeakSetRemoteValue = {
  type: "weakset",
  ?handle: Handle,
  ?internalId: InternalId,
}

IteratorRemoteValue = {
  type: "iterator",
  ?handle: Handle,
  ?internalId: InternalId,
}

GeneratorRemoteValue = {
  type: "generator",
  ?handle: Handle,
  ?internalId: InternalId,
}

ErrorRemoteValue = {
  type: "error",
  ?handle: Handle,
  ?internalId: InternalId,
}

ProxyRemoteValue = {
  type: "proxy",
  ?handle: Handle,
  ?internalId: InternalId,
}

PromiseRemoteValue = {
  type: "promise",
  ?handle: Handle,
  ?internalId: InternalId,
}

TypedArrayRemoteValue = {
  type: "typedarray",
  ?handle: Handle,
  ?internalId: InternalId,
}

ArrayBufferRemoteValue = {
  type: "arraybuffer",
  ?handle: Handle,
  ?internalId: InternalId,
}

NodeRemoteValue = {
  type: "node",
  ?handle: Handle,
  ?internalId: InternalId,
  ?value: NodeProperties,
}

NodeProperties = {
  nodeType: uint,
  nodeValue: text,
  ?localName: text,
  ?namespaceURI: text,
  childNodeCount: uint,
  ?children: [*NodeRemoteValue],
  ?attributes: {*text => text},
  ?shadowRoot: NodeRemoteValue / null,
}

WindowProxyRemoteValue = {
  type: "window",
  ?handle: Handle,
  ?internalId: InternalId,
}

Add WASM types?

Should WindowProxy get attributes in a similar style to Node?

Describe `IteratorRemoteValue` serialization.

Describe `GeneratorRemoteValue` serialization.

Describe `ProxyRemoteValue` serialization.

handle String / Number / etc. wrapper objects specially?

6.2.3.1. Serialization

To serialize as a remote value given a value, a max depth, an ownership type, a serialization internal map and a realm:

Let remote value be a result of serialize primitive protocol value given a value.
If remote value is not undefined, return remote value.
In the following list of conditions and associated steps, run the first set of steps for which the associated condition is true:
Let handle id be the handle for an object given realm, ownership type and value.
Let known object be true, if value is in the serialization internal map, otherwise false.
Let child ownership be "none".
Type(value) is Symbol
Let remote value be a map matching the SymbolRemoteValue production in the local end definition, with the handle property set to handle id if it’s not null, or omitted otherwise.
IsArray(value)
1. Let remote value be a map matching the ArrayRemoteValue production in the local end definition, with the handle property set to handle id if it’s not null, or omitted otherwise.
2. Set internal ids if needed given serialization internal map, remote value and value.
3. Let serialized be null.
4. If known object is false, and max depth is not null and greater than 0, run the following steps:
  1. Let serialized be the result of serialize as a list given CreateArrayIterator(value, value), max depth, serialization internal map and realm.
5. If serialized is not null, set field value of remote value to serialized.
IsRegExp(value)
1. Let pattern be ToString(Get(value, "source")).
2. Let flags be ToString(Get(value, "flags")).
3. Let value be a map matching the RegExpValue production in the local end definition, with the pattern property set to the pattern and the the flags property set to the flags.
4. Let remote value be a map matching the RegExpRemoteValue production in the local end definition, with the handle property set to handle id if it’s not null, or omitted otherwise, and the value property set to value.
value has a [[DateValue]] internal slot.
1. Let serialized be Date.ToDateString(thisTimeValue(value)).
2. Let remote value be a map matching the DateRemoteValue production in the local end definition, with the handle property set to handle id if it’s not null, or omitted otherwise, and the value set to serialized.
value has a [[MapData]] internal slot
1. Let remote value be a map matching the MapRemoteValue production in the local end definition, with the handle property set to handle id if it’s not null, or omitted otherwise.
2. Set internal ids if needed given serialization internal map, remote value and value.
  1. Let serialized be null.
  2. If known object is false, and max depth is not null and greater than 0, run the following steps:
    
    Let serialized be the result of serialize as a mapping given CreateMapIterator(value, key+value), max depth, child ownership, serialization internal map and realm.
3. If serialized is not null, set field value of remote value to serialized.
value has a [[SetData]] internal slot
1. Let remote value be a map matching the SetRemoteValue production in the local end definition, with the handle property set to handle id if it’s not null, or omitted otherwise.
2. Set internal ids if needed given serialization internal map, remote value and value.
  1. Let serialized be null.
  2. If known object is false, and max depth is not null and greater than 0, run the following steps:
    
    Let serialized be the result of serialize as a list given CreateSetIterator(value, value), max depth, child ownership, serialization internal map and realm.
3. If serialized is not null, set field value of remote value to serialized.
value has a [[WeakMapData]] internal slot
Let remote value be a map matching the WeakMapRemoteValue production in the local end definition, with the handle property set to handle id if it’s not null, or omitted otherwise.
value has a [[WeakSetData]] internal slot
Let remote value be a map matching the WeakSetRemoteValue production in the local end definition, with the handle property set to handle id if it’s not null, or omitted otherwise.
value has an [[ErrorData]] internal slot
Let remote value be a map matching the ErrorRemoteValue production in the local end definition, with the handle property set to handle id if it’s not null, or omitted otherwise.
IsPromise(value)
Let remote value be a map matching the PromiseRemoteValue production in the local end definition, with the handle property set to handle id if it’s not null, or omitted otherwise.
value has a [[TypedArrayName]] internal slot
Let remote value be a map matching the TypedArrayRemoteValue production in the local end definition, with the handle property set to handle id if it’s not null, or omitted otherwise.
value has an [[ArrayBufferData]] internal slot
Let remote value be a map matching the ArrayBufferRemoteValue production in the local end definition, with the handle property set to handle id if it’s not null, or omitted otherwise.
value is a platform object that implements Node
1. Let remote value be a map matching the NodeRemoteValue production in the local end definition, with the handle property set to handle id if it’s not null, or omitted otherwise.
2. Set internal ids if needed given serialization internal map, remote value and value.
3. Let serialized be null.
4. If known object is false, run the following steps:
  1. Let serialized be a map.
  2. Set serialized["nodeType"] to Get(value, "nodeType").
  3. Set serialized["nodeValue"] to Get(value, "nodeValue")
  4. If value is an Element or an Attribute:
    
    Set serialized["localName"] to Get(value, "localName").
    
    Set serialized["namespaceURI"] to Get(value, "namespaceURI")
  5. Let child node count be the size of serialized’s children.
  6. Set serialized["childNodeCount"] to child node count.
  7. If max depth is equal to 0 let children be null. Otherwise, let children be an empty list and, for each node child in the children of value:
    
    Let child depth be max depth - 1 if max depth is not null, or null otherwise.
    
    Let serialized be the result of serialize as a remote value with child, child depth, child ownership, serialization internal map and realm.
    
    Append serialized to children.
  8. Set serialized["children"] to children.
  9. If value is an Element:
    
    Let attributes be a new map.
    
    For each attribute in value’s attribute list:
    
    Let name be attribute’s qualified name
    
    Let value be attribute’s value.
    
    Set attributes[name] to value
    
    Set serialized["attributes"] to attributes.
    
    Let shadow root be value’s shadow root.
    
    If shadow root is null, let serialized shadow be null. Otherwise run the following substeps:
    
    Let child depth be max depth - 1 if max depth is not null, or null otherwise.
    
    Let serialized shadow be the result of serialize as a remote value with shadow root, child depth, false, child ownership, serialization internal map and realm.
    
    Note: this means the handle for the shadow root will be serialized irrespective of whether the shadow is open or closed, but no properties of the node will be returned.
    
    Set serialized["shadowRoot"] to serialized shadow.
5. If serialized is not null, set field value of remote value to serialized.
value is a platform object that implements WindowProxy
1. Let remote value be a map matching the WindowProxyValue production in the local end definition, with the handle property set to handle id if it’s not null, or omitted otherwise.
value is a platform object
1. Let remote value be a map matching the ObjectValue production in the local end definition, with the handle property set to handle id if it’s not null, or omitted otherwise.
IsCallable(value)
Let remote value be a map matching the FunctionValue production in the local end definition, with the handle property set to handle id if it’s not null, or omitted otherwise.
Otherwise:
1. Assert: type(value) is Object
2. Let remote value be a map matching the ObjectValue production in the local end definition, with the handle property set to handle id if it’s not null, or omitted otherwise.
3. Set internal ids if needed given serialization internal map, remote value and value.
4. Let serialized be null.
5. If known object is false, and max depth is greater than 0, run the following steps:
  1. Let serialized be the result of serialize as a mapping given EnumerableOwnPropertyNames(value, key+value), max depth, child ownership, serialization internal map and realm.
6. If serialized is not null, set field value of remote value to serialized.
Return remote value

Does it make sense to use the same depth parameter for nodes and objects in general?

children and child nodes are different things. Either childNodeCount should reference to childNodes, or it should be renamed to childrenCount.

nodeValue can be null. Omit the field in such a case, or adjust type to allow null value.

shadowRoot field is optional. Omit it in case of shadow root is null, or remove optional flag from the field.

To serialize as a list given iterable, max depth, child ownership, serialization internal map and realm:

Let serialized be a new list.
For each child value in iterable:
1. Let child depth be max depth - 1 if max depth is not null, or null otherwise.
2. Let serialized child be the result of serialize as a remote value with arguments child value, child depth, child ownership, serialization internal map and realm.
3. Append serialized child to serialized.
Return serialized

this assumes for-in works on iterators

To serialize as a mapping given iterable, max depth, child ownership, serialization internal map and realm:

Let serialized be a new list.
For item in iterable:
1. Assert: IsArray(item)
2. Let property be CreateListFromArrayLike(item)
3. Assert: property is a list of size 2
4. Let key be property[0] and let value be property[1]
5. Let child depth be max depth - 1 if max depth is not null, or null otherwise.
6. If Type(key) is String, let serialized key be child key, otherwise let serialized key be the result of serialize as a remote value with arguments child key, child depth, serialization internal map and realm.
7. Let serialized value be the result of serialize as a remote value with arguments value, child depth, child ownership, serialization internal map and realm.
8. Let serialized child be («serialized key, serialized value»).
9. Append serialized child to serialized.
Return serialized

7. Modules

7.1. The session Module

The session module contains commands and events for monitoring the status of the remote end.

7.1.1. Definition

remote end definition

SessionCommand = (SessionStatusCommand //
                  SessionSubscribeCommand)

local end definition

SessionResult = (StatusResult)

To update the event map, given session, requested event names, browsing contexts, and enabled:

Note: The return value of this algorithm is a map between event names and contexts. When the events are being enabled, the contexts in the return value are those for which the event are now enabled but were not previously. When events are disabled, the return value is always empty.

Let global event set be a clone of the global event set for session.
Let event map be a new map.
For each key → value of the browsing context event map for session:
1. Set event map[key] to a clone of value.
Let event names be an empty set.
For each entry name in requested event names, let event names be the union of event names and the result of trying to obtain a set of event names with name.
Let enabled events be a new map.
If browsing contexts is null:
1. If enabled is true:
  1. For each event name of event names:
    1. If global event set doesn’t contain event name:
      1. Let already enabled contexts be the event enabled browsing contexts given session and event name
      2. Add event name to global event set.
      3. For each context of already enabled contexts, remove event name from event map[context].
      4. Let newly enabled contexts be a list of all top-level browsing contexts that are not contained in already enabled contexts,
      5. Set enabled events[event name] to newly enabled contexts.
2. If enabled is false:
  1. For each event name in event names:
    1. If global event set contains event name, remove event name from global event set. Otherwise return error with error code invalid argument.
Otherwise, if browsing contexts is not null:
1. Let targets be an empty map.
2. For each context id in browsing contexts:
  1. Let context be the result of trying to get a browsing context with context id.
  2. Let top-level context be the top-level browsing context for context.
  3. If event map does not contain top-level context, set event map[top-level context] to a new set.
  4. Set targets[top-level context] to event map[top-level context].
3. For each event name in event names:
  1. If enabled is true and global event set contains event name, continue.
  2. For each context → target in targets:
    1. If enabled is true and target does not contain event name:
      1. Add event name to target.
      2. If enabled events does not contain event name, set enabled events[event name] to a new set.
      3. Append context to enabled events[event name].
    2. If enabled is false:
      1. If target contains event name, remove event name from target. Otherwise return error with error code invalid argument.
Set the global event set for session to global event set.
Set the browsing context event map for session to event map.
Return success with data enabled events.

Note: Implementations that do additional work when an event is enabled, e.g. subscribing to the relevant engine-internal events, will likely perform those additional steps when updating the event map. This specification uses a model where hooks are always called and then the event map is used to filter only those that ought to be returned to the local end.

7.1.2. Types

7.1.2.1. The session.CapabilitiesRequest Type

remote end definition and local end definition

Capabilities = {
    ?acceptInsecureCertificates: bool,
    ?browserName: text,
    ?browserVersion: text,
    ?platformName: text,
    ?proxy: {
        ?proxyType: "pac" / "direct" / "autodetect" / "system" / "manual",
        ?proxyAutoconfigUrl: text,
        ?ftpProxy: text,
        ?httpProxy: text,
        ?noProxy: [*text],
        ?sslProxy: text,
        ?socksProxy: text,
        ?socksVersion: int,
    },
    *text => any
};

The CapabilitiesRequest type represents the capabilities requested for a session.

7.1.3. Commands

7.1.3.1. The session.status Command

The session.status command returns information about whether a remote end is in a state in which it can create new sessions, but may additionally include arbitrary meta information that is specific to the implementation.

This is a static command.

Command Type

SessionStatusCommand = {
  method: "session.status",
  params: EmptyParams,
}

Return Type

SessionStatusResult = {
  ready: bool,
  message: text,
}

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

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.
Return success with data body

7.1.3.2. The session.new Command

The session.new command allows creating a new BiDi session.

Note: A session created this way will not be accessible via HTTP.

This is a static command.

Command Type

SessionNewCommand = {
  method: "session.new",
  params: {capabilities: CapabilitiesRequestParameters},
}

CapabilitiesRequestParameters = {
  ?alwaysMatch: CapabilitiesRequest,
  ?firstMatch: [*CapabilitiesRequest]
}

Return Type

SessionNewResult = {
  sessionId: text,
  capabilities: {
    acceptInsecureCertificates: bool,
    browserName: text,
    browserVersion: text,
    platformName: text,
    proxy: {
      ?proxyType: "pac" / "direct" / "autodetect" / "system" / "manual",
      ?proxyAutoconfigUrl: text,
      ?ftpProxy: text,
      ?httpProxy: text,
      ?noProxy: [*text],
      ?sslProxy: text,
      ?socksProxy: text,
      ?socksVersion: int,
    },
    setWindowRect: bool,
    *text => any
  }
}

The remote end steps given session and command parameters are:

If session is not null, return an error with error code session not created.
If the implementation is unable to start a new session for any reason, return an error with error code session not created.
Let flags be a set containing "bidi".
Let capabilities be the result of trying to process capabilities with command parameters and flags.
Let session be the result of trying to create a session with capabilities and flags.
Set session’s BiDi flag to true.

Note: the connection for this session will be set to the current connection by the caller.
Let body be a new map matching the SessionNewResult production, with the sessionId field set to session’s session ID, and the capabilities field set to capabilities.
Return success with data body.

The session.subscribe command enables certain events either globally or for a set of browsing contexts

This needs to be generalized to work with realms too

Command Type

SessionSubscribeCommand = {
  method: "session.subscribe",
  params: SessionSubscribeParameters
}

SessionSubscribeParameters = {
  events: [*text],
  ?contexts: [*BrowsingContext],
}

Return Type

EmptyResult

The remote end steps with session and command parameters are:

Let the list of event names be the value of the events field of command parameters
Let the list of contexts be the value of the contexts field of command parameters if it is present or null if it isn’t.
Let enabled events be the result of trying to update the event map with session, list of event names , list of contexts and enabled true.
Let subscribe step events be a new map.
For each event name → contexts in enabled events:
1. If the event with event name event name defines remote end subscribe steps, set subscribe step events[event name] to contexts.
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 susbscribe priority, or false otherwise.
If list of contexts is null, let include global be true, otherwise let include global be false.
For each event name → contexts in subscribe step events:
1. Run the remote end subscribe steps for the event with event name event name given session, contexts and include global.
Return success with data null.

7.1.3.4. The session.unsubscribe Command

The session.unsubscribe command disables events either globally or for a set of browsing contexts

This needs to be generalised to work with realms too

Command Type

SessionUnsubscribeCommand = {
  method: "session.unsubscribe",
  params: SessionSubscribeParameters
}

Return Type

EmptyResult

The remote end steps with session and command parameters are:

Let the list of event names be the value of the events field of command parameters.
Let the list of contexts be the value of the contexts field of command parameters if it is present or null if it isn’t.
Try to update the event map with session, list of event names, list of contexts and enabled false.
Return success with data null.

7.2. The browsingContext Module

The browsingContext module contains commands and events relating to browsing contexts.

The progress of navigation is communicated using an immutable WebDriver navigation status struct, which has the following items:

id: The navigation id for the navigation, or null when the navigation is canceled before making progress.
status: A status code that is either "canceled", "pending", or "complete".
url: The URL which is being loaded in the navigation

7.2.1. Definition

remote end definition

BrowsingContextCommand = (
    BrowsingContextCloseCommand //
    BrowsingContextCreateCommand //
    BrowsingContextGetTreeCommand //
    BrowsingContextNavigateCommand //
    BrowsingContextReloadCommand
)

local end definition

BrowsingContextResult = (
    BrowsingContextCreateResult //
    BrowsingContextGetTreeResult //
    BrowsingContextNavigateResult
)

BrowsingContextEvent = (
    BrowsingContextCreatedEvent //
    BrowsingContextDestroyedEvent //
    BrowsingContextNavigationStartedEvent //
    BrowsingContextFragmentNavigatedEvent //
    BrowsingContextDomContentLoadedEvent //
    BrowsingContextLoadEvent //
    BrowsingContextDownloadWillBegin //
    BrowsingContextNavigationAbortedEvent //
    BrowsingContextNavigationFailedEvent
)

7.2.2. Types

7.2.2.1. The browsingContext.BrowsingContext Type

remote end definition and local end definition

BrowsingContext = text;

Each browsing context has an associated browsing context id, which is a string uniquely identifying that browsing context. This is implicitly set when the context is created. For browsing contexts with an associated WebDriver window handle the browsing context id must be the same as the window handle.

To get a browsing context given context id:

If context id is null, return success with data null.
If there is no browsing context with browsing context id context id return error with error code no such frame
Let context be the browsing context with id context id.
Return success with data context

7.2.2.2. The browsingContext.BrowsingContextInfo Type

local end definition

BrowsingContextInfoList = [* BrowsingContextInfo]

BrowsingContextInfo = {
  context: BrowsingContext,
  ?parent: BrowsingContext / null,
  url: text,
  children: BrowsingContextInfoList / null
}

The BrowsingContextInfo type represents the properties of a browsing context.

To get the browsing context info given context, max depth and is root:

Let context id be the browsing context id for context.
If context has a parent browsing context let parent id be the browsing context id of that parent. Otherwise let parent id be null.
Let document be context’s active document.
Let url be the result of running the URL serializer, given document’s URL.

Note: This includes the fragment component of the URL.
Let child infos be null.
If max depth is null, or max depth is greater than 0:
1. Let child contexts be a list containing all browsing contexts which are child browsing contexts of context.
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 context of child contexts:
  1. Let info be the result of get the browsing context info given context, child depth, and false.
  2. Append info to child infos
Let context info be a map matching the BrowsingContextInfo production with the context field set to context id, the parent field set to parent id if is root is true, or unset otherwise, the url field set to url, and the children field set to child infos.
Return context info.

To given context, request, wait condition, and optionally history handling (default: "default") and ignore cache (default: false):

Let navigation id be the string representation of a UUID based on truly random, or pseudo-random numbers.
Navigate context with resource request, and using context as the source browsing context, 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.
Let (event received, navigate status) be await given «"navigation started", "navigation failed", "fragment navigated"», and navigation id.
Assert: navigate status’s id is navigation id.
If navigate status’s status is "complete":
1. Let body be a map matching the BrowsingContextNavigateResult production, with the navigation field set to navigation id, and the url field set to the result of the URL serializer given navigate status’s url.
2. Return success with data body.
Note: this is the case if the navigation only caused the fragment to change.
If navigate status’s status is "canceled" return error with error code unknown error.

TODO: is this the right way to handle errors here?
Assert: navigate status’s status is "pending" and navigation id is not null.
If wait condition is "none":
1. Let body be a map matching the BrowsingContextNavigateResult production, with the navigation field set to navigation id, and the url field set to the result of the URL serializer given navigate status’s url.
2. Return success with data body.
If wait condition is "interactive", let event name be "domContentLoaded", otherwise let event name be "load".
Let (event received, status) be await given «event name, "download started", "navigation aborted", "navigation failed"» and navigation id.
If event received is "navigation failed" return error with error code unknown error.

Are we surfacing enough information about what failed and why with an error here? What error code do we want? Is there going to be a problem where local ends parse the implementation-defined strings to figure out what actually went wrong?
Let body be a map matching the BrowsingContextNavigateResult production, with the navigation field set to status’s id, and the url field set to the result of the URL serializer given status’s url.
Return success with data body.

remote end definition and local end definition

Navigation = text;

The Navigation type is a unique string identifying an ongoing navigation.

TODO: Link to the definition in the HTML spec.

7.2.2.4. The browsingContext.NavigationInfo Type

local end definition:

NavigationInfo = {
  context: BrowsingContext,
  navigation: Navigation / null,
  url: text,
}

The NavigationInfo type provides details of an ongoing navigation.

To , given context and navigation status:

Let context id be the browsing context id for context.
Let navigation id be navigation status’s id.
Let url be navigation status’s url.
Return a map matching the NavigationInfo production, with the context field set to context id, the navigation field set to navigation id, and the url field set to the result of the URL serializer given url.

7.2.3. Commands

7.2.3.1. The browsingContext.close Command

The browsingContext.close command closes a top-level browsing context.

Command Type

BrowsingContextCloseCommand = {
  method: "browsingContext.close",
  params: BrowsingContextCloseParameters
}

BrowsingContextCloseParameters = {
  context: BrowsingContext
}

The remote end steps with command parameters are:

Let context id be the value of the context field of command parameters.
Let context be the result of trying to get a browsing context with context id.
Assert: context is not null.
If context is not a top-level browsing context, return error with error code invalid argument.
Close context.

There is an open discussion about the behavior when closing the last top-level browsing context. We could expect to close the browser, close the session or leave this up to the implementation. [Issue #w3c/webdriver-bidi#170]

7.2.3.2. The browsingContext.create Command

The browsingContext.create command creates a new browsing context, either in a new tab or in a new window, and returns its browsing context id.

Command Type

BrowsingContextCreateCommand = {
  method: "browsingContext.create",
  params: BrowsingContextCreateParameters
}

BrowsingContextCreateType = "tab" / "window"

BrowsingContextCreateParameters = {
  type: BrowsingContextCreateType
}

Return Type

BrowsingContextCreateResult = {
  context: BrowsingContext
}

The remote end steps with command parameters are:

Let type be the value of the type field of command parameters.
Create a new top-level browsing context by running the window open steps with url set to "about:blank", target set to the empty string, and features set to "noopener". This must be done without invoking the focusing steps for the created browsing context. If type is "tab", and the implementation supports multiple browsing contexts in the same OS window, the new browsing context should share an OS window with any other top-level browsing context. If type is "window", and the implementation supports multiple browsing contexts in separate OS windows, the created browsing context should be in a new OS window. In all other cases the details of how the browsing context is presented to the user are implementation defined.

HTML’s window open steps depend on the "entry global object" and WebDriver’s New Window command depends on the "current browsing context". Given that we don’t have any such implicit context here, what OS window should new tabs be opened in?
Let context id be the browsing context id of the newly created browsing context.
Let body be a map matching the BrowsingContextCreateResult production, with the context field set to context id.
Return success with data body.

7.2.3.3. The browsingContext.getTree Command

The browsingContext.getTree command returns a tree of all descendent browsing contexts including the given parent iself, or all top-level contexts when no parent is provided.

Command Type

BrowsingContextGetTreeCommand = {
  method: "browsingContext.getTree",
  params: BrowsingContextGetTreeParameters
}

BrowsingContextGetTreeParameters = {
  ?maxDepth: uint,
  ?root: BrowsingContext,
}

Return Type

BrowsingContextGetTreeResult = {
  contexts: BrowsingContextInfoList
}

The remote end steps with session and command parameters are:

Let root id be the value of the root field of command parameters if present, or null otherwise.
Let max depth be the value of the maxDepth field of command parameters if present, or null otherwise.
Let contexts be an empty list.
If root id is not null, append the result of trying to get a browsing context given root id to contexts. Otherwise append all top-level browsing contexts to contexts.
Let contexts info be an empty list.
For each context of contexts:
1. Let info be the result of get the browsing context info given context, max depth, and true.
2. Append info to contexts info
Let body be a map matching the BrowsingContextGetTreeResult production, with the contexts field set to contexts info.
Return success with data body.

7.2.3.4. The browsingContext.navigate Command

The browsingContext.navigate command navigates a browsing context to the given URL.

Command Type

BrowsingContextNavigateCommand = {
  method: "browsingContext.navigate",
  params: BrowsingContextNavigateParameters
}

BrowsingContextNavigateParameters = {
  context: BrowsingContext,
  url: text,
  ?wait: ReadinessState,
}

 ReadinessState = "none" / "interactive" / "complete"

Return Type

BrowsingContextNavigateResult = {
    navigation: Navigation / null,
    url: text,
}

The remote end steps with session and command parameters are:

Let context id be the value of the context field of command parameters.
Let context be the result of trying to get a browsing context with context id.
Assert: context is not null.
Let wait condition be the value of the wait field of command parameters if present, or "none" otherwise.
Let url be the value of the url field of command parameters.
Let document be context’s active document.
Let base be document’s base URL.
Let url record be the result of applying the URL parser to url, with base URL base.
If url record is failure, return error with error code invalid argument.
Let request be a new request whose URL is url record.
Return the result of await a navigation with context, request and wait condition.

7.2.3.5. The browsingContext.reload Command

The browsingContext.reload command reloads a browsing context.

Command Type

BrowsingContextReloadCommand = {
  method: "browsingContext.reload",
  params: BrowsingContextReloadParameters
}

BrowsingContextReloadParameters = {
  context: BrowsingContext,
  ?ignoreCache: boolean,
  ?wait: ReadinessState,
}

The remote end steps with command parameters are:

Let context id be the value of the context field of command parameters.
Let context be the result of trying to get a browsing context with context id.
Assert: context is not null.
Let ignore cache be the the value of the ignoreCache field of command parameters if present, or false otherwise.
Let wait condition be the value of the wait field of command parameters if present, or "none" otherwise.
Let document be context’s active document.
Let url be document’s URL.
Let request be a new request whose URL is url.
Return the result of await a navigation with context, request, wait condition, history handling "reload", and ignore cache ignore cache.

7.2.4. Events

7.2.4.1. The browsingContext.contextCreated Event

Event Type

 BrowsingContextCreatedEvent = {
  method: "browsingContext.contextCreated",
  params: BrowsingContextInfo
}

To Recursively emit context created events given session and context:

Emit a context created event with session and context.
For each child browsing context, child, of context:
1. Recursively emit context created events given session and child.

To Emit a context created event given session and context:

Let params be the result of get the browsing context info given context, 0, and true.
Let body be a map matching the BrowsingContextCreatedEvent production, with the params field set to params.
Emit an event with session and body.

The remote end event trigger is:

When the create a new browsing context algorithm is invoked, after the active document of the browsing context is set, run the following steps:

Let context be the newly created browsing context.
Let related browsing contexts be a set containing context.
For each session in the set of sessions for which an event is enabled given "browsingContext.contextCreated" and related browsing contexts:
1. Emit a context created event given session and context.

The remote end subscribe steps, with subscribe priority 1, given session, contexts and include global are:

For each context in contexts:
1. Recursively emit context created events given session and context.

7.2.4.2. The browsingContext.contextDestroyed Event

Event Type

 BrowsingContextDestroyedEvent = {
  method: "browsingContext.contextDestroyed",
  params: BrowsingContextInfo
}

The remote end event trigger is:

Define the following browsing context tree discarded steps:

Let context be the browsing context being discarded.
Let params be the result of get the browsing context info, given context, 0, and true.
Let body be a map matching the BrowsingContextDestroyedEvent production, with the params field set to params.
Let related browsing contexts be a set containing the parent browsing context of context, if that is not null, or an empty set otherwise.
For each session in the set of sessions for which an event is enabled given "browsingContext.contextDestroyed" and related browsing contexts:
1. Emit an event with session and body.

the way this hooks into HTML feels very fragile. See https://github.com/whatwg/html/issues/6194

It’s unclear if we ought to only fire this event for browsing contexts that have active documents; navigation can also cause contexts to become inaccessible but not yet get discarded because bfcache.

7.2.4.3. The browsingContext.navigationStarted Event

Event Type

 BrowsingContextNavigationStartedEvent = {
  method: "browsingContext.navigationStarted",
  params: NavigationInfo
}

The remote end event trigger is the steps given context and navigation status:

Let params be the result of get the navigation info given context and navigation status.
Let body be a map matching the BrowsingContextNavigationStarted production, with the params field set to params.
Let navigation id be navigation status’s id.
Let related browsing contexts be a set containing context.
Resume with "navigation started", navigation id, and navigation status.
For each session in the set of sessions for which an event is enabled given "browsingContext.navigationStarted" and related browsing contexts:
1. Emit an event with session and body.

7.2.4.4. The browsingContext.fragmentNavigated Event

Event Type

 BrowsingContextFragmentNavigatedEvent = {
  method: "browsingContext.fragmentNavigated",
  params: NavigationInfo
}

The remote end event trigger is the WebDriver BiDi fragment navigated steps given context and navigation status:

Let params be the result of get the navigation info given context and navigation status.
Let body be a map matching the BrowsingContextFragmentNavigatedEvent production, with the params field set to params.
Let navigation id be navigation status’s id.
Let related browsing contexts be a set containing context.
Resume with "fragment navigated", navigation id, and navigation status.
For each session in the set of sessions for which an event is enabled given "browsingContext.fragmentNavigated" and related browsing contexts:
1. Emit an event with session and body.

7.2.4.5. The browsingContext.domContentLoaded Event

Event Type

 BrowsingContextDomContentLoadedEvent = {
  method: "browsingContext.domContentLoaded",
  params: NavigationInfo
}

The remote end event trigger is the WebDriver BiDi DOM content loaded steps given context and navigation status:

Let params be the result of get the navigation info given context and navigation status.
Let body be a map matching the BrowsingContextDomContentLoadedEvent production, with the params field set to params.
Let related browsing contexts be a set containing context.
Let navigation id be navigation status’s id.
Resume with "domContentLoaded", navigation id, and navigation status.
For each session in the set of sessions for which an event is enabled given "browsingContext.domContentLoaded" and related browsing contexts:
1. Emit an event with session and body.

7.2.4.6. The browsingContext.load Event

Event Type

 BrowsingContextLoadEvent = {
  method: "browsingContext.load",
  params: NavigationInfo
}

The remote end event trigger is the WebDriver BiDi load complete steps given context and navigation status:

Let params be the result of get the navigation info given context and navigation status.
Let body be a map matching the BrowsingContextLoadEvent production, with the params field set to params.
Let related browsing contexts be a set containing context.
Let navigation id be navigation status’s id.
Resume with "load", navigation id and navigation status.
For each session in the set of sessions for which an event is enabled given "browsingContext.load" and related browsing contexts:
1. Emit an event with session and body.

7.2.4.7. The browsingContext.downloadWillBegin Event

Event Type

 BrowsingContextDownloadWillBegin = {
  method: "browsingContext.downloadWillBegin",
  params: NavigationInfo
}

The remote end event trigger is the WebDriver BiDi download started steps given context and navigation status:

Let params be the result of get the navigation info given context and navigation status.
Let body be a map matching the BrowsingContextDownloadWillBegin production, with the params field set to params.
Let navigation id be navigation status’s id.
Let related browsing contexts be a set containing context.
Resume with "download started", navigation id, and navigation status.
For each session in the set of sessions for which an event is enabled given "browsingContext.downloadWillBegin" and related browsing contexts:
1. Emit an event with session and body.

7.2.4.8. The browsingContext.navigationAborted Event

Event Type

 BrowsingContextNavigationAborted = {
  method: "browsingContext.navigationAborted",
  params: NavigationInfo
}

The remote end event trigger is the steps given context and navigation status:

Let params be the result of get the navigation info given context and navigation status.
Let body be a map matching the BrowsingContextNavigationAborted production, with the params field set to params.
Let navigation id be navigation status’s id.
Let related browsing contexts be a set containing context.
Resume with "navigation aborted", navigation id, and navigation status.
For each session in the set of sessions for which an event is enabled given "browsingContext.navigationAborted" and related browsing contexts:
1. Emit an event with session and body.

7.2.4.9. The browsingContext.navigationFailed Event

Event Type

 BrowsingContextNavigationFailed = {
  method: "browsingContext.navigationFailed",
  params: NavigationInfo
}

The remote end event trigger is the steps given context and navigation status:

Let params be the result of get the navigation info given context and navigation status.
Let body be a map matching the BrowsingContextNavigationFailed production, with the params field set to params.
Let navigation id be navigation status’s id.
Let related browsing contexts be a set containing context.
Resume with "navigation failed", navigation id, and navigation status.
For each session in the set of sessions for which an event is enabled given "browsingContext.navigationFailed" and related browsing contexts:
1. Emit an event with session and body.

7.3. The script Module

The script module contains commands and events relating to script realms and execution.

7.3.1. Definition

Remote end definition

ScriptCommand = (
  ScriptCallFunctionCommand //
  ScriptEvaluateCommand //
  ScriptGetRealmsCommand
)

local end definition

ScriptResult = (
  ScriptCallFunctionResult //
  ScriptEvaluateResult //
  ScriptGetRealmsResult
)

ScriptEvent = (
    ScriptRealmCreatedEvent //
    ScriptRealmDestroyedEvent
)

7.3.2. Types

7.3.2.1. The script.ExceptionDetails type

Remote end definition and local end definition

ExceptionDetails = {
  columnNumber: uint,
  exception: RemoteValue,
  lineNumber: uint,
  stackTrace: StackTrace,
  text: text,
};

The ExceptionDetails type represents a JavaScript exception.

To get exception details given a realm, a completion record record and an ownership type:

Assert: record.[[Type]] is throw.
Let text be an implementation-defined textual description of the error represented by record.

TODO: Tighten up the requirements here; people will probably try to parse this data with regex or something equally bad.
Let exception be the result of serialize as a remote value given record.[[Value]], 1 as max depth, ownership type, a new Map as serialization internal map and realm.
Let stack trace be the stack trace for an exception given record.
If stack trace has size of 1 or greater, let line number be value of the lineNumber field in stack trace[0], and let column number be the value of the columnNumber field stack trace[0]. Otherwise let line number and column number be 0.
Let exception details be a map matching the ExceptionDetails production, with the text field set to text, the exception field set to exception, the lineNumber field set to line number, the columnNumber field set to column number, and the stackTrace field set to stack trace.
Return exception details.

7.3.2.2. The script.Realm type

Remote end definition and local end definition

Realm = text;

Each realm has an associated realm id, which is a string uniquely identifying that realm. This is implicitly set when the realm is created.

To get a realm given realm id:

If realm id is null, return success with data null.
If there is no realm with id realm id return error with error code no such frame
Let realm be the realm with id realm id.
Return success with data realm

This has the wrong error code

7.3.2.3. The script.RealmInfo type

Local end definition

RealmInfo = {
  WindowRealmInfo //
  DedicatedWorkerRealmInfo //
  SharedWorkerRealmInfo //
  ServiceWorkerRealmInfo //
  WorkerRealmInfo //
  PaintWorkletRealmInfo //
  AudioWorkletRealmInfo //
  WorkletRealmInfo //
}

BaseRealmInfo = {
  realm: Realm,
  origin: text
}

WindowRealmInfo = {
  BaseRealmInfo,
  type: "window",
  context: BrowsingContext
}

DedicatedWorkerRealmInfo = {
  BaseRealmInfo,
  type: "dedicated-worker"
}

SharedWorkerRealmInfo = {
  BaseRealmInfo,
  type: "shared-worker"
}

ServiceWorkerRealmInfo = {
  BaseRealmInfo,
  type: "service-worker"
}

WorkerRealmInfo = {
  BaseRealmInfo,
  type: "worker"
}

PaintWorkletRealmInfo = {
  BaseRealmInfo,
  type: "paint-worklet"
}

AudioWorkletRealmInfo = {
  BaseRealmInfo,
  type: "audio-worklet"
}

WorkletRealmInfo = {
  BaseRealmInfo,
  type: "worklet"
}

The RealmInfo type represents the properties of a realm.

To get the realm info given environment settings:

Let realm be environment settings’ realm execution context's Realm component.
Let realm id be the realm id for realm.
Let origin be the serialization of an origin given environment settings’s origin.
Let global object be the global object specified by environment settings
Run the steps under the first matching condition:
global object is a Window object
1. Let document be environment settings’ responsible document.
2. Let browsing context be document’s browsing context.
3. Let context id be the browsing context id for browsing context.
4. Let realm info be a map matching the WindowRealmInfo production, with the realm field set to realm id, the origin field set to origin, and the context field set to context id.
global object is a DedicatedWorkerGlobalScope object
1. Let realm info be a map matching the DedicatedWorkerRealmInfo production, with the realm field set to realm id, and the origin field set to origin.
global object is a SharedWorkerGlobalScope object
1. Let realm info be a map matching the SharedWorkerRealmInfo production, with the realm field set to realm id, and the origin field set to origin.
global object is a ServiceWorkerGlobalScope object
1. Let realm info be a map matching the ServiceWorkerRealmInfo production, with the realm field set to realm id, and the origin field set to origin.
global object is a WorkerGlobalScope object
1. Let realm info be a map matching the WorkerRealmInfo production, with the realm field set to realm id, and the origin field set to origin.
global object is a PaintWorkletGlobalScope object
1. Let realm info be a map matching the PaintWorkletRealmInfo production, with the realm field set to realm id, and the origin field set to origin.
global object is a AudioWorkletGlobalScope object
1. Let realm info be a map matching the AudioWorkletRealmInfo production, with the realm field set to realm id, and the origin field set to origin.
global object is a WorkletGlobalScope object
1. Let realm info be a map matching the WorkletRealmInfo production, with the realm field set to realm id, and the origin field set to origin.
Otherwise:
1. Let realm info be null.
Return realm info

Note: Future variations of this specification will retain the invariant that the last component of the type name after splitting on "-" will always be "worker" for globals implementing WorkerGlobalScope, and "worklet" for globals implementing WorkletGlobalScope.

7.3.2.4. The script.StackFrame type

StackFrame = {
  columnNumber: int,
  functionName: text,
  lineNumber: int,
  url: text,
}

A frame in a stack trace is represented by a StackFrame object. This has a url property, which represents the URL of the script, a functionName property which represents the name of the executing function, and lineNumber and columnNumber properties, which represent the line and column number of the executed code.

7.3.2.5. The script.StackTrace type

StackTrace = {
  callFrames: [*StackFrame],
}

The StackTrace type represents the javascript stack at a point in script execution.

Note: The details of how to get a list of stack frames, and the properties of that list are underspecified, and therefore the details here are implementation defined.

It is assumed that an implementation is able to generate a list of stack frames, which is a list with one entry for each item in the javascript call stack, starting from the most recent. Each entry is a single stack frame corresponding to execution of a statement or expression in a script script, which contains the following fields:

script url: The url of the resource containing script
function: The name of the function being executed
line number: The zero-based line number of the executed code, relative to the top of the resource containing script.
column number: The zero-based column number of the executed code, relative to the start of the line in the resource containing script.

To construct a stack trace, with a list of stack frames stack:

Let call frames be a new list.
For each stack frame frame in stack, starting from the most recently executed frame, run the following steps:
1. Let url be the result of running the URL serializer, given the URL of frame’s script url.
2. Let frame info be a new map matching the StackFrame production, with the url field set to url, the functionName field set to frame’s function, the lineNumber field set to frame’s line number and the columnNumber field set to frame’s column number.
Append frame info to call frames.
Let stack trace be a new map matching the StackTrace production, with the callFrames property set to call frames.
Return stack trace.

The current stack trace is the result of construct a stack trace given a list of stack frames representing the callstack of the running execution context.

The stack trace for an exception with an exception, or a Completion Record of type throw, exception, is given by:

If exception is a value that has been thrown as an exception, let record be the Completion Record created to throw exception. Otherwise let record be exception.
Let stack be the list of stack frames corresponding to execution at the point record was created.
Return construct a stack trace given stack.

7.3.2.6. The script.Result type

Remote end definition and local end definition

ScriptResult = (
  ScriptResultSuccess //
  ScriptResultException
)

ScriptResultSuccess = {
  result: RemoteValue,
  realm: Realm
}

ScriptResultException = {
  exceptionDetails: ExceptionDetails
  realm: Realm
}

The Result type indicates the return value of a command that executes script. The ScriptResultSuccess variant is used in cases where the script completes normally and the ScriptResultException variant is used in cases where the script completes with a thrown exception.

7.3.2.7. The script.Target type

Remote end definition and local end definition

RealmTarget = {realm: Realm};

ContextTarget = {
  context: BrowsingContext,
  ?sandbox: text
}

Target = (
  RealmTarget //
  ContextTarget
);

The Target type represents a value that is either a script.Realm or a browsingContext.BrowsingContext. This is useful in cases where a context identifier can stand in for the realm associated with the context’s active document.

To get a realm from a target given target:

If target matches the ContextTarget production:
1. Let context be the result of trying to get a browsing context with target["context"].
2. If target does not contain a field named "sandbox":
  1. Let document be context’s active document.
  2. Let environment settings be the environment settings object whose relevant global object's associated Document is document.
  3. Let realm be environment settings’ realm execution context's Realm component.
3. Otherwise: let realm be get or create a sandbox realm given target["sandbox"] and context.
Otherwise:
1. Assert: target matches the RealmTarget production.
2. Let realm id be the value of the realm field of target.
3. Let realm be get a realm given realm id.
Return success with data realm

This has the wrong error code

7.3.2.8. The script.Ownership type

SerializationOwnershipModel = "root" / "none"

The SerializationOwnershipModel specifies how the serialized value ownership should be treated.

7.3.3. Commands

7.3.3.1. The script.disown Command

The script.disown command disowns the given handles. This does not guarantee the handled object will be garbage collected, as there can be other handles or strong ECMAScript references.

Command Type

ScriptDisownCommand = {
  method: "script.disown",
  params: ScriptDisownParameters
}

ScriptDisownParameters = {
  handles: [Handle]
  target: Target;
}

The remote end steps with command parameters are:

Let realm be the result of trying to get a realm from a target given the value of the target field of command parameters.
Let handles the value of the handles field of command parameters.
For each handle id of handles:
1. Let handle map be realm’s handle object map
2. If handle map contains handle id, remove handle id from the handle map.

7.3.3.2. The script.callFunction Command

The script.callFunction command calls a provided function with given arguments in a given realm.

RealmInfo can be either a realm or a browsing context.

Note: In case of an arrow function in functionDeclaration, the this argument doesn’t affect function’s this binding.

Command Type

ScriptCallFunctionCommand = {
  method: "script.callFunction",
  params: ScriptCallFunctionParameters
}

ScriptCallFunctionParameters = {
  functionDeclaration: text;
  ?arguments: [ArgumentValue];
  ?this: ArgumentValue;
  ?awaitPromise: bool;
  target: Target;
  ?ownership: OwnershipModel;
}

ArgumentValue = (
  RemoteReference //
  LocalValue
);

Return Type

ScriptCallFunctionResult = ScriptResult;

TODO: Add timeout argument as described in the script.evaluate.

To deserialize arguments given realm and serialized arguments list:

Let deserialized arguments list be an empty list.
For each serialized argument of serialized arguments list:
1. Let deserialized argument be the result of trying to deserialize local value given realm and serialized argument.
2. Append deserialized argument to the deserialized arguments list.
Return success with data deserialized arguments list.

To evaluate function body given function declaration, environment settings, base URL, and options:

Note: the function declaration is parenthesized and evaluated.

Let parenthesized function declaration be concatenate «"(", function declaration, ")"»
Let function script be the result of create a classic script with parenthesized function declaration, environment settings, base URL, and options.
Prepare to run script with environment settings.
Let function body evaluation status be ScriptEvaluation(function script’s record).
Clean up after running script with environment settings.
Return function body evaluation status.

The remote end steps with command parameters are:

Let realm be the result of trying to get a realm from a target given the value of the target field of command parameters.
Let realm id be realm’s realm id.
Let environment settings be the environment settings object whose realm execution context's Realm component is realm.
Let command arguments be the value of the arguments field of command parameters.
Let deserialized arguments be an empty list.
If command arguments is not null, set deserialized arguments to the result of trying to deserialize arguments given realm and command arguments.
Let this parameter be the value of the this field of command parameters.
Let this object be null.
If this parameter is not null, set this object to the result of trying to deserialize local value given realm and this parameter.
Let function declaration be the value of the functionDeclaration field of command parameters.
Let await promise be the value of the awaitPromise field of command parameters, if present, or true otherwise.
Let result ownership be the value of the resultOwnership field of command parameters, if present, or none otherwise.
Let function body evaluation status be the result of evaluate function body (function declaration, environment settings, base URL, and options).
If function body evaluation status.[[Type]] is throw, return error with error code invalid argument.
Let function object be function body evaluation status.[[Value]].
If IsCallable(function object) is false:
1. Return an error with error code Invalid Argument
Prepare to run script with environment settings.
Set evaluation status to Call(function object, this object, deserialized arguments).
If evaluation status.[[Type]] is normal, and await promise is true, and IsPromise(evaluation status.[[Value]]):
1. Set evaluation status to Await(evaluation status.[[Value]]).
Clean up after running script with environment settings.
If evaluation status.[[Type]] is throw:
1. Let exception details be the result of get exception details given realm, evaluation status and result ownership as ownership type.
2. Return a new map matching the ScriptResultException production, with the exceptionDetails field set to exception details.
Assert: evaluation status.[[Type]] is normal.
Let result be the result of serialize as a remote value given evaluation status.[[Value]], 1 as max depth, result ownership as ownership type, new map as serialization internal map and realm.
Return a new map matching the ScriptResultSuccess production, with the realm field set to realm id, and the result field set to result.

7.3.3.3. The script.evaluate Command

The script.evaluate command evaluates a provided script in a given realm. For convenience a browsing context can be provided in place of a realm, in which case the realm used is the realm of the browsing context’s active document.

The method returns the value of executing the provided script, unless it returns a promise and awaitPromise is true (which is the default), in which case the resolved value of the promise is returned.

Command Type

ScriptEvaluateCommand = {
  method: "script.evaluate",
  params: ScriptEvaluateParameters
}

ScriptEvaluateParameters = {
  expression: text;
  target: Target;
  ?awaitPromise: bool;
  ?resultOwnership: OwnershipModel;
}

Return Type

ScriptEvaluateResult = ScriptResult;

TODO: Add timeout argument. It’s not totally clear how this ought to work; in Chrome it seems like the timeout doesn’t apply to the promise resolve step, but that likely isn’t what clients want.

The remote end steps with command parameters are:

Let realm be the result of trying to get a realm from a target given the value of the target field of command parameters.
Let realm id be realm’s realm id.
Let environment settings be the environment settings object whose realm execution context's Realm component is realm.
Let source be the value of the expression field of command parameters.
Let await promise be the value of the awaitPromise field of command parameters, if present, or true otherwise.
Let result ownership be the value of the resultOwnership field of command parameters, if present, or none otherwise.
Let options be the default classic script fetch options.
Let base URL be the API base URL of environment settings.
Let script be the result of create a classic script with source, environment settings, base URL, and options.
Prepare to run script with environment settings.
Set evaluation status to ScriptEvaluation(script’s record).
If evaluation status.[[Type]] is normal, await promise is true, and IsPromise(evaluation status.[[Value]]):
1. Set evaluation status to Await(evaluation status.[[Value]]).
Clean up after running script with environment settings.
If evaluation status.[[Type]] is throw:
1. Let exception details be the result of get exception details given realm, evaluation status and result ownership as ownership type.
2. Return a new map matching the ScriptResultException production, with the realm field set to realm id, and the exceptionDetails field set to exception details.
Assert: evaluation status.[[Type]] is normal.
Let result be the result of serialize as a remote value given evaluation status.[[Value]], 1 as max depth, result ownership as ownership type, new map as serialization internal map and realm.
Return a new map matching the ScriptResultSuccess production, with the with the realm field set to realm id, and the result field set to result.

7.3.3.4. The script.getRealms Command

The script.getRealms command returns a list of all realms, optionally filtered to realms of a specific type, or to the realm associated with the document currently loaded in a specified browsing context.

Command Type

ScriptGetRealmsCommand = {
  method: "script.getRealms",
  params: GetRealmsParameters
}

GetRealmsParameters = {
  ?context: BrowsingContext,
  ?type: RealmType,
}

Return Type

RealmInfoList = [* RealmInfo]

ScriptGetRealmsResult = {
  realms: RealmInfoList
}

The remote end steps with session and command parameters are:

Let environment settings be a list of all the environment settings objects that have their execution ready flag set.
If command parameters contains context:
1. Let context be the result of trying to get a browsing context with command parameters["context"].
2. Let document be context’s active document.
3. Let context environment settings be a list.
4. For each settings of environment settings:
  1. If any of the following conditions hold:
    - The associated Document of settings’ relevant global object is document
    - The global object specified by settings is a WorkerGlobalScope with document in its owner set
    Append settings to context environment settings.
5. Set environment settings to context environment settings.
Let realms be a list.
For each settings of environment settings:
1. Let realm info be the result of get the realm info given settings
2. If command parameters contains type and realm info["type"] is not equal to command parameters["type"] then continue.
3. If realm info is not null, append realm info to realms.
Let body be a map matching the GetRealmsResult production, with the realms field set to realms.
Return success with data body.

Extend this to also allow realm parents e.g. for nested workers? Or get all ancestor workers.

We might want to have a more sophisticated filter system than just a literal match.

7.3.4. Events

7.3.4.1. The script.realmCreated Event

Event Type

 ScriptRealmCreatedEvent = {
  method: "script.realmCreated",
  params: RealmInfo
}

The remote end event trigger is:

When any of the set up a window environment settings object, set up a worker environment settings object or set up a worklet environment settings object algorithms are invoked, immediately prior to returning the settings object:

Let environment settings be the newly created environment settings object.
Let realm info be be the result of get the realm info given environment settings.
If realm info is null, return.
Let related browsing contexts be the result of get related browsing contexts given environment settings.
Let body be a map matching the RealmCreatedEvent production, with the params field set to realm info.
For each session in the set of sessions for which an event is enabled given "script.realmCreated" and related browsing contexts:
1. Emit an event with session and body.

The remote end subscribe steps with subscribe priority 2, given session, contexts and include global are:

Let environment settings be a list of all the environment settings objects that have their execution ready flag set.
For each settings of environment settings:
1. Let related browsing contexts be a new set.
2. If the associated Document of settings’ relevant global object is a Document:
  1. Let context be settings’s relevant global object's associated Document’s browsing context's top-level browsing context.
  2. If context is not in contexts, continue.
  3. Append context to related browsing contexts.
  Otherwise, if include global is false, continue.
3. Let realm info be the result of get the realm info given settings
4. Let body be a map matching the RealmCreatedEvent production, with the params field set to realm info.
5. If event is enabled givenn session, "script.realmCreated" and related browsing contexts:
  1. Emit an event with session and body.

Should the order here be better defined?

7.3.4.2. The script.realmDestroyed Event

Event Type

RealmDestroyedParameters = {
  realm: Realm
}

ScriptRealmDestroyedEvent = {
  method: "script.realmDestoyed",
  params: RealmDestroyedParameters
}

The remote end event trigger is:

Define the following unloading document cleanup steps with document:

Let related browsing contexts be an empty set.
Append document’s browsing context to related browsing contexts.
For each worklet global scope in document’s worklet global scopes:
1. Let realm be worklet global scope’s relevant Realm.
2. Let realm id be the realm id for realm.
3. Let params be a map mathcing the RealmDestroyedParameters production, with the realm field set of realm id.
4. Let body be a map matching the RealmDestroyedEvent production, with the params field set to params.
5. For each session in the set of sessions for which an event is enabled given "script.realmDestroyed" and related browsing contexts:
  1. Emit an event with session and body.
Let environment settings be the environment settings object whose relevant global object's associated Document is document.
Let realm be environment settings’ realm execution context's Realm component.
Let realm id be the realm id for realm.
Let params be a map mathcing the RealmDestroyedParameters production, with the realm field set to realm id.
Let body be a map matching the RealmDestroyedEvent production, with the params field set to params.
For each session in the set of sessions for which an event is enabled given "script.realmDestroyed" and related browsing contexts:
1. Emit an event with session and body.

Whenever a worker event loop event loop is destroyed, either because the worker comes to the end of its lifecycle, or prematurely via the terminate a worker algorithm:

Let environment settings be the environment settings object for which event loop is the responsible event loop.
Let related browsing contexts be the result of get related browsing contexts given environment settings.
Let realm be environment settings’s environment settings object’s Realm.
Let realm id be the realm id for realm.
Let params be a map mathcing the RealmDestroyedParameters production, with the realm field set of realm id.
Let body be a map matching the RealmDestroyedEvent production, with the params field set to params.

7.4. Log

The log module contains functionality and events related to logging.

A BiDi Session has a log event buffer which is a map from browsing context id to a list of log events for that context that have not been emitted. User agents may impose a maximum size on this buffer, subject to the condition that if events A and B happen in the same context with A occuring before B, and both are added to the buffer, the entry for B must not be removed before the entry for A.

To buffer a log event given session, contexts and event:

Let buffer be session’s log event buffer.
Let context ids be a new list.
For each context of contexts:
1. Append the browsing context id for context to context ids.
For each context id in context ids:
1. Let other contexts be an empty list
2. For each other id in context ids:
3. If other id is not equal to context id, append other id to other contexts.
4. If buffer does not contain context id, let buffer[context id] be a new list.
5. Append (event, other contexts) to buffer[context id].

Note: we store the other contexts here so that each event is only emitted once. In practice this is only relevant for workers that can be associated with multiple browsing contexts.

Do we want to key this on browsing context or top-level browsing context? The difference is in what happens if an event occurs in a frame and that frame is then navigated before the local end subscribes to log events for the top level context.

7.4.1. Definition

remote end definition

LogEvent = (
  LogEntryAddedEvent
)

7.4.2. Types

7.4.2.1. log.LogEntry

LogLevel = "debug" / "info" / "warning" / "error"

LogEntry = (
  GenericLogEntry //
  ConsoleLogEntry //
  JavascriptLogEntry
)

BaseLogEntry = {
  level: LogLevel,
  text: text / null,
  timestamp: int,
  ?stackTrace: StackTrace,
}

GenericLogEntry = {
  BaseLogEntry,
  type: text,
}

ConsoleLogEntry = {
  BaseLogEntry,
  type: "console",
  method: text,
  realm: Realm,
  args: [*RemoteValue],
}

JavascriptLogEntry = {
  BaseLogEntry,
  type: "javascript",
}

Each log event is represented by a LogEntry object. This has a type property which represents the type of log entry added, a level property representing severity, a text property with the log message string itself, and a timestamp property corresponding to the time the log entry was generated. Specific variants of the LogEntry are used to represent logs from different sources, and provide additional fields specific to the entry type.

7.4.3. Events

7.4.3.1. The log.entryAdded Event

Event Type

 LogEntryAddedEvent = {
  method: "log.entryAdded",
  params: LogEntry,
}

The remote end event trigger is:

Define the following console steps with method, args, and options:

If method is "error" or "assert", let level be "error". If method is "debug" or "trace" let level be "debug". If method is "warn" or warning, let level be "warning". Otherwise let level be "info".
Let timestamp be a time value representing the current date and time in UTC.
Let text be an empty string.
If Type(|args[0]) is String, and args[0] contains a formatting specifier, let formatted args be Formatter(args). Otherwise let formatted args be args.

This is underdefined in the console spec, so it’s unclar if we can get interoperable behaviour here.
For each arg in formatted args:
1. If arg is not the first entry in args, append a U+0020 SPACE to text.
2. If arg is a primitive ECMAScript value, append ToString(arg) to text. Otherwise append an implementation-defined string to text.
Let realm be the realm id of the current Realm Record.
Let serialized args be a new list.
For each arg of args:
1. Let serialized arg be the result of serialize as a remote value given arg as value, 1 as max depth, none as ownership type, a new Map as serialization internal map, and realm.
2. Add serialized arg to serialized args.
If method is "assert", "error", "trace", or "warn", let stack be the current stack trace. Otherwise let stack be null.
Let entry be a map matching the ConsoleLogEntry production, with the the level field set to level, the text field set to text, the timestamp field set to timestamp, the stackTrace field set to stack if stack is not null, or omitted otherwise, the method field set to method, the realm field set to realm and the args field set to serialized args.
Let body be a map matching the LogEntryAddedEvent production, with the params field set to entry.
Let settings be the current settings object
Let related browsing contexts be the result of get related browsing contexts given settings.
For each session in active BiDi sessions:
1. If event is enabled with session, "log.entryAdded" and related browsing contexts, emit an event with session and body.
  
  Otherwise, buffer a log event with session, related browsing contexts, and body.

Define the following error reporting steps with arguments script, line number, column number, message and handled:

If handled is true return.
Let settings be script’s settings object.
Let stack be the stack trace for an exception with the exception corresponding to the error being reported.
Let entry be a map matching the JavascriptLogEntry production, with level set to "error", text set to message, and the timestamp field set to timestamp.
Let related browsing contexts be the result of get related browsing contexts given settings.
For each session in active BiDi sessions:
1. If event is enabled with session, "log.entryAdded" and related browsing contexts, emit an event with session and body.
  
  Otherwise, buffer a log event with session, related browsing contexts, and body.

Lots more things require logging. CDP has LogEntryAdded types xml, javascript, network, storage, appcache, rendering, security, deprecation, worker, violation, intervention, recommendation, other. These are in addition to the js exception and console API types that are represented by different methods.

Allow implementation-defined log types

The remote end subscribe steps, with subscribe priority 10, given session, contexts and include global are:

For each context id → events in session’s log event buffer:
1. Let maybe context be the result of getting a browsing context given context id.
2. If maybe context is an error, remove context id from log event buffer and continue.
3. Let context be maybe context’s data
4. Let top level context be context’s top-level browsing context.
5. If include global is true and top level context is not in contexts, or if include global is false and top level context is in contexts:
  1. For each (event, other contexts) in events:
    1. Emit an event with session and event.
    2. For each other context id in other contexts:
      1. If log event buffer contains other context id, remove event from log event buffer[other context id].

8. Patches to Other Specifications

This specification requires some changes to external specifications to provide the necessary integration points. It is assumed that these patches will be committed to the other specifications as part of the standards process.

8.1. HTML

The a browsing context is discarded algorithm is modified to read as follows:

To discard a browsing context browsingContext, run these steps:

If this is not a recursive invocation of this algorithm, call any browsing context tree discarded steps defined in other applicable specifications with browsingContext.
Discard all Document objects for all the entries in browsingContext’s session history.
If browsingContext is a top-level browsing context, then remove a browsing context browsingContext.

The actual patch might be better to split the algorithm into an outer algorithm that is called by external callers and an inner algorithm that’s used for recursive calls. That’s quite hard to express as a patch to the specification since it requires changing multiple parts.

The report an error algorithm is modified with an additional step at the end:

Call any error reporting steps defined in external specifications with script, line, col, message, and true if the error is handled, or false otherwise.

8.2. Console

Other specifications can define console steps. When any method of the console interface is called, with method name method and argument args:

If that method does not call the Printer operation, call any console steps defined in external specification with arguments method, args and, undefined.

Otherwise, at the point when the Printer operation is called with arguments name, printerArgs and options (which is undefined if the argument is not provided), call any console steps defined in external specification with arguments name, printerArgs, and options.

WebDriver BiDi

Abstract

Status of this document

1. Introduction

2. Infrastructure

3. Protocol

3.1. Definition

3.2. Session

3.3. Modules

3.4. Commands

3.5. Events

4. Transport

4.1. Establishing a Connection

5. Sandboxed Script Execution

5.1. Sandbox Realms

5.2. Sandbox Proxy Objects

5.3. SandboxWindowProxy

6. Common Data Types

6.1. Reference

6.2. Protocol Value

6.2.1. Primitive Protocol Value

6.2.1.1. Serialization

6.2.1.2. Deserialization

6.2.2. Local Value

6.2.2.1. Deserialization

6.2.3. Remote Value

6.2.3.1. Serialization

7. Modules

7.1. The session Module

7.1.1. Definition

7.1.2. Types

7.1.2.1. The session.CapabilitiesRequest Type

7.1.3. Commands

7.1.3.1. The session.status Command

7.1.3.2. The session.new Command

7.1.3.3. The session.subscribe Command

7.1.3.4. The session.unsubscribe Command

7.2. The browsingContext Module

7.2.1. Definition

7.2.2. Types

7.2.2.1. The browsingContext.BrowsingContext Type

7.2.2.2. The browsingContext.BrowsingContextInfo Type

7.2.2.3. The browsingContext.Navigation Type

7.2.2.4. The browsingContext.NavigationInfo Type

7.2.3. Commands

7.2.3.1. The browsingContext.close Command

7.2.3.2. The browsingContext.create Command

7.2.3.3. The browsingContext.getTree Command

7.2.3.4. The browsingContext.navigate Command

7.2.3.5. The browsingContext.reload Command

7.2.4. Events

7.2.4.1. The browsingContext.contextCreated Event

7.2.4.2. The browsingContext.contextDestroyed Event

7.2.4.3. The browsingContext.navigationStarted Event

7.2.4.4. The browsingContext.fragmentNavigated Event

7.2.4.5. The browsingContext.domContentLoaded Event

7.2.4.6. The browsingContext.load Event

7.2.4.7. The browsingContext.downloadWillBegin Event

7.2.4.8. The browsingContext.navigationAborted Event

7.2.4.9. The browsingContext.navigationFailed Event

7.3. The script Module

7.3.1. Definition

7.3.2. Types

7.3.2.1. The script.ExceptionDetails type

7.3.2.2. The script.Realm type

7.3.2.3. The script.RealmInfo type

7.3.2.4. The script.StackFrame type

7.3.2.5. The script.StackTrace type

7.3.2.6. The script.Result type

7.3.2.7. The script.Target type

7.3.2.8. The script.Ownership type

7.3.3. Commands

7.3.3.1. The script.disown Command

7.3.3.2. The script.callFunction Command

7.3.3.3. The script.evaluate Command

7.3.3.4. The script.getRealms Command

7.3.4. Events

7.3.4.1. The script.realmCreated Event

7.3.4.2. The script.realmDestroyed Event

7.4. Log