1428398 - Document insertCSS interaction with page styles

Status: RESOLVED FIXED

(WebExtensions :: General, defect, P5)

Description

[Yuri Khan]

User Agent: Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:58.0) Gecko/20100101 Firefox/58.0
Build ID: 20171228162026

Steps to reproduce:

1. Attempt to convince Stylus developers to use insertCSS instead of inserting a <style> element into the page DOM.

https://github.com/openstyles/stylus/issues/248


Actual results:

Developers ask about guarantees that styles injected via insertCSS({cssOrigin: 'author'}) will win in the cascading order against page-specified styles, all other things being equal (i.e. origin, importance, and specificity).

https://github.com/openstyles/stylus/issues/248#issuecomment-355580985


Expected results:

It should be evident from the insertCSS documentation whether that is or is not the case.

https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/tabs/insertCSS

Currently, it is only evident that !important styles injected as {cssOrigin: 'user'} will win against page-specified !important styles. That is not sufficient for style injector extension developers because non-!important user styles lose to non-!important author styles.

A typical use case for style injector extension users is to identify a page-specified CSS rule giving an undesirable effect, and create a custom rule with the same selector and importance. The expectation is that such a rule will override the page-specified style.

An acceptable solution would be to add something like this to the description of the cssOrigin property:

    Rules added as "author" stylesheets behave as if they appeared
    after all author rules specified by the web page, including any
    author stylesheets added dynamically by the page’s scripts,
    even if that happens later than the insertCSS call completes.

Comment 1

[Tomislav Jovanovic :zombie]

It looks clear from current docs.
https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/insertCSS

Comment 2

[Yuri Khan]

I’m sorry but I don’t see any guarantee about author styles in the current docs.

Comment 3

[Tomislav Jovanovic :zombie]

I apologize, I misunderstood the description from the first comment.

Can you please describe a use case not covered by specifying rules from a "user" origin with !important keyword?

I'm not sure we can easily provide a guarantee that extension-inserted "author" stylesheets will behave as you ask, just like rules from extensions injecting <style> elements into the DOM will not override any "author stylesheets added dynamically by the page’s scripts, [even] if that happens later than the insertCSS call completes."

Comment 4

[Yuri Khan]

The use case is the whole Stylish/Stylus community and the way they operate. It was briefly described in this paragraph:

A typical use case for style injector extension users is to identify a page-specified CSS rule giving an undesirable effect, and create a custom rule with the same selector and importance. The expectation is that such a rule will override the page-specified style.

To be more specific, here is the process I use; I expect that many custom style makers work similarly:

• I am interacting with some web site or web application, and I am annoyed by some small detail. (The exact nature of annoyance is not important. Perhaps it uses a downloadable font that has no coverage for Cyrillics so mixed Russian/English text looks wacky. Or a rarely-used button on the periphery is painted bright “click me” green, distracting me from work. Or a text input field specifies dark gray text color which is invisible in my dark GTK theme.)

• I fire up the Inspector on the offending element, and look at the site’s style rules that are likely to be causing the issue. I briefly play with them in the Inspector to arrive at a solution that looks satisfactory to me.

• I create a custom style in my styling extension of choice. This opens a new tab with a CSS editor. I fill out the style name, e.g. “GitLab: Dim New Repo button”; and the URL domain it will apply to.

• I switch to the tab containing the site and copy the CSS selector from the rule I want to override. I paste that into the custom style editor, add { } and write my customization inside the braces.

• Then I save the custom style and reload the offending page. The custom style kicks in and neutralizes the annoyance.

I do this privately, but thousands of users are sharing their customizations. There is an existing body of custom styles, which are mostly written in assumption that they will be injected as author styles, very far down the document order, so, according to the CSS cascading rules, at equal origin, importance, and specificity, they win against the site’s rules by virtue of coming later.

Injecting custom styles as user styles is not done in practice, except in very special circumstances, because normal user styles have lower priority than normal author styles. Since normal styles make up the vast majority of styles in the wild, a user would have to modify the selectors so as to either make them !important or give them higher specificity, and ain’t nobody got time for that.

In my experience, normal custom styles injected with insertCSS at “author” origin consistently win against normal site styles; and !important custom styles injected the same way also consistently win against !important site styles, all other things being equal.

I have also built a small example where the site adds a <style> element very late (after a button click) at the bottom of its <body>.

Steps to reproduce:

• Open the above fiddle. Observe that the background is red, as specified in the site’s initial CSS.
• Click the button. Observe that the background is now #c0ffee, as specified in the site’s added style.
• Build and load an extension that fires on pages with urls in the fiddle.jshell.net domain and injects body { background: blue } with insertCSS as an author style.
• Reload the fiddle. Observe that the background is blue, as injected by the extension.
• Click the button. Observe that the background is still blue, despite the site having added a rule.

So: The actual behavior of Firefox is exactly the desired one. What I’m asking (on behalf of custom style makers and users) is that it be explicitly documented and preserved.

Comment 5

[Tomislav Jovanovic :zombie]

Thank you for a detailed explanation, that does sound reasonable, and I confirmed we already insert these as "additional" stylesheets, so this bug would just need a test to make sure we don't break it.

Comment 6

[Richard Bloor]

Added explanation of "author" stylesheets behavior to cssOrigin. Let me know if further changes are needed or this can be marked dev-doc-complete.

Comment 7

[Yuri Khan]

Nice. I think there’s a small typo:

-This behavior including any author stylesheets
+This behavior includes any author stylesheets

Comment 8

[Tomislav Jovanovic :zombie]

It doesn't look like "user" and "author" list items ended up in the right place?

Comment 9

[Richard Bloor]

Thanks Tom, typo fixed and bullets moved to the correct place on page.

Comment 10

[Rob Wu [:robwu]]

(In reply to Tomislav Jovanovic :zombie from comment #5)

Thank you for a detailed explanation, that does sound reasonable, and I confirmed we already insert these as "additional" stylesheets, so this bug would just need a test to make sure we don't break it.

Test cases have been added as part of bug 1736579, specifically:

• https://searchfox.org/mozilla-central/rev/76b13c585e575cf273fd05ab3b48a1532c1d1faa/toolkit/components/extensions/test/mochitest/test_ext_scripting_insertCSS.html#262-279
• https://searchfox.org/mozilla-central/rev/76b13c585e575cf273fd05ab3b48a1532c1d1faa/toolkit/components/extensions/test/mochitest/test_ext_scripting_insertCSS.html#262-279

Note: insertCSS is prone to timing issues. Declarative content scripts (styles) are a better way to minimize disruptive style changes. That is tracked at bug 1679997.