Can we link to run_at rather than include possible values here? Having it inline is both more info for the reader to parse and more content to maintain should the potential values change.

As a reader, I find the current framing a little confusing. The first sentence in this section starts by talking about the order in which "matching key objects are processed," but it's not immediately clear to me why that matters.

It feels like the current copy is too focused on the implementation details of parsing an array of objects rather than the thing I want to understand as a developer: what (if any) guarantees are there about the order in which my content scripts will be added to (and executed on) a web page.

For the moment, I think just adding an intro statement would help clarify this content. For example:

Files declared in content scripts are injected into web pages in a well defined order. When a webpage loads, matching key objects are processed in this order:

Longer term, I think we should consider moving this to the content scripts page and building it out to cover both the static content scripts definitions from this page and the dynamic content scripts declrations from the runtime API.

I really like helping concertize this information with a grounded example. I think we can improve on this explanation, though, by adding notes about things like when the website's own scripts run, when DOM events occur (e.g. DOMContentLoaded), and referencing which content script object is being processed at a given moment.

Suggested edit to address my feedback at https://github.com/mdn/content/pull/39298/files#r2075072868

@Rob--W I'm unclear how this could help the reader: they are now presented with two slightly different statements of the processing order. And, as I commented previously, this statement doesn't include what I understood to be the whole reason for the change, i.e., the statement about the object ordering the key array.

@Rob--W I'm unclear how this could help the reader: they are now presented with two slightly different statements of the processing order.

I think that a concise one-sentence frame helps the reader with putting your following explanation in the right context. The list of steps below could result in the appearance that there is some complex rule (that the reader must brace for), while the rule is relatively simple: run_at, and then the order as given. If someone already understands this one sentence rule, they don't need to read the rest.

And, as I commented previously, this statement doesn't include what I understood to be the whole reason for the change, i.e., the statement about the object ordering the key array.

Your fuller explanation covers that. The sentence here is mainly to get the rule of thumb. And as phrased, it could also include the order of js/css arrays across all objects (but it could also mean just within the object). It is not needed to make the sentence longer to address that ambiguity.

@Rob--W For clarity, we should state the rule only once.

I'd be fine with stating the rule only once. Can we choose a phrasing that fits more naturally with how it actually works? The current text below describes some ordering, without the time aspect of run_at (they are evaluated separately at different times!). The mentions of "each object", "object", "key value" and "each object" again is getting me confused, requiring me to think what exactly it is referring to.

Here is an example of text that conveys the concepts more naturally, at least to me.

At each point in time specified by `run_at`
(first `document_start`, then`document_end`, and finally `document_idle`),
the registered objects in `content_scripts` are run as follows:

- In the order as specified in the `content_scripts` array,
  for each object with the matching `run_at` value:
  - CSS is applied in the order as specified in its `css` array, if any.
  - JavaScript code is executed in the order as specified in its `js` array, if any.

@Rob--W a slight irony here in that my original draft included detailing the sequence of run_at directives, but @dotproto suggested removing them to avoid duplication and redundancy. Please check out my update.

For reference, here's my comment. At the time I just read it as a list of possible run_at values, not as commentary about their execution order. That was an oversight on my part.

May I suggest putting jquery.js back in the original list of two scripts, and use run-first.js here? jquery can be viewed as a dependency of the other scripts, and if they are indeed dependent, then it makes much more sense to put them in the same declaration.

Something called "run-first.js" already conveys from its name what it is supposed to do.

I'd be fine with stating the rule only once. Can we choose a phrasing that fits more naturally with how it actually works? The current text below describes some ordering, without the time aspect of run_at (they are evaluated separately at different times!). The mentions of "each object", "object", "key value" and "each object" again is getting me confused, requiring me to think what exactly it is referring to.

Here is an example of text that conveys the concepts more naturally, at least to me.

At each point in time specified by `run_at`
(first `document_start`, then`document_end`, and finally `document_idle`),
the registered objects in `content_scripts` are run as follows:

- In the order as specified in the `content_scripts` array,
  for each object with the matching `run_at` value:
  - CSS is applied in the order as specified in its `css` array, if any.
  - JavaScript code is executed in the order as specified in its `js` array, if any.