Add content scripts section in specification

specification/index.bs

@@ -7,6 +7,7 @@ Group: WECG
 URL: https://w3c.github.io/webextensions
 Editor: Mukul Purohit, Microsoft Corporation https://www.microsoft.com, [email protected]
 Editor: Tomislav Jovanovic, Mozilla https://www.mozilla.org/, [email protected]
+Editor: Oliver Dunk, Google https://www.google.com, [email protected]
 Abstract: [Placeholder] Abstract.
 Markup Shorthands: markdown yes
 </pre>
@@ -27,11 +28,11 @@ An optional directory containing strings as defined in <a href="#localization">l
 
 ### Other files
 
-An extension may also contain other files, such as those referenced in the <a href="#key-content_scripts">content_scripts</a> and <a href="#key-background">background</a> part of the <a href="#manifest">Manifest</a>.
+An extension may also contain other files, such as those referenced in the [[#key-content_scripts]] and [[#key-background]] part of the [=manifest=].
 
 ## Manifest
 
-A WebExtension must have a manifest file at its root directory.
+A WebExtension must have a <dfn>manifest</dfn> file at its root directory.
 
 ### Manifest file
 
@@ -112,7 +113,7 @@ This key may be present.
 
 #### Key `content_scripts`
 
-This key may be present.
+The <a href="#key-content_scripts">`content_scripts`</a> key is a [=list=] of items representing [=content scripts=] that should be registered.
 
 #### Key `content_security_policy`
 
@@ -154,6 +155,8 @@ Filenames beginning with an underscore (`_`) are reserved for use by user agent.
 
 ## Isolated worlds
 
+<dfn>Worlds</dfn> are isolated JavaScript contexts with access to the same underlying DOM tree but their own set of wrappers around those DOM objects.
+
 ## Unavailable APIs
 
 ## The `browser` global
@@ -172,6 +175,12 @@ Issue(62): Specify localization handling.
 
 ## Match patterns
 
+A <dfn>match pattern</dfn> is a pattern used to match URLs.
+
+## Globs
+
+A <dfn>glob</dfn> can be any [=string=]. It can contain any number of wildcards where * can match zero or more characters and ? matches exactly one character.
+
 ## Concepts
 
 ### Uniqueness of extension IDs
@@ -190,7 +199,70 @@ Issue(62): Specify localization handling.
 
 ### Content scripts
 
-#### Isolated worlds
+<dfn>Content scripts</dfn> represent a set of JS and CSS files that should be injected into pages loaded by the user agent.
+
+#### Key `matches`
+
+A [=list=] of [=match patterns=] that are used to decide where the content script runs. This key is required.
+
+#### Key `exclude_matches`
+
+A [=list=] of [=match patterns=] that should be used to exclude URLs from where the content script runs.
+
+#### Key `js`
+
+A [=list=] of file paths that should be injected as scripts.
+
+#### Key `css`
+
+A [=list=] of file paths that should be injected as stylesheets.
+
+#### Key `all_frames`
+
+If `all_frames` is true, the content script must be injected into subframes. Defaults to false.
+
+#### Key `match_about_blank`
+
+If this is `true`, the content script will also be injected into an additional user agent specified set of pages used to represent empty frames. This will only happen if the content script matches the page that embedded the frame. Defaults to `false`.
+
+#### Key `match_origin_as_fallback`
+
+Used to match frames with an opaque or otherwise missing origin. The origin to match against is determined in the following order of priority:
+
+1. If the frame has an [=opaque origin=], such as with a [=blob URLs=], use the non-opaque origin.
+1. If available, use the origin of the parent frame.
+1. Otherwise, no origin is found and this frame can never be matched.
+
+#### Key `run_at`
+
+Specifies when the content script should be injected. Valid values are `document_start`, `document_end` and `document_idle`.
+
+#### Key `include_globs`
+
+A list of [=globs=] that a page should match in addition to matches.
+
+#### Key `exclude_globs`
+
+A list of [=globs=] that should be used to exclude URLs from where the content script runs.
+
+#### Key `world`
+
+The [=world=] any JavaScript scripts should be injected into. Defaults to `ISOLATED`. Valid values are `MAIN` and `ISOLATED`.
+
+#### Injecting a content script
+
+Issue: If the same extension specifies the same script twice, what should happen? ([bug](https://crbug.com/324096753))
+
+Issue: The below algorithm needs to be updated to include `match_about_blank` and `match_origin_as_fallback`.
+
+To determine if a content script should be injected in a frame:
+
+1. If the extension does not have access to the origin, return.
+1. If the origin is not included in `matches`, return.
+1. If `include_globs` is present and the origin is not matched, return.
+1. If the origin matches an entry in `exclude_matches` or `exclude_globs`, return.
+1. If this is a frame, and `all_frames` is not `true`, return.
+1. Otherwise, inject the content script. This should be done based on the `run_at` setting.
 
 ### Extension pages