Request immediate injection of manifest script registered with `document_idle`

fregante commented 2 months ago

Context

I have a content script registered on *://*/* and run_at: document_idle.
I also use the Commands API to run scripts via keyboard shortcuts, context menus, browser action clicks, etc

Problem

On larger websites, like nytimes.com, the page (and therefore the content script) takes several seconds to load. This is fine with regular usage, but if the user activates the extension, the content script cannot respond (or even receive messages) until the browser loads it.

I could use the Scripting API to manually inject it, but the browser will follow it with its own injection, or maybe cause race conditions.

Possible solutions

add a manifest key to enable immediate injection (e.g. run_on_active_tab: true)
add a method to request a specific content script to be injected immediately, without duplicating the native injection (e.g. scripting.ensureScript(3), where the number is the index in the manifest)

fregante commented 2 months ago

I'm also interested in the idea of exposing a runtime API to let extensions request injection of a given content script, but I'm a bit uncomfortable with the suggestion that we do so based on content script declaration indices. First, this approach only works with content scripts declared in the extensions manifest; runtime declarations via scripting.registerContentScripts() or scripting.updateContentScripts() wouldn't be accessible with this approach. Second, while array indices are static for content scripts declared int he manifest, they are more difficult to reason about than a unique identifier. I expect that this approach would lead to subtle bugs and it would make extension source more difficult for both extension developers and reviewers to reason about.

I think a better approach would be to add an id field to the content script declaration object. A unique identifier could be used by both statically and dynamically declared content scripts, be easier for developers to reason about, be less likely to result in unexpected bugs when changing only a manifest, be more predictable and easier to work with in situations where the manifest is generated at build time.

// manifest.json
{
  "content_scripts": [{
    "id": "main",
    "matches": ["*://*.example.com/*"],
    "scripts": ["content.js"],
    "run_at": "document_idle"
  }]
}

// background.js
browser.action.onClicked.addListener((tab) => {
  scripting.executeScript({
    target: { tab: tabId },
    scriptId: "main"
    // "files" and "func" omitted because the appropriate value would be reused
    // by from the "main" content script's declaration.
  });
});

I'm also concerned that introducing a document_idle_or_extension_invoked value for run_at would set a president of combining existing phases with _or_extension_invoked which could lead to a combinatorial explosion if we expand the set of supported lifecycle injection points or new methods of triggering script injection.

One way to combat this is to allow run_at to accept an array of lifecycle phases (for example, "run_at": ["document_idle", "extension_invoked"]). That said, I'm somewhat hesitant about this approach because it only seems useful in combination with extension_invoked. Other potential uses of this array feel like footguns; for example, what would the expected behavior of "run_at": ["document_idle", "document_start"] be? Inject at each distinct phase? Only inject on the first? The browser errors on manifest parse because that declaration doesn't make senes? IMO the design of the API should try to discourage usage patterns that we don't expect or want.

Rob--W commented 1 month ago

This topic was discussed in today's meeting (meeting notes pending review before merging in #608).

This specific part of the proposal was discussed in more detail:

add a method to request a specific content script to be injected immediately, without duplicating the native injection (e.g. scripting.ensureScript(3), where the number is the index in the manifest)

I expressed concerns over this capability in isolation, because the currently expected behavior is for the script to execute whenever the API is called. This could be countered by introducing a way for extension authors to explicitly signal that a content script should run once per page. If that capability were to exist, then it can be combined with the existing executeImmediately flag of the scripting.executeScript API to execute immediately.

FYI: In Firefox, there is currently no deduplication of already-injected scripts. In Chrome, content scripts are currently run only once even when specified multiple times. This is even the case if the scripts target different worlds, which someone reported before at https://issues.chromium.org/issues/324096753 ("Shared content script in different worlds conflicts with each other")

w3c / webextensions