[pull] main from mdn:main

files/en-us/web/api/cookiestoremanager/subscribe/index.md

@@ -10,6 +10,8 @@ browser-compat: api.CookieStoreManager.subscribe
 
 The **`subscribe()`** method of the {{domxref("CookieStoreManager")}} interface subscribes a {{domxref("ServiceWorkerRegistration")}} to cookie change events.
 
+Duplicate subscriptions are ignored: that is, if a service worker subscribes more than once to the same cookie, it will only receive each change notification once.
+
 ## Syntax
 
 ```js-nolint
@@ -20,10 +22,10 @@ subscribe(subscriptions)
 
 - `subscriptions`
   - : An array of objects, each of which has the following properties:
-    - `name`
-      - : A string with the name of a cookie.
-    - `url`
-      - : A string with the url of a cookie scope. This may be narrower than the scope of the service worker registration.
+    - `name` {{optional_inline}}
+      - : A string equal to the name of a cookie. If `name` is omitted, the service worker is subscribed to change events for all cookies that are in scope.
+    - `url` {{optional_inline}}
+      - : A string equal to the URL of a cookie scope. This may be narrower than the scope of the service worker registration. If `url` is omitted, it defaults to the scope of the service worker registration.
 
 ### Return value
 
@@ -32,23 +34,55 @@ A {{jsxref("Promise")}} that resolves with {{jsxref("undefined")}} when the subs
 ### Exceptions
 
 - {{jsxref("TypeError")}}
-  - : Thrown if the URL passed in `subscriptions` does not match the service worker registration's {{domxref("ServiceWorkerRegistration.scope","scope")}}.
+  - : Thrown if the `url` is not a valid URL, or doesn't start with the service worker registration's {{domxref("ServiceWorkerRegistration.scope","scope")}}.
 
 ## Examples
 
+### Setting name and URL
+
 In this example, the {{domxref("ServiceWorkerRegistration")}} represented by `registration` is subscribing to change events on the cookie named `"cookie1"` with a scope of `"/path1"`.
 
 ```js
+// Subscribe to a specific cookie and URL
 const subscriptions = [{ name: "cookie1", url: `/path1` }];
 await registration.cookies.subscribe(subscriptions);
 ```
 
-The URL passed to the `subscribe()` method, may be narrower than the service worker registration scope. In the following example the subscription is for `/path/one/`, so it will receive change events for changes on the first cookie, but not the second.
+### Setting name only
+
+In this example, we set only `name` and omit `url`: the subscription applies to all cookies named `cookie1` within the service worker's scope.
 
 ```js
-registration.cookies.subscribe([{ name: "cookie1", url: "/path/one/" }]); // subscription
-cookieStore.set({ name: "cookie1", value: "cookie-value", path: "/path/one/" }); // receives a change event
-cookieStore.set({ name: "cookie1", value: "cookie-value", path: "/path/two/" }); // does not receive a change event
+// Subscribe to all cookies named "cookie1" in the registration scope
+await registration.cookies.subscribe([{ name: "cookie1" }]);
+```
+
+### Setting URL only
+
+In this example we set only `url`, and omit `name`: the subscription applies to all cookies within the specified URL scope.
+
+```js
+// Subscribe to all cookie changes within a specific path
+await registration.cookies.subscribe([{ url: "/path/one/" }]);
+```
+
+### Subscribing to all cookies
+
+In this example, both `name` and `url` are omitted. The subscription applies to all cookies within the service worker's scope.
+
+```js
+// Subscribe to all cookie changes within the entire registration scope
+await registration.cookies.subscribe([{}]);
+```
+
+### Setting a URL outside the service worker's scope
+
+If the URL is outside the service worker's scope, `subscribe()` will throw a `TypeError`.
+
+```js example-bad
+await registration.cookies.subscribe([
+  { name: "cookie1", url: "/out-of-scope/" },
+]);
 ```
 
 ## Specifications

files/en-us/web/webdriver/reference/bidi/modules/index.md

@@ -18,7 +18,7 @@ Both command and event names use the module name as a prefix: `module_name.comma
 
 ## Commands
 
-A command is an asynchronous operation sent from the client to the browser. Each command message you send to the browser has three fields:
+A command is an asynchronous operation sent from the client to the browser. Each command message _you send_ to the browser has three fields:
 
 - `id`: A number you assign to the command. Unlike HTTP where each request waits for a response, a WebSocket connection can have multiple commands in flight at the same time and responses may arrive out of order. The `id` lets you match each response to the command that triggered it.
 - `method`: The command to run, in the form `module_name.command_name`.
@@ -45,6 +45,12 @@ To receive events, the client must first subscribe to them using the `session.su
 
 The client can subscribe to a specific event or to all events in a module. For example, subscribing to `"browsingContext.contextCreated"` subscribes the client to that single event, while subscribing to `"browsingContext"` subscribes the client to every event in the `browsingContext` module.
 
+Every event notification _you receive_ from the browser has three fields:
+
+- `type`: Always `"event"`.
+- `method`: The event name, in the form `module_name.event_name`.
+- `params`: An object containing the event-specific data. The structure of `params` is specific to each event.
+
 The following is a sample event message sent by the browser when the client is subscribed to `log.entryAdded` and a console message is logged (some fields have been omitted for brevity):
 
 ```json
@@ -53,11 +59,10 @@ The following is a sample event message sent by the browser when the client is s
   "method": "log.entryAdded",
   "params": {
     "type": "console",
-    "method": "log",
-    "realm": null,
     "level": "info",
     "text": "Hello world",
-    "timestamp": 1657282076037
+    "timestamp": 1657282076037,
+    "method": "log"
   }
 }
 ```

files/en-us/web/webdriver/reference/bidi/modules/log/entryadded/index.md

@@ -0,0 +1,189 @@
+---
+title: log.entryAdded event
+short-title: log.entryAdded
+slug: Web/WebDriver/Reference/BiDi/Modules/log/entryAdded
+page-type: webdriver-event
+browser-compat: webdriver.bidi.log.entryAdded_event
+sidebar: webdriver
+---
+
+The `log.entryAdded` [event](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules#events) of the [`log`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/log) module fires when a new log entry is created in the browser, from either a console API call or an unhandled JavaScript error.
+
+## Event data
+
+The `params` field in the event notification is a log entry object. Based on the source of the log, the log entry object has different types: `"console"` or `"javascript"`. Each type may provide additional fields specific to that source.
+
+### Common fields
+
+All log entry objects include the following fields:
+
+- `level`
+  - : A string that indicates the severity of the log entry. It has one of the following values:
+    - `"debug"`: A debug-level message (from {{domxref("console/debug_static", "console.debug()")}} or {{domxref("console/trace_static", "console.trace()")}}).
+    - `"info"`: An informational message (from {{domxref("console/log_static", "console.log()")}}, {{domxref("console/info_static", "console.info()")}}, and [other console methods](/en-US/docs/Web/API/console) that don't produce a more specific level).
+    - `"warn"`: A warning message (from {{domxref("console/warn_static", "console.warn()")}}).
+    - `"error"`: An error message (from {{domxref("console/error_static", "console.error()")}} or {{domxref("console/assert_static", "console.assert()")}}).
+- `source`
+  - : An object that identifies the [realm](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/script/getRealms) where the log entry was created. It contains the following fields:
+    - `realm`
+      - : A string that contains the ID of the realm.
+    - `context` {{optional_inline}}
+      - : A string that contains the ID of the context in which the log entry was created.
+    - `userContext` {{optional_inline}}
+      - : A string that contains the ID of the user context in which the script-related event occurred.
+- `stackTrace` {{optional_inline}}
+  - : An object with a `callFrames` array that represents the [JavaScript stack](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/script/stackTrace) at the point the entry was created. Each item in the array is a stack frame with the following fields: `columnNumber`, `functionName`, `lineNumber`, and `url`.
+- `text`
+  - : A string that contains the log message or `null` if not available. For console entries, it is the concatenation of all stringified arguments joined by spaces, and for JavaScript errors, it is generally the error message.
+    The exact format is browser-dependent, so don't rely on this value for assertions in tests.
+- `timestamp`
+  - : A non-negative integer that represents the time when the log entry was created, in UTC, as milliseconds elapsed since the epoch ({{jsxref("Date.now()")}}).
+- `type`
+  - : A string that identifies the source of the log entry. It has one of the following values:
+    - `"console"`: Indicates that the log entry was generated from a call to a console API method (for example, {{domxref("console/log_static", "console.log()")}}, {{domxref("console/warn_static", "console.warn()")}}). Log entry objects of this type include [additional fields](#console-entry-fields).
+    - `"javascript"`: Indicates that the log entry was generated from an unhandled JavaScript error.
+
+### `"console"` log entry fields
+
+In addition to the [common fields](#common-fields), log entry objects with `"type": "console"` also include:
+
+- `args`
+  - : An array of objects that represent the arguments passed to the console method. Each object has a `type` field (such as `"string"`, `"number"`, `"boolean"`, or `"array"`) and optional `value`, `handle`, and `internalId` fields.
+- `method`
+  - : A string that contains the name of the console method that was called (for example, `"log"`, `"error"`, `"assert"`, `"debug"`, `"trace"`, `"warn"`).
+
+## Examples
+
+### Receiving an event for a console log
+
+With a [WebDriver BiDi connection](/en-US/docs/Web/WebDriver/How_to/Create_BiDi_connection) and a [subscription](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/subscribe) to `log.entryAdded` active, the browser sends a `log.entryAdded` event when a script evaluates `console.log("hello", [1, true, "foo"])`:
+
+```json
+{
+  "type": "event",
+  "method": "log.entryAdded",
+  "params": {
+    "type": "console",
+    "method": "log",
+    "source": {
+      "realm": "7c37f4c0-abcd-1234-ef56-789012345678",
+      "context": "6B3D5B3A-6571-432B-8E96-E53B5C2ECBB5"
+    },
+    "args": [
+      {
+        "type": "string",
+        "value": "hello"
+      },
+      {
+        "type": "array",
+        "value": [
+          { "type": "number", "value": 1 },
+          { "type": "boolean", "value": true },
+          { "type": "string", "value": "foo" }
+        ]
+      }
+    ],
+    "level": "info",
+    "text": "hello 1,true,foo",
+    "timestamp": 1712345678901,
+    "stackTrace": {
+      "callFrames": [
+        {
+          "columnNumber": 8,
+          "functionName": "",
+          "lineNumber": 1,
+          "url": "https://example.com/app.js"
+        }
+      ]
+    }
+  }
+}
+```
+
+### Receiving an event for a console warning
+
+With a [WebDriver BiDi connection](/en-US/docs/Web/WebDriver/How_to/Create_BiDi_connection) and a [subscription](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/subscribe) to `log.entryAdded` active, the browser sends a `log.entryAdded` event when a script evaluates `console.warn("something went wrong")`:
+
+```json
+{
+  "type": "event",
+  "method": "log.entryAdded",
+  "params": {
+    "type": "console",
+    "method": "warn",
+    "source": {
+      "realm": "7c37f4c0-abcd-1234-ef56-789012345678",
+      "context": "6B3D5B3A-6571-432B-8E96-E53B5C2ECBB5"
+    },
+    "args": [
+      {
+        "type": "string",
+        "value": "something went wrong"
+      }
+    ],
+    "level": "warn",
+    "text": "something went wrong",
+    "timestamp": 1712345678950,
+    "stackTrace": {
+      "callFrames": [
+        {
+          "columnNumber": 8,
+          "functionName": "",
+          "lineNumber": 1,
+          "url": "https://example.com/app.js"
+        }
+      ]
+    }
+  }
+}
+```
+
+### Receiving an event for an unhandled JavaScript error
+
+With a [WebDriver BiDi connection](/en-US/docs/Web/WebDriver/How_to/Create_BiDi_connection) and a [subscription](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/subscribe) to `log.entryAdded` active, the browser sends a `log.entryAdded` event when an unhandled JavaScript error occurs:
+
+```json
+{
+  "type": "event",
+  "method": "log.entryAdded",
+  "params": {
+    "type": "javascript",
+    "level": "error",
+    "source": {
+      "realm": "7c37f4c0-abcd-1234-ef56-789012345678",
+      "context": "6B3D5B3A-6571-432B-8E96-E53B5C2ECBB5"
+    },
+    "text": "ReferenceError: undefinedVariable is not defined",
+    "timestamp": 1712345679100,
+    "stackTrace": {
+      "callFrames": [
+        {
+          "columnNumber": 27,
+          "functionName": "",
+          "lineNumber": 3,
+          "url": "https://example.com/app.js"
+        },
+        {
+          "columnNumber": 18,
+          "functionName": "",
+          "lineNumber": 3,
+          "url": "https://example.com/app.js"
+        }
+      ]
+    }
+  }
+}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [`session.subscribe`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/subscribe) command
+- [`console`](/en-US/docs/Web/API/console) API

files/en-us/web/webdriver/reference/bidi/modules/log/index.md

@@ -7,7 +7,15 @@ browser-compat: webdriver.bidi.log
 sidebar: webdriver
 ---
 
-The **`log`** module contains events related to logging.
+The **`log`** module provides an event for monitoring browser log entries, including [console API](/en-US/docs/Web/API/console) output and unhandled JavaScript errors.
+
+## Commands
+
+The `log` module has no associated commands.
+
+## Events
+
+{{ListSubPages}}
 
 ## Specifications
 

files/sidebars/webdriver.yaml

@@ -26,7 +26,10 @@ sidebar:
         code: true
       - link: /Web/WebDriver/Reference/BiDi/Modules/input
         code: true
-      - link: /Web/WebDriver/Reference/BiDi/Modules/log
+      - type: listSubPages
+        path: /Web/WebDriver/Reference/BiDi/Modules/log
+        link: /Web/WebDriver/Reference/BiDi/Modules/log
+        details: closed
         code: true
       - link: /Web/WebDriver/Reference/BiDi/Modules/network
         code: true

front-matter-config.json

@@ -376,6 +376,7 @@
                 "webdriver-command",
                 "webdriver-capability",
                 "webdriver-error",
+                "webdriver-event",
                 "reference"
               ]
             }