extensions/common/api/content_scripts.webidl

// Copyright 2026 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

[ExternalExtensionType="extensionTypes.RunAt"]
typedef object ExtensionTypesRunAt;

[ExternalExtensionType="extensionTypes.ExecutionWorld"]
typedef object ExtensionTypesExecutionWorld;

// Describes a content script to be injected into a web page.
dictionary ContentScript {
  // Specifies which pages this content script will be injected into. See
  // <a href="develop/concepts/match-patterns">Match Patterns</a> for more
  // details on the syntax of these strings.
  required sequence<DOMString> matches;

  // Excludes pages that this content script would otherwise be injected into.
  // See <a href="develop/concepts/match-patterns">Match Patterns</a> for more
  // details on the syntax of these strings.
  sequence<DOMString> exclude_matches;

  // The list of CSS files to be injected into matching pages. These are
  // injected in the order they appear in this array, before any DOM is
  // constructed or displayed for the page.
  sequence<DOMString> css;

  // The list of JavaScript files to be injected into matching pages. These
  // are injected in the order they appear in this array.
  sequence<DOMString> js;

  // If specified true, it will 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 will not inject into child frames if the URL
  // requirements are not met. Defaults to false, meaning that only the top
  // frame is matched.
  boolean all_frames;

  // Whether the script should inject into any frames where the URL belongs to
  // a scheme that would never match a specified Match Pattern, including
  // about:, data:, blob:, and filesystem: schemes. In these cases, in order
  // to determine if the script should inject, the origin of the URL is
  // checked. If the origin is `null` (as is the case for data: URLs), then
  // the "initiator" or "creator" origin is used (i.e., the origin of the
  // frame that created or navigated this frame). Note that this may not
  // be the parent frame, if the frame was navigated by another frame in the
  // document hierarchy.
  boolean match_origin_as_fallback;

  // Whether the script should inject into an about:blank frame where the
  // parent or opener frame matches one of the patterns declared in matches.
  // Defaults to false.
  boolean match_about_blank;

  // Applied after matches to include only those URLs that also match this
  // glob. Intended to emulate the
  // <a href="http://wiki.greasespot.net/Metadata_Block#.40include">@include
  // </a> Greasemonkey keyword.
  sequence<DOMString> include_globs;

  // Applied after matches to exclude URLs that match this glob. Intended to
  // emulate the
  // <a href="https://wiki.greasespot.net/Metadata_Block#.40exclude">@exclude
  // </a> Greasemonkey keyword.
  sequence<DOMString> exclude_globs;

  // Specifies when JavaScript files are injected into the web page. The
  // preferred and default value is <code>document_idle</code>.
  ExtensionTypesRunAt run_at;

  // The JavaScript "world" to run the script in. Defaults to
  // <code>ISOLATED</code>. Only available in Manifest V3 extensions.
  ExtensionTypesExecutionWorld world;
};

// Stub namespace for the "content_scripts" manifest key.
[generate_error_messages, Namespace=contentScripts]
partial dictionary ExtensionManifest {
  sequence<ContentScript> content_scripts;
};