This reflects the _world_ of the MV3 scripting API:
https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/scripting/ExecutionWorld
MAIN: page's world
ISOLATED: extension's content script world
Some scriptlets are best executed in either world, so this
commit allows to pick in which world a scriptlet should execute
(default to MAIN).
For instance, the new sed.js scriptlet will now execute in
the ISOLATED world.
Related commit:
- 41876336db
The `tryCount` parameter has been removed.
The new default behavior of the sed.js scriptlet is to bail out
when the document itself has been fully loaded, i.e. when
DOMContentLoaded event is fired.
Two new parameters have been added to override the default quit out
behavior:
`stay, 1`
Use to force the scriptlet to stay at work forever.
`quitAfter, ms`
This tells the scriptlet to quit `ms` milliseconds after the
page has been loaded, i.e. after the DOMContentLoaded event has
been fired.
The mutation observer of the sed.js scriptlet can be a significant
overhead for pages with dynamically updated DOM, and in most cases
the scriptlet is useful only for DOM changes occurring before the
DOMContentLoaded event, so the default is to quit out when that
event is received ("quit out" means discarding the mutation observer
and having the scriptlet garbage-collected by the JS engine).
At the moment, the only filter lists deemed from a "trusted source"
are uBO-specific filter lists (i.e. "uBlock filters -- ..."), and
the user's own filters from "My filters".
A new scriptlet which can only be used by filter lists from trusted
sources has been introduced: `sed.js`.
The new `sed.js` scriptlet provides the ability to perform
text-level substitutions. Usage:
example.org##+js(sed, nodeName, pattern, replacement, ...)
`nodeName`
The name of the node for which the text content must be substituted.
Valid node names can be found at:
https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeName
`pattern`
A string or regex to find in the text content of the node as the target of
substitution.
`replacement`
The replacement text. Can be omitted if the goal is to delete the text which
matches the pattern. Cannot be omitted if extra pairs of parameters have to be
used (see below).
Optionally, extra pairs of parameters to modify the behavior of the scriptlet:
`condition, pattern`
A string or regex which must be found in the text content of the node
in order for the substitution to occur.
`sedCount, n`
This will cause the scriptlet to stop after n instances of substitution. Since
a mutation oberver is used by the scriptlet, it's advised to stop it whenever
it becomes pointless. Default to zero, which means the scriptlet never stops.
`tryCount, n`
This will cause the scriptlet to stop after n instances of mutation observer
run (regardless of whether a substitution occurred). Default to zero, which
means the scriptlet never stops.
`log, 1`
This will cause the scriptlet to output information at the console, useful as
a debugging tool for filter authors. The logging ability is supported only
in the dev build of uBO.
Examples of usage:
example.com##+js(sed, script, /devtoolsDetector\.launch\(\)\;/, , sedCount, 1)
example.com##+js(sed, #text, /^Advertisement$/)
Related issue:
- https://github.com/uBlockOrigin/uBlock-issues/issues/2618
Usage:
example.com##+js(spoof-css, selector, property-name, property-value, ...)
- selector: a valid CSS selector which matches the elements for which
the spoofing must apply.
- property-name: a CSS property name (can be dashed- or camel-cased)
- property-value: the value to return regardless of the currently
computed value.
There can be any number of property-name/property-value pairs, all
separated by commas.
A special property-name/property-value pair `debug/1` can be used
to force the browser to break when `getComputedStyle()` or
`getBoundingClientrect()` is called, useful to help pinpoint usage
of those calls in the page's source code:
example.com##+js(spoof-css, .ad, debug, 1)
Related issue:
- https://github.com/uBlockOrigin/uBlock-issues/issues/2615
Expand `set-constant`: 3rd parameter and beyond are tokens which
modify the behavior of `set-contant`. Valid tokens:
- `interactive`, `end`, `2`: set the constant when the event
`DOMContentInteractive` is fired.
- `complete`, `idle`, `3`: set the constant when the event
`load` is fired.
- `asFunction`: the constant will be a function returning the
specified value.
- `asCallback`: the constant will be a function returning a
function returning the specified value.
- `asResolved`: the constant will be a promise resolving to
the specified value.
- `asRejected`: the constant will be a promise failing with
the specified value.
Harden `no-setimeout-if` and `no-setinterval-if` as per feedback
from filter list maintainers.
As per discussion with filter list maintainers.
THis requires to use JSON notation for parameter passing:
- "runAt": "end" = execute scriptlet at `DOMContentLoaded` event
- "runAt": "idle" = execute scriptlet at `load` event
A new optional parameter has been added to `set-constant`
scriptlet: `runAt`, default to `0`.
..##+js(set, document.body.oncontextmenu, null, 2)
When the `runAt` parameter is present, uBO will take it into
account to possibly defer execution of `set-constant`:
- `runAt` not present: execute immediately
- `runAt` = 1: execute immediately
- `runAt` = 2: execute when document state is "interactive"
- `runAt` = 3: execute when document state is `"complete"
maintainers.
To enable logging, use the JSON approach to pass parameters to
`acs` scriptlet. Example:
..##+js(acs, { "target": "document.oncontextmenu", "log": true })
Whereas "target", "needle", and "context" correspond to their
respective positional argument. Using JSON form to pass parameters
allows to specify extra paramters to facilitate debugging of that
scriptlet:
- `"log": true` => output useful information at the dev console.
- `"debug": true` => break at key locations in the scriptlet.
The added logging/debugging capabilities work only in the dev build
of uBO or if the advanced setting `filterAuthorMode` is set to
`true`.
The scriptlet addEventListenerLogger has been removed.
The logging of addEventListener() calls can now be done with the
addEventListenerDefuser scriptlet, which now supports the
following named arguments:
"type": the event type to match. Default to '', i.e. match-all.
"pattern": the pattern to match against the handler argument
Default to '', i.e. match-all.
"log": an integer value telling when to log:
- 1: log only when both type and pattern matches, i.e. when a
call to addEventListener() is defused
- 2: log when either the type or pattern matches
- 3: log all calls to addEventListener()
"debug": an integer value telling when to break into the
debugger, useful to inspect the debugger's call stack.
- 1: break into the debugger when both type and pattern match,
so effectively when defusing is taking place.
- 2: break into the debugger when either type or pattern matches.
The usage of named arguments is optional, positional arguments
are still supported as documented. Named arguments is required
to use "log" and/or "debug" arguments.
Obviously, do not use "log" or "debug" in any filter list, these
are investigative tools for filter list authors.
Examples of usage using named arguments:
wikipedia.org##+js(aeld, { "type": "/mouse/", "pattern": "/.^/", "log": 2 })
Above filter will log calls to addEventListener() which have the
pattern "mouse" in the event type (so "mouseover", "mouseout",
etc.) without defusing any of them (because pattern can't match
anything).
wikipedia.org##+js(aeld, { "type": "/.^/", "log": 2 })
Above filter will log all calls without defusing any of them
(because type can't match anything)
wikipedia.org##+js(aeld, { "log": 1 })
Above filter will log and defuse all calls to addEventListener().
Builtin scriptlets are no longer parsed as text-based resources,
they are imported as JS functions, and `toString()` is used to
obtain text-based representation of a scriptlet.
Scriptlet parameters are now passed as function call arguments
rather than by replacing text-based occurrences of `{{i}}`. The
arguments are always string values (see below for exception).
Support for argument as Object has been added. This opens the
door to have scriptlets using named arguments rather than
positional arguments, and hence easier to extend functionality
of existing scriptlets. Example:
example.com##+js(scriplet, { "prop": "adblock", "value": false, "log": true })
Compatibility with user-provided scriptlets has been preserved.
User-provided scriptlets can benefit some of the changes:
Use the form `function(..){..}` instead of `(function(..){..})();`
in order to received scriptlet arguments as part of function call
-- instead of using `{{i}}`.
If using the form `function(..){..}`, you can choose to receive
an Object as argument -- just be sure that your scriptlet's
parameter is valid JSON notation.
The purpose is to prevent a call to an existing function from
throwing an exception. The exception will be caught by the
scriptlet and neutralized.
The first argument must be a reference to a function call. At
the moment, the function call must exist at the time the
scriptlet is called.
Related issue:
- https://github.com/uBlockOrigin/uBlock-issues/issues/2508
If the first argument is a regex with multine flag set, the
scriptlet will execute the regex against the whole text, and
remove matching text from the whole text.
If the matching text does not contains whole lines, the text
won't be removed, i.e. it is not allowed to remove only part
of a line.
Related issue:
- https://github.com/uBlockOrigin/uBlock-issues/issues/2531#issuecomment-1462389539
Usage:
- example.com##+js(href-sanitizer, a[href^="/go?to="]:not([title]))
- example.com##+js(href-sanitizer, a[href^="/go?to="][title], [title])
The second argument is the attribute from which to extract the text
to be used for the `href` attribute of the link. If the second
attribute is absent, the text content of the element will be used.
Related issue:
- https://github.com/uBlockOrigin/uBlock-issues/issues/2531
Usage:
example.com##+js(href-from-text, a[href^="/tracker-link?to="]
The above scriptlet will find all elements matching the selector
passed as 1st argument, and replace the `href` attribute with the
text content of the element, if all the following conditions are
met:
- The element is a link (`a`) element
- The link element has an existing `href` attribute
- The text content of the element is a valid `https`-based URL
Related issue:
- https://github.com/uBlockOrigin/uAssets/issues/14849
Arguments:
1. Required. The selector of elements which are to be removed.
Example: Period[id*="-roll-"][id*="-ad-"]
2. An optional selector that must have a match in the document
for the pruning to occur. No selector means the pruning can
be performed regardless.
3. An optional URL which must be a match for the pruning to
occur. If left blank, the pruning can be performed regardless.
Related discussion:
- https://github.com/uBlockOrigin/uBlock-issues/discussions/2270
If the argument to the window-close-if scriptlet is a regex, the
match will be against the whole location URL, otherwise the
match will be against the part+query part of the location URL.
Raymond Hill