recursal/MDN huggingface dataset:
action.setPopup()
=================

Sets the HTML document that is opened as a popup when the user clicks on the browser action's icon. Tabs without a specific popup will inherit the global popup, which defaults to the `default_popup` specified in the manifest.

**Note:** This API is available in Manifest V3 or higher.

Syntax
------


```js
browser.action.setPopup(
  details // object
)
```

### Parameters

`details`

An object with the following properties:

`tabId` Optional

`integer`. Sets the popup only for a specific tab. The popup is reset when the user navigates this tab to a new page.

`windowId` Optional

`integer`. Sets the popup only for the specified window.

`popup`

`string` or `null`. The HTML file to show in a popup, specified as a URL.

This can point to a file packaged within the extension (for example, created using `extension.getURL`), or a remote document (e.g. `https://example.org/`).

If an empty string (`""`) is passed here, the popup is disabled, and the extension will receive `action.onClicked` events.

If `popup` is `null`:

* If `tabId` is specified, removes the tab-specific popup so that the tab inherits the global popup.
* If `windowId` is specified, removes the window-specific popup so that the window inherits the global popup.
* If `tabId` and `windowId` are both omitted, reverts the global popup to the default value.



* If `windowId` and `tabId` are both supplied, the function fails and the popup is not set.
* If `windowId` and `tabId` are both omitted, the global popup is set.
Examples
--------

This code adds a pair of context menu items that you can use to switch between two popups. Note that you'll need the "contextMenus" permission set in the extension's manifest to create context menu items.


```js
function onCreated() {
  if (browser.runtime.lastError) {
    console.log("error creating item:", browser.runtime.lastError);
  } else {
    console.log("item created successfully");
  }
}

browser.contextMenus.create(
  {
    id: "popup-1",
    type: "radio",
    title: "Popup 1",
    contexts: ["all"],
    checked: true,
  },
  onCreated,
);

browser.contextMenus.create(
  {
    id: "popup-2",
    type: "radio",
    title: "Popup 2",
    contexts: ["all"],
    checked: false,
  },
  onCreated,
);

browser.contextMenus.onClicked.addListener((info, tab) => {
  if (info.menuItemId === "popup-1") {
    browser.action.setPopup({ popup: "/popup/popup1.html" });
  } else if (info.menuItemId === "popup-2") {
    browser.action.setPopup({ popup: "/popup/popup2.html" });
  }
});
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.action` API. This documentation is derived from `browser_action.json` in the Chromium code.
dom.openOrClosedShadowRoot()
============================

Gets the open shadow root or the closed shadow root hosted by the specified element. If the shadow root isn't attached to the element, it will return `null`.

**Note:** In Firefox, the equivalent property is `element.openOrClosedShadowRoot`. This read-only property represents the shadow root hosted by the element, regardless of whether its `mode` is `open` or `closed`.

Use `Element.attachShadow()` to add a shadow root to an element.

Syntax
------


```js
let shadowRoot = browser.dom.openOrClosedShadowRoot(
  element,    // HTMLElement
)
```

### Parameters

`element`

`HTMLElement`. The host element.

### Return value

 A `ShadowRoot` object instance, regardless of whether its
 `mode` is set to `open` or
 `closed`, or `null` if no shadow root is present.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `Element.shadowRoot`
* `chrome.dom.openOrClosedShadowRoot`
scripting.ExecutionWorld
========================

 Specifies the execution environment of a script injected with `scripting.executeScript()`
 or registered with `scripting.registerContentScripts()`.

Type
----

Values of this type are strings. Possible values are:

* `ISOLATED`
 The default execution environment of content scripts.
 This environment is isolated from the page's context: while they share the same document, the global scopes and available APIs differ.
* `MAIN`
 The execution environment of the web page. This environment is shared with the web page, without isolation.
 Scripts in this environment do not have any access to APIs that are only available to content scripts.


**Warning:** Due to the lack of isolation, the web page can detect the executed code and interfere with it.
 Do not use the `MAIN` world unless it is acceptable for web pages to read, access, or modify the logic or data that flows through the executed code.
 `MAIN` is not supported in Firefox (although it is planned and the work to introduce it is tracked by Bug 1736575). In the meantime, JavaScript code running in the isolated content script sandbox can use the Firefox "Xray vision" feature, as described in Share objects with page scripts.
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.scripting` API.
scripting.removeCSS()
=====================

Removes a CSS stylesheet injected by a call to `scripting.insertCSS()`.

**Note:** This method is available in Manifest V3 or higher in Chrome and Firefox 101. In Safari and Firefox 102+, this method is also available in Manifest V2.

To use this API you must have the `"scripting"` permission and permission for the page's URL, either explicitly as a host permission or using the activeTab permission.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
await browser.scripting.removeCSS(
  details       // object
)
```

### Parameters

`details`

An object describing the CSS to remove and where to remove it from. It contains the following properties:

`css` Optional

`string`. A string containing the CSS to inject. Either `css` or `files` must be specified and must match the stylesheet inserted through `scripting.insertCSS()`.

`files` Optional

`array` of `string`. The path of a CSS files to inject, relative to the extension's root directory. Either `files` or `css` must be specified and must match the stylesheet inserted through `scripting.insertCSS()`.

`origin` Optional

`string`. The style origin for the injection, either `USER` or `AUTHOR`. Defaults to `AUTHOR`. Must match the origin of the stylesheet inserted through `scripting.insertCSS()`.

`target`

`scripting.InjectionTarget`. Details specifying the target to remove the CSS from.


### Return value

A `Promise` that fulfills with no arguments when all the CSS is removed. If any error occurs, the promise is rejected. Attempts to remove non-existent stylesheets are ignored.

Examples
--------

This example adds some CSS using `scripting.insertCSS`, then removes it again when the user clicks a browser action:


```js
// Assuming some style has been injected previously with the following code:
//
// await browser.scripting.insertCSS({
// target: {
// tabId: tab.id,
// },
// css: "\* { background: #c0ffee }",
// });
//
// We can remove it when a user clicked an extension button like this:
browser.action.onClicked.addListener(async (tab) => {
  try {
    await browser.scripting.removeCSS({
      target: {
        tabId: tab.id,
      },
      css: "\* { background: #c0ffee }",
    });
  } catch (err) {
    console.error(`failed to remove CSS: ${err}`);
  }
});
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.scripting` API.
scripting.updateContentScripts()
================================

Updates registered content scripts. If there are errors during script parsing and file validation, or if the IDs specified do not exist, no scripts are updated.

**Note:** This method is available in Manifest V3 or higher in Chrome and Firefox 101. In Firefox 102+, this method is also available in Manifest V2.

To use this API you must have the `"scripting"` permission and permission for the page's URL, either explicitly as a host permission or using the activeTab permission.

This is an asynchronous function that returns a `Promise`.

### Syntax


```js
await browser.scripting.updateContentScripts(
  scripts         // object
)
```

### Parameters

`scripts`

`array` of `scripting.RegisteredContentScript`. Details of a script to update. All the properties are optional except for `id`.

### Return value

A `Promise` that fulfills with an array of `scripting.RegisteredContentScript`. If any error occurs, the promise is rejected.

Examples
--------

This example updates a content script registered with ID `a-script` by setting `allFrames` to `true`:


```js
try {
  await browser.scripting.registerContentScripts([
    {
      id: "a-script",
      js: ["script.js"],
      matches: ["\*://example.org/\*"],
    },
  ]);

  // Update content script registered before to allow execution
  // in all frames:
  await browser.scripting.updateContentScripts([
    {
      id: "a-script",
      allFrames: true,
    },
  ]);
} catch (err) {
  console.error(`failed to register or update content scripts: ${err}`);
}
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.scripting` API.
scripting.registerContentScripts()
==================================

Registers one or more content scripts.

**Note:** This method is available in Manifest V3 or higher in Chrome and Firefox 101. In Firefox 102+, this method is also available in Manifest V2.

To use this API you must have the `"scripting"` permission and permission for the page's URL, either explicitly as a host permission or using the activeTab permission.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
await browser.scripting.registerContentScripts(
  scripts         // array
)
```

### Parameters

`scripts`

`array` of `scripting.RegisteredContentScript`. A list of scripts to register.

### Return value

A `Promise` that fulfills with an array of `scripting.RegisteredContentScript`. If there are errors during script parsing and file validation, or if the IDs specified do not exist, no scripts are registered and the promise is rejected.

Examples
--------

This example registers a content script that injects the file `"script.js"`:


```js
const aScript = {
  id: "a-script",
  js: ["script.js"],
  matches: ["https://example.com/\*"],
};

try {
  await browser.scripting.registerContentScripts([aScript]);
} catch (err) {
  console.error(`failed to register content scripts: ${err}`);
}
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.scripting` API.
scripting.ContentScriptFilter
=============================

This object contains a list of IDs of scripts to retrieve with `scripting.getRegisteredContentScripts()` or to unregister with `scripting.unregisterContentScripts()`.

Type
----

Values of this type are objects. They contain these properties:

`ids`

`array` of `string`. Array of scripts IDs.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.scripting` API.
scripting.RegisteredContentScript
=================================

This object contains details of a script to be registered or that is registered.

Type
----

Values of this type are objects. They contain these properties:

`allFrames` Optional

`boolean`. If specified `true`, the script is inject into all frames, even if the frame is not the top-most frame in the tab. Each frame is checked independently for URL requirements; it does not inject into child frames if the URL requirements are not met. Defaults to `false`, meaning that only the top frame is matched.

`css` Optional

`array` of `string`. The list of CSS files to be injected into matching pages. These are injected in the order they appear in this array.

`excludeMatches` Optional

`array` of `string`. Array of pages that this content script is excluded from but would otherwise be injected into.

`id`

`string`. The ID of the content script, specified in the API call.

`js` Optional

`array` of `string`. Array of path to JavaScript files in the extension package to inject into matching pages. Scripts are injected in the order they appear in this array.

`matches` Optional

`array` of `string`. Array of the pages this content script is injected into. Must be specified for `scripting.registerContentScripts()`.

`persistAcrossSessions` Optional

`boolean`. Specifies if this content script persists across browser restarts and updates and extension restarts. Defaults to `true`.

`runAt` Optional

`extensionTypes.RunAt`. Specifies when JavaScript files are injected into the web page. The default value is `document_idle`. In Firefox, `runAt` also affects the point where the CSS is inserted. In Chrome, `runAt` does not affect the CSS insertion point.

`world` Optional

`scripting.ExecutionWorld`. The execution environment for a script to execute in. The default value is `ISOLATED`.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.scripting` API.
scripting.InjectionTarget
=========================

This object contains details specifying the injection target for CSS and JavaScript. Its used in `scripting.executeScript()`, `scripting.insertCSS()`, and `scripting.removeCSS()`.

Type
----

Values of this type are objects. They contain these properties:

`allFrames` Optional

`boolean`. Whether the script or CSS is injected into all frames within the tab. Defaults to `false`. Cannot be `true` if `frameIds` is specified.

`frameIds` Optional

`array` of `number`. Array of the IDs of the frames to inject into.

`tabId`

`number`. The ID of the tab to inject into.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.scripting` API.
scripting.unregisterContentScripts()
====================================

Unregisters one or more content scripts.

**Note:** This method is available in Manifest V3 or higher in Chrome and Firefox 101. In Firefox 102+, this method is also available in Manifest V2.

To use this API you must have the `"scripting"` permission and permission for the page's URL, either explicitly as a host permission or using the activeTab permission.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
await browser.scripting.unregisterContentScripts(
  scripts         // object
)
```

### Parameters

`scripts` Optional

`scripting.ContentScriptFilter`. A filter to identify the dynamic content scripts to unregistered. If not specified, all dynamic content scripts are unregistered.

### Return value

A `Promise` that fulfills with no arguments when all the scripts are unregistered. If any error occurs, the promise is rejected.

Examples
--------

This example unregisters a registered content script with ID `a-script`:


```js
try {
  await browser.scripting.unregisterContentScripts({
    ids: ["a-script"],
  });
} catch (err) {
  console.error(`failed to unregister content scripts: ${err}`);
}
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.scripting` API.
scripting.getRegisteredContentScripts()
=======================================

Returns all the content scripts registered with `scripting.registerContentScripts()` or a subset of the registered scripts when using a filter.

**Note:** This method is available in Manifest V3 or higher in Chrome and Firefox 101. In Firefox 102+, this method is also available in Manifest V2.

To use this API you must have the `"scripting"` permission and permission for the page's URL, either explicitly as a host permission or using the activeTab permission.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let scripts = await browser.scripting.getRegisteredContentScripts(
  filter          // object
)
```

### Parameters

`filter` Optional

`scripting.ContentScriptFilter`. A filter for the registered script details to return.

### Return value

A `Promise` that fulfills with an array of `scripting.RegisteredContentScript`. If any error occurs, the promise is rejected.

Examples
--------

This example returns all the registered content scripts:


```js
// Register two content scripts.
await browser.scripting.registerContentScripts([
  {
    id: "script-1",
    js: ["script-1.js"],
    matches: ["\*://example.com/\*"],
  },
  {
    id: "script-2",
    js: ["script-2.js"],
    matches: ["\*://example.com/\*"],
  },
]);

// Retrieve all content scripts.
let scripts = await browser.scripting.getRegisteredContentScripts();
console.log(scripts.map((script) => script.id)); // ["script-1", "script-2"]

// Only retrieve the second script.
scripts = await browser.scripting.getRegisteredContentScripts({
  ids: ["script-2"],
});
console.log(scripts.map((script) => script.id)); // ["script-2"]
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.scripting` API.
UserScripts.UserScriptOptions
=============================

The UserScriptOptions object represents the content scripts to register. It has similar syntax to the contentScript options supported by browser.contentScripts.register. The differences are:

* it does not support a CSS property (use browser.contentScripts.register to dynamically register/unregister stylesheets)
* It does support an optional scriptMetadata property (as a plain JSON object which contains some metadata properties associated to the registered userScripts)

The UserScriptOptions object has the following properties:

`allFrames` Optional

Same as `all_frames` in the `content_scripts` key.

`excludeGlobs` Optional

Same as `exclude_globs` in the `content_scripts` key.

`excludeMatches` Optional

Same as `exclude_matches` in the `content_scripts` key.

`includeGlobs` Optional

Same as `include_globs` in the `content_scripts` key.

`js` Optional

An array of objects. Each object has either a property named `file`, which is a URL starting at the extension's manifest.json and pointing to a JavaScript file to register, or a property named `code`, which is some JavaScript code to register.

`matchAboutBlank` Optional

Same as `match_about_blank` in the `content_scripts` key.

`matches`

Same as `matches` in the `content_scripts` key.

`runAt` Optional

Same as `run_at` in the `content_scripts` key.

`scriptMetadata` Optional

A user script metadata value

It has similar syntax to the contentScript options supported by browser.contentScripts.register.
userScripts.RegisteredUserScript
================================

A `RegisteredUserScript` object is returned by a call to `userScripts.register()` and represents the user scripts registered in that call.

The object defines a single method, `unregister()`, which is used to unregister the user scripts.

**Note:** If this object is destroyed (for example because it goes out of scope) then the associated scripts will be unregistered automatically, so you should keep a reference to this object for as long as you want the user scripts to stay registered.

Methods
-------

`unregister()`

Unregisters the user scripts represented by this object.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
RegisteredUserScript.unregister()
=================================

The `unregister()` method of the `RegisteredUserScript` object unregisters the user scripts represented by the object, user scripts that were registered using `userScripts.register()`.

**Note:** User Scripts are automatically unregistered when the related extension page (from which the user scripts were registered) is unloaded, so you should register a user script from an extension page that persists at least as long as you want the user scripts to stay registered.

Syntax
------


```js
const registeredUserScript = await browser.userScripts.register(
  userScriptOptions       // object
);
// …
await registeredUserScript.unregister()
```

### Parameters

None.

### Return value

A `Promise` that is resolved once the user scripts are unregistered. The promise does not return a value.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `userScripts.register()`
* `RegisteredUserScript`
clipboard.setImageData()
========================

Copies an image to the clipboard. The image is re-encoded before it is written to the clipboard. If the image is invalid, the clipboard is not modified.

The image is provided as an `ArrayBuffer` containing the encoded image. JPEG and PNG formats are supported.

Although this API is based on Chrome's `clipboard.setImageData()` API, there are some differences:

* The Chrome API is only for apps, not extensions.
* This API requires only the `"clipboardWrite"` permission, while the Chrome version also requires the `"clipboard"` permission.
* Chrome's API uses callbacks, and this API only supports promises.
* This API does not support the `additionalItems` parameter.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
browser.clipboard.setImageData(imageData, imageType)
```

### Parameters

`imageData`

An `ArrayBuffer` containing the encoded image data to copy to the clipboard.

`imageType`

A string indicating the type of image contained in `imageData`: `"png"` or `"jpeg"`.

### Return value

A `Promise` that will be resolved with no arguments if the operation succeeded, or rejected if there was an error (for example, because the data did not represent a valid image).

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Copy a remote image:


```js
// requires:
// \* the host permission for "https://cdn.mdn.mozilla.net/\*"
// \* the API permission "clipboardWrite"

fetch("https://cdn.mdn.mozilla.net/static/img/favicon144.png")
  .then((response) => response.arrayBuffer())
  .then((buffer) => browser.clipboard.setImageData(buffer, "png"));
```


Copy an image that was bundled with the extension:


```js
// requires the API permission "clipboardWrite"

fetch(browser.runtime.getURL("image.png"))
  .then((response) => response.arrayBuffer())
  .then((buffer) => browser.clipboard.setImageData(buffer, "png"));
```


**Note:** This API is based on Chromium's `chrome.clipboard` API.