Skip to content

Latest commit

 

History

History
527 lines (357 loc) · 112 KB

USER_GUIDE.md

File metadata and controls

527 lines (357 loc) · 112 KB

Module Engine user guide

For installation, see the project README. This guide covers the current controls, userscript subset, filtering behavior and permissions.

Backup & restore

Open Backup & restore in the side menu and choose Download backup. Keep the downloaded JSON file to restore this profile or move your setup to another supported browser.

The backup includes protection switches and filter-layer choices, custom request/hiding filters, every configured domain list, appearance and website-theme exceptions, script update preferences, and the saved script library with source, order, tags, source URLs, GM values and prepared dependency bytes. The file is unencrypted; script values can contain private information. Nothing is uploaded.

To restore:

  1. Download a backup of the current browser first if you want to keep its setup.
  2. Choose a Module Engine JSON backup (up to 8 MiB). The page validates it and shows the current and incoming counts and script names without saving or executing anything.
  3. Review the replacement, acknowledge it, then choose Replace and restore. Cancel leaves saved data unchanged.
  4. Review the restored scripts in Modules & scripts, enable the module and the scripts you want, and reload affected website tabs.

Restore replaces the saved settings and library, including scripts and values absent from the file. It does not merge libraries. The userscript module and every restored script start off, even when they were on in the backup. Execution permissions and hidden-direction-control acknowledgments must be granted separately. Dependencies are checked against their cached SHA-256 digests and declared pins; missing caches can be prepared later through the normal manager. Restore does not download dependencies. Already executed page code cannot be undone; reload open pages.

If settings, scripts, saved values, appearance or script update preferences change after the review, restore refuses to overwrite them; choose the file again to review the latest state. A failed restore reports the error and attempts verified storage and native-rule rollback. If rollback cannot be verified, the error says so; reopen the extension and check its status before retrying. A browser or computer interruption during restore may leave its outcome unknown: reopen and check before repeating it.

Backups exclude browser permissions, execution capabilities, MCP approvals/connections, editor drafts, activity/network logs, suspected-ad flags, invalid quarantined entries, pending script updates, and downloaded community/threat list updates. Existing downloaded filter lists and diagnostic data in the destination browser are retained; bundled lists belong to the installed extension version. Browser cookies and general browser data are not part of a script's GM values. Only Module Engine's version-1 JSON backup format is supported; ZIP archives, other managers' backups and cloud sync are unavailable.

Modules and userscripts

Use New script to start from an explicit example site scope, or Import to read a local UTF-8 .user.js file. Review the code, sites, timing and APIs in the editor. Save stores a script turned off, without running it; after review, turn on Run this script beside its name, then reload a matching page. Saving an edit pauses that script again. Duplicate name/namespace identities and stale saves from another editor are rejected. Drafts are preserved when another window changes the library; Discard draft explicitly loads the latest saved source.

Scripts containing hidden Unicode direction controls show a warning with their original line and column positions. Install/update and MCP reviews display those controls as visible \uXXXX escapes; saved, exported and executed source stays unchanged. The editor also marks their locations. Before Run this script can enable affected code, review the escaped preview and explicitly acknowledge the warning. Cancelling leaves it off. Every later enable needs its own acknowledgment, including after an edit or update. Ordinary Arabic/Hebrew text and textual JavaScript escapes do not trigger this warning. This helps review visibility; it does not certify that a script is safe. Executable @require files with these controls also need review in Modules & scripts. Each preview identifies the cached URL and SHA-256 digest. Previously enabled scripts with affected dependencies pause on upgrade until reviewed.

Export saves the current editor text, including an unsaved draft, as a local .user.js file; dependency caches and GM values are not included. Delete removes the saved source, cached dependencies and GM values after confirmation. Disabling a script or the module unregisters future runs, revokes live API access and cancels pending network requests. It cannot undo arbitrary JavaScript already executed on an open page; reload that page. Re-enabling requires a fresh page load for that script's GM access.

This is an original, focused userscript manager inspired by tools such as Violentmonkey, with a documented compatibility subset:

Feature Supported behavior
Installation and updates Direct URL installation or opening a .user.js link, which shows the review first. @downloadURL / @updateURL are used for checks after a URL install. Daily background checks download newer versions. A version from the same address that needs no new access installs on its own and keeps the script's on/off state; other updates wait for review. Manual checks are always available. Reviews show the read-only current and proposed code and access, need explicit approval and preserve GM values. Nothing new installs without your approval, and an update you apply after review starts paused.
Metadata @name, @namespace, @version, @description, @tag, HTTP(S) @match / @exclude-match, URL glob or bounded regex @include / @exclude, @run-at, @noframes, @require, @resource, @connect, @top-level-await, @unwrap
Editor and organization Syntax highlighting, line numbers, inline errors, metadata suggestions, author/local tags, search/filter, configurable start order and optional external-file tracking with explicit draft review.
Scope At least one explicit @match or @include; up to 64 entries per rule type. Either inclusion type can match, and either exclusion type vetoes it. Extended HTTP(S) match patterns, URL globs and bounded regex rules are detailed below. <all_urls> means HTTP(S) pages. Browser-restricted pages remain unavailable.
Timing and frames document-start, document-body, document-end (default), document-idle; matching frames by default, top frame only with @noframes. Legacy value reads and value listeners wait for stored values before running, so document-start can be delayed for those scripts.
Execution Isolated content by default. page can combine real page globals with granted GM APIs; wrapped auto tries page first with isolated fallback if startup is blocked. Chrome/Edge allow 10 isolated worlds per document, including the relays for page bridges. Keep overlapping scopes within that limit. See the execution and upgrade details below.
Helpers GM.info / GM_info identifies Module Engine and exposes script.grant (also grants), script metadata, UUID, source and actual injection context. When a script runs in the page (page, or auto in the page), the site can read that data, so the UUID there is derived from @name and @namespace and shared by everyone who uses the script, rather than your installation's own ID. GM.addStyle / GM_addStyle returns the style element with a one-use .then() callback.
Elements GM_addElement / GM.addElement accepts (tag, attributes?) or (parent, tag, attributes?). Returns a real DOM element synchronously, with a one-use .then() callback. Supports explicit element and shadow-root parents; browser CSP still applies.
Tabs GM_openInTab / GM.openInTab returns a synchronous handle with close(), closed and onclose. Supports HTTP(S) destinations, background/foreground, adjacent insertion and pinning; see limits below.
Clipboard GM_setClipboard(data, type?) writes asynchronously and returns void; GM.setClipboard returns a completion promise. Text and HTML only; no reading. Requires optional helper access.
Notifications GM_notification / GM.notification returns an immediate handle with promise-returning remove(). Supports text/options, click and close callbacks. Requires optional helper access.
Downloads GM_download returns an abort control with callbacks; GM.download returns an abortable promise. Bounded HTTP(S) downloads save through the browser and respect @connect. Requires optional helper access.
Cookies GM_cookie / GM.cookie provides list, set and delete. Calls with callbacks return void; omitting the callback returns a promise. Requires its own grant and optional cookie permission. Includes HttpOnly cookies; current host and explicitly declared @connect destinations, calling tab's store only.
Local values Synchronous GM_getValue, GM_listValues, GM_getValues; legacy GM_setValue, GM_deleteValue, GM_setValues, GM_deleteValues return void and persist asynchronously. All seven corresponding GM.name methods return promises. getValues accepts an array of keys, an object of defaults, or no argument for all values. Stored values must be JSON-compatible; 256 nonempty string keys and 64 KiB per script.
Value listeners GM_addValueChangeListener(key, callback) / GM_removeValueChangeListener(id) and GM.addValueChangeListener / GM.removeValueChangeListener. Callbacks receive (key, oldValue, newValue, remote); creation/deletion uses undefined, and remote identifies another script instance. Unchanged values do not notify. Up to 256 listeners per instance.
Menus GM_registerMenuCommand / GM_unregisterMenuCommand and GM.registerMenuCommand / GM.unregisterMenuCommand. Commands appear in the extension popup for their page tab. Register returns an ID synchronously; the same ID updates a command. Optional id, title, accessKey, autoClose (default true), icon, or a legacy access-key string. Icons accept inline base64 PNG/JPEG/GIF/WebP up to 32 KiB; other URLs are ignored without fetching. Up to 32 commands per instance. Captions are literal text.
Dependencies Explicit preparation of up to 8 ordered @require libraries and 16 uniquely named @resource files; 256 KiB each and 1 MiB combined per script. See preparation below.
Resources Synchronous GM_getResourceText(name) / GM_getResourceURL(name); promise-returning GM.getResourceText(name) / GM.getResourceUrl(name) (GM.getResourceURL also accepted). Text is decoded as UTF-8; URLs are cached Blob URLs, revoked on final document unload and retained across back/forward cache suspension. Unknown names throw/reject.
HTTP GM_xmlhttpRequest(details) with callbacks and .abort(), and abortable promise GM.xmlHttpRequest(details) (GM.xmlhttpRequest also accepted). Supported options and bounds are below.
Library limits 32 scripts, 128 KiB source per script, 1 MiB source overall, 3 MiB total library storage
Unsupported Regex flags (including u); repetition counts above 128; non-HTTP(S) pages and unsupported directives/grants. Icon URLs remain informational with a visible explanation. Other sites’ cookie partitions, arbitrary non-JSON storage, updates applied without review, ZIP backups and cloud sync are unavailable.

The editor checks syntax and metadata without running the source. Runtime errors still appear in the matching page's developer console. For agent-assisted inspection, Modules & scripts → MCP optionally connects to the bundled local server, which is read-only by default; see setup, approval and capture limits. If you start it with --allow-changes and tick Propose script changes for my review, the agent can also propose new scripts, edits and on/off changes. Each proposal waits on the MCP page with the same review as a URL install; nothing is saved until you click Apply, and applied scripts stay off unless you choose Apply & enable. See script change proposals. Ad blocking and userscripts work independently of that server. This does not claim full Violentmonkey compatibility.

Request each helper with its exact @grant name. Legacy reads use a hydrated private cache, not a promise disguised as a synchronous API. Legacy writes update that cache immediately, then save in order. A failed write rolls the cache back and logs the failure; use the modern promise-returning methods when the script needs confirmation of persistence. Native value requests retain limits of 8 per browser tab, 16 per script and 64 overall; each document queues at most 64 writes. Up to 64 initial cache connections can wait separately without consuming those value-request slots; manager controls still take priority. Concurrent tabs can overwrite the same key: read/increment/write is not an atomic counter.

To use a script command, open Module Engine on its matching page and choose a button under Script commands for this page. Refresh commands updates a popup that was already open. Frame commands identify their frame. A callback receives a synthetic click event with modifier keys; browser user activation is not transferred into the script. Editing, disabling, deleting or revoking browser access removes live menus and their capabilities. Page unload disconnects them. A native worker restart reconnects an open document without rerunning its source; after three failed reconnects, reload the page. Existing code and values it already read cannot be taken back.

Menu publication has separate capacity of one pending update per native connection and 64 overall. Updates made while a publication is pending combine into the latest menu state. This leaves ordinary GM value capacity available, and manager controls still take priority.

The 32-script library limit is separate from Chromium's per-document world limit. Chromium can fall back to its default shared world after 10 isolated worlds. Module Engine leaves messaging disabled there, and privileged scripts stop with a console error instead of receiving GM access. Keep overlapping isolated scripts within the limit, including scripts with no privileged grants. Native include-glob prefilters are broader than the exact case-insensitive wrapper: they can consume a world on nearby paths even when the wrapper refuses execution. The manager displays a reminder when more than 10 isolated scripts are enabled across the library.

Execution compatibility

@grant unsafeWindow supplies the global object of the selected world. In @inject-into page, it is the actual page window and can read/change page JavaScript objects alongside granted GM APIs. In content and the default mode, it is the isolated script global: DOM access works, but page JavaScript globals remain inaccessible.

Wrapped @inject-into auto scripts try page execution first, following Violentmonkey's injection-mode behavior. If CSP, Trusted Types or unavailable page startup prevents execution, they run in content mode instead. GM_info.injectInto reports the mode actually used, and unsafeWindow follows that mode. An exception or rejected promise after page startup never triggers fallback, so side effects are not repeated. The page+GM bridge respects site policy; explicit page mode reports blocked startup without falling back. Existing native page scripts without GM grants, and raw page scripts, retain their native execution path.

Page execution shares trust with the site. Page code can interfere with the script, observe its data or invoke its granted helpers, including storage, network and cookie helpers. Native credentials remain in an isolated relay, and the broker still checks grants, current URL, browser permission and revocation. This does not isolate a page script from the page. Use content when you need that isolation; grant page scripts only the access you trust the site to exercise.

Upgrading existing auto scripts: previously saved scripts stay isolated until you disable and re-enable each one after reviewing the warning. Saving, or applying a reviewed update, disables the script and resets that choice; an automatic update, which cannot change @inject-into, keeps it. Switching the whole module off/on does not opt older scripts into page access. The default for scripts without @inject-into remains content.

For example, a reviewed script can request both real page globals and storage:

// @inject-into auto
// @grant unsafeWindow
// @grant GM.setValue
// @top-level-await
// Add these to the script's metadata block, alongside @name and @match.

if (unsafeWindow.myPageApp) {
  await GM.setValue('lastTheme', unsafeWindow.myPageApp.theme);
}

The bridge adds bounds of eight pending native calls and one native connection per script instance, 128 incoming bridge events per second and 24 MiB per serialized packet. Existing GM storage/network/helper limits still apply. A call that times out or loses its page bridge may already have reached the browser; it is never retried automatically.

Page startup and GM connections now follow trusted browser navigation events; a website dispatching synthetic pagehide/pageshow events cannot suspend the bridge or create duplicate connections. Returning to a cached document reconnects values and menus without rerunning the source. A discarded document loads and runs normally as a new document. Native worker restarts also reconnect without replaying script code, with three bounded retries before requiring a reload.

Navigation cancels unsent queued writes and discards stale read replies. Already submitted writes can still complete: an available completion reply keeps its actual success/error, while old value snapshots are discarded. Losing the entire page bridge still leaves the outcome uncertain. Reload the extension and script pages after updating this checkout; existing tabs do not adopt the new runner automatically.

Add a bare // @top-level-await line to use await directly in the script body. Cached @require code runs in declared order in the same async wrapper before the source. Execution begins at the selected timing phase, subject to existing cache/channel startup, then yields at each await; script start order does not guarantee completion order. Rejections are reported in the page console. Disabling revokes GM access but cannot cancel ordinary JavaScript promises or undo page changes. GM_info.script.topLevelAwait describes the selected mode.

// @unwrap removes the function and strict-mode wrappers. Top-level var, functions, let and const have native global-script semantics in the selected world. In page mode they can share globals with page scripts; in content mode they remain isolated. Raw auto stays isolated; select page explicitly for raw page-global declarations. All @grant lines are ignored, including unsupported grant names; no GM APIs or unsafeWindow alias are supplied. @require libraries precede the source as raw code. It cannot combine with @top-level-await or document-body, and top-level return is invalid. These two directives are described in Violentmonkey's metadata reference.

Unwrapped scripts accept the same scopes as wrapped scripts, including @include/@exclude globs and regular expressions, ports, fragments, IPv6, .tld and partial host wildcards. Scopes the browser can enforce natively (exact hosts, * or a leading *. host wildcard with ordinary paths) register as before. Other scopes run a separate pre-check script first. On a page that the browser's broader native scope admits but the exact scope excludes, the pre-check defines a non-enumerable, non-configurable marker on that world's global; the raw script also declares that name with let, so the browser refuses to instantiate it. No raw statement runs and no var, function or lexical binding is created. The marker name is derived from the script name and namespace, not your installation. Page-mode scripts with a later @run-at get their pre-check at document start, before page listeners. The delayed runner verifies that the approved document URL is still current immediately before execution. If it changed, reload the destination to run a matching script. Chrome and Edge hide the expected redeclaration error from the console and page listeners. Firefox hides it in page mode, but its console can show one “redeclaration of non-configurable global property” error for each skipped isolated script. Page code can see the marker on excluded pages in page mode. @noframes and native exclusions remain effective.

Cookie helpers

Declare @grant GM_cookie and/or @grant GM.cookie, review the scope, then choose Allow helper access. The browser's cookies permission is optional and is never requested by running script code. This grant can expose or change login/session cookies, including HttpOnly values. Grant it only to reviewed code. The manager's installation/update review shows cookie scope and execution-mode changes.

Both spellings support list(options, callback?), set(options, callback?) and delete(options, callback?). With a callback, calls return undefined: list calls (cookies, error), while set/delete call (error); errors are strings and successful error arguments are undefined. Without a callback, calls return promises: list resolves to an array, set/delete resolve to undefined, and failures reject. Invalid callback types throw immediately. Callback signatures follow Violentmonkey's GM cookie reference; promise use is also supported here.

An omitted url uses the current frame URL, including its path; an explicit URL must be absolute HTTP(S) without credentials. Every list operation has a URL filter, so {} does not enumerate the whole browser cookie jar. The current host is allowed; other hosts require an explicit @connect hostname or *. A hostname also covers its subdomains. Setting a parent-domain cookie needs authorization for that parent. These cookie defaults are narrower than the HTTP helper's unrestricted default.

Method Options
list url, name, domain, path, secure, session, storeId
set url, name, value, domain, path, secure, httpOnly, sameSite, expirationDate, storeId
delete url, required name, storeId

The native cookie store is resolved from the calling tab, preserving private-window/container separation. An explicit storeId must match that store. Partitioned (CHIPS) cookies are available through partitionKey: {topLevelSite, hasCrossSiteAncestor?} only for the calling tab's own top-level site, such as https://example.com. A subframe uses its tab's top-level page, and an empty partitionKey (all partitions) is rejected. Without partitionKey, lists exclude partitioned cookies. In Firefox, firstPartyDomain accepts '' or the tab's own first-party domain, which first-party isolation requires; Chrome and Edge reject it. No browser privacy setting is changed. Browser cookie restrictions remain in force; see the Chrome API and Firefox API.

Results are limited to 256 cookies and 1 MiB; oversized results reject instead of silently truncating. Values accept at most 4096 UTF-8 bytes, other string options 1024, domains 253 characters, and URLs 4096 characters. Native operations time out after two seconds without retrying. A pending browser call retains its capacity slot until it actually finishes (two per script, eight overall).

Scope, document, capability and permission checks guard each new call; list results are checked again before delivery and discarded if access was revoked. Cookie scripts wait for their native channel before source execution. Disable/edit/delete, unload, permission removal and leaving scope reject further calls.

For set and delete, submission to the browser is the acceptance boundary. A submitted write cannot be cancelled by disabling the script; its native success or failure is still returned if the calling context remains available. If it times out after submission, the error explicitly says the outcome is unknown and the write may still complete. Module Engine never retries or rolls back that write automatically, since doing so could overwrite another cookie change.

Userscript URL matching

@match and @exclude-match accept http, https, * or http* schemes. * and http* mean HTTP and HTTPS. Hosts accept exact names, *.example.com (including the base host), partial wildcards such as api*.example.com, bracketed IPv6, and exact internationalized names such as bücher.example (normalized to punycode). Use punycode when mixing a partial wildcard with internationalized labels. An omitted port or :* accepts any port; an explicit port also recognizes its default form, such as :443 on HTTPS.

Match paths remain case-sensitive and include the query string. A fragment is checked only when the pattern contains #; otherwise it is ignored. This preserves existing Module Engine behavior: /read matches /read#part, but requires /read* or an explicit query pattern to match /read?id=1. A matching history/hash change does not itself run a script again. Reload the page to trigger a fresh run.

@include and @exclude accept case-insensitive full-URL globs, with * as a wildcard and ? literal, or /regular expression/ without flags. Regex matching is case-insensitive and searches the full canonical URL, including its query and fragment. Use ^ and $ for exact boundaries. Syntax is that of a browser RegExp with the i flag and no u flag, as in Violentmonkey: groups, named groups, alternation, classes, assertions, lookahead and lookbehind ((?=…), (?!…), (?<=…), (?<!…)), numbered and named backreferences (\1, \k<name>), lazy quantifiers, (?-i:…) modifiers and legacy forms such as octal escapes and literal braces. Without the u flag, \p{…} matches literal text; the editor warns about it. Flags and repetition counts above 128 are rejected.

Expressions never run in the browser's own backtracking engine, so a hostile URL cannot stall the extension. Patterns without backreferences use a linear matcher, where each lookaround is one pass over the URL. Backreferences use a bounded search that follows browser priority rules. URLs longer than 32,768 characters, and searches that exceed the work limit, fail closed: the script does not run, and an exhausted @exclude still blocks it.

// @match http*://api*.example.com:8443/read*#details
// @match https://example.tld/*
// @include /^https?:\/\/(www\.)?example\.com\/read(?:\/\d+)?$/
// @exclude /\/private(?:\/|$)/

The host suffix .tld means a known public suffix, including private hosting suffixes, from the bundled Public Suffix List. For example, example.tld accepts example.com, example.co.uk and example.github.io; it rejects example.com.attacker.org. Wildcard and exception entries follow the list's longest-suffix rules. Unknown suffixes are rejected. In include globs, *.example.tld still requires a subdomain, and omitting a port requires the URL's default port. .tld is special only at the end of a hostname in a match pattern or URL glob; it is not expanded inside regexes. No suffix lookups or updates use the network.

Matching is bounded: 2,048 characters per rule, 32,768 per URL, 16 nested regex groups, repetition bounds up to 128, 512 compiled states and 100,000 compilation visits per regex, and one million state visits across a URL's regex checks. A limit failure denies scope, including when it occurs in an exclusion. Broad rules need conservative native prefilters and may consume one of Chrome/Edge's ten isolated worlds even on a page where the exact guard declines execution. Narrow host/path rules reduce that overlap.

The wrapper and GM broker enforce the same scope. Privileged calls additionally read the current frame URL, so an old browser-reported sender URL cannot grant access after a history change. An unavailable, replaced or unresponsive frame fails closed; a scope probe times out after two seconds. These matching changes do not expand @connect destinations or grant access to non-HTTP(S) or browser-restricted pages.

Editing and organizing scripts

The source editor highlights JavaScript and metadata, displays line numbers and marks syntax errors. Choose Go to error to focus the reported character. It checks the selected execution form: strict function body by default, async body with @top-level-await, or a raw script with @unwrap. Top-level return is allowed only in wrapped modes. It is a syntax check, not a runtime or security audit. Highlighting stops after 20,000 tokens; remaining text stays plain. If parsing exceeds two seconds or the worker fails, the editor retains the source and falls back to plain text.

Use repeated @tag metadata for author tags, or enter comma-separated Your tags and choose Save tags. Each set supports 16 unique tags of 1–64 characters without commas or control characters. Local tags survive source edits and approved updates; they do not alter exported source or GM_info.script.tags. Search includes script names, sites and both tag sets; the tag selector filters the library. Saving tags alone keeps the script enabled. Saving source and tag edits together pauses it as usual.

Inside the metadata block, type after @ for supported directive suggestions. Values are suggested for @grant, @run-at and @inject-into. Ctrl+Space or Suggestions opens the list; use Up/Down to select, Enter/Tab to insert and Escape to dismiss. With the list closed, Tab moves focus normally. Ctrl+Z undoes an insertion. Suggestions do not change other metadata, add permissions or run code. The syntax checker still catches incompatible combinations. This is metadata completion, not general JavaScript IntelliSense.

For an external editor, export a script to a local .user.js file and edit it in your usual editor. With an installed Node.js 22 or later, open a terminal in the Module Engine project folder and run the included helper, replacing this example path:

node development/server.cjs --file "C:\path\script.user.js"

Open the script in Module Engine, expand External editor, paste the terminal's MEF1 pairing code and choose Start tracking within two minutes. Keep the terminal and manager page open. The helper reads only that chosen UTF-8 file (up to 128 KiB). It supports normal saves and atomic file replacement; it has no directory browser, file-writing endpoint or script execution. No package installation, file:// permission or new extension permission is needed.

File changes are detected about once a second while connected. Choose Load into draft, review the source, site scopes and GM access in Script details, then Save. Unsaved source replacement requires confirmation; cancellation preserves the draft. If the file changes during confirmation, review it again. Local tags are preserved. Saving pauses the script and keeps tracking the same file. Enable it explicitly only after review. Missing, oversized or invalid UTF-8 files leave the draft unchanged.

Stop preserves your draft. Opening a different script, discarding/reloading a draft or closing the manager ends tracking. A stale saved revision prevents loading file changes. A connection lasts at most 30 minutes; restart the helper for a fresh pairing code after stopping, expiry or an interrupted connection. Stop its terminal process with Ctrl+C when finished. Neither the helper nor this workflow writes changes back to your editor file; use Export if you want a copy of changes made in Module Engine. Windows CRLF is accepted and shown using the textarea's LF line endings.

The helper is separate from MCP, whose tools only read or propose changes for your review. It listens on literal 127.0.0.1 with an expiring one-use code, rotated session token, exact Host check and extension-origin binding. Ordinary webpages cannot pair or read files. Tokens stay in page memory and are cleared from the input; do not share them. This boundary does not protect against software already controlling your user account. Network paths, device paths, alternate streams and symlink/junction redirection are refused; choose the real local file path.

Select a saved script and use Earlier or Later to change its start order. This applies on the next page load within each @run-at phase; different phases still follow their normal timing. Disabled scripts retain their positions. Saved-value hydration and asynchronous work may finish later, so use explicit coordination when one script depends on another's completed work. Tags and ordering are local library settings, not part of a single-file source export.

Installing and updating scripts

  1. Open a .user.js link, or open Modules & scripts → Install from URL, paste a direct userscript source URL and choose Fetch for review. A website's HTML file-view page is not a source URL.
  2. Review the read-only code, sites, excluded sites, APIs, network scope, timing, frames, execution world and dependencies. Changed settings are marked beside the current values. Fetching does not save, enable or execute anything.
  3. Choose Install script. The script is saved paused. Prepare and review any dependencies, allow the relevant browser access, then enable Run this script and reload a matching page.
  4. When an update is ready, the script shows Update in the library. Select it and choose Review update under Source & updates, or choose Check for updates at any time. Review the current and proposed code, then choose Apply update. Approval uses exactly the bytes shown, without fetching a different version. The script's ID and latest saved GM values are retained; its source is replaced and it is paused again. Reload pages after enabling it.

Opening .user.js links. While Userscripts is on, opening a top-level https://…/*.user.js link (HTTP only on localhost) replaces that tab with the review dialog. The extension then downloads the source separately, without cookies. Opening a link never installs or runs anything. If the URL turns out to be an HTML file view, a redirect or a file without a // ==UserScript== block, the tab goes back to opening it normally. For any other error, Open file in browser does the same. Background prerendering, frames, POST requests and plain-HTTP hosts are never intercepted. A tab is replaced at most once every two seconds, and at most eight links are intercepted per minute. Turn off Open .user.js links for review under Installs & updates to let links open normally. The browser's own request for the link is not blocked: it may already have reached the server, or started a download if the server sent the file as an attachment.

Update sources. After a URL install, updates are downloaded from the script's @downloadURL, or from the installed URL if it has none. Versions are checked at @updateURL, or by downloading the script if it has none. The same HTTPS rules apply, and unusable URLs fall back with a visible note. The review's Update source row shows both URLs for the current and proposed versions, so a changed destination is marked before you approve it. A local script is never checked. If it declares @downloadURL, Review @downloadURL fetches that URL for an ordinary install review, which links it if you approve. You can also use Install from URL with the same @name and @namespace; the review shows a replacement and links that URL while retaining values. Updates cannot change this identity. Local source edits are shown as the current source and will be replaced only if you approve. Saving a local edit retains its source URL.

Daily checks. While Userscripts and Check installed scripts daily are on, an hourly alarm checks each linked script whose last check is a day old, one download at a time. A script whose source or URL changed is checked on the next alarm. Only strictly newer @versions are downloaded for review, following Violentmonkey's rule that unversioned scripts are not updated automatically. Same-version or unversioned changes remain visible through Check for updates. Downloaded updates are kept for review until the script's source or URL changes, up to 1 MiB in total; beyond that, only the available version is noted and Review update downloads it again. Pausing Userscripts or turning checks off cancels a running check. Check all now runs a check immediately. Each check contacts that script's host, which can see your IP address and that you use the script. If the saved settings are damaged, every automatic behavior stays off until you change a setting.

Automatic updates. While Install updates that need no new access is on (the default), a check installs a downloaded update without a review if all of these hold:

  • it is a newer @version of the same script, from the address the script already downloads from;
  • it runs on no new sites: no new @match or @include entries, no removed exclusions, and no newly allowed frames;
  • it asks for no new @grant or @connect entries;
  • it does not remove its last @connect entry while it keeps GM.xmlHttpRequest or GM_download: with no @connect entries, those requests can go to any HTTP(S) host;
  • it keeps its @inject-into world, @run-at timing and wrapping;
  • it keeps its @require and @resource files and its @downloadURL and @updateURL;
  • it has no hidden direction controls.

Entries are compared as written, so any new pattern counts as new. The script keeps its on/off state, GM values, tags and cached dependencies. Its library entry reads "Updated automatically", and the activity log records the change. Reload open pages to run the new code.

Any other update waits for review, with the reason shown beside it: for example "it asks for GM_cookie". Checks never edit, pause or replace the installed script in any other way. Turning the setting off stops a check that is running and makes every update wait for review.

An automatic update is only as trustworthy as the script's host: whoever can change the file at its address can change what it does on the sites it already reaches. Turn the setting off if you want to read every change.

Source downloads require HTTPS, except HTTP on localhost, 127.0.0.1 or [::1] for development. Credentials, URL fragments and redirects are rejected; cookies and referrers are omitted. Use the final direct URL if a host redirects. An opened link that redirects is handed back to the browser, so the final URL is reviewed if it is itself a .user.js URL. Limits are 128 KiB of valid UTF-8 source, 30 seconds and four concurrent source downloads. Unsupported metadata, HTML and failed HTTP responses are rejected. Cancel download restores the manager immediately. A stale review cannot overwrite a later edit or deletion, and failed commits attempt verified storage/native-registration rollback.

Version comparison uses dotted numeric parts with optional letter suffixes ignored, following the documented Violentmonkey version convention. Missing or other version formats are explicitly shown as incomparable. Identical source has no update action; changed source with the same version is clearly labeled for review. Numerically older versions cannot be applied through this flow. Updates preserve cached dependencies when their declarations match; changed dependencies require preparation before enabling. Source URLs stay in the local library; single-file Export exports source only.

Clipboard, notifications and downloads

Request the exact API spelling with @grant. In Modules & scripts, select the script, review its source and choose Allow helper access, then accept the browser prompt. These browser permissions are shared by the extension, but each script still needs its own exact grants and a valid native connection. They are optional; the blocker does not need them. The manager displays download destinations from @connect, just as it does for HTTP requests.

GM_setClipboard(data, type?) and GM.setClipboard(data, type?) accept strings up to 1 MiB of UTF-8. The default type is text/plain; text, html and text/html are also accepted. HTML is copied literally, without inserting or executing it. The legacy call returns void and logs failures; the modern call returns a promise that confirms the write. Clipboard images, reads and selection preservation are unsupported. A write already accepted by the browser cannot be undone by disabling a script.

GM_notification({text, title?, image?, silent?, tag?, onclick?, ondone?}) and GM.notification return {remove()} immediately. The positional (text, title?, image?, onclick?) form also works. remove() resolves after removal, and ondone runs once after confirmed closure. Titles identify the source script. Text is limited to 4 KiB, titles to 256 bytes and tags to 128 bytes. Images must be inline base64 PNG/JPEG/GIF/WebP up to 32 KiB; remote images are rejected without fetching. A repeated tag replaces the same document instance's earlier notification. silent applies on Chrome/Edge; Firefox does not support that native option and ignores it. Zombie options, persistent notifications across worker restarts and cross-tab tag replacement are unsupported. Native permission denial or creation failures log an error; remove() then rejects. System notification settings may suppress a visible toast even when the browser accepts it.

GM_download({url, name, ...options}) and GM.download also accept (url, name). Options are headers, timeout, anonymous, redirect, user, password, saveAs, conflictAction, context and the existing HTTP callbacks (onloadstart, onreadystatechange, onprogress, onload, onerror, onabort, ontimeout, onloadend). The response uses a Blob. Completion means the native browser save finished; progress describes the initial HTTP transfer. A download uses GET with a 120-second HTTP timeout and 16 MiB response cap. The HTTP cookie/header/redirect rules below apply, including @connect checks at every hop; without @connect, any HTTP(S) destination is allowed. The grant permits network access without also requiring an HTTP grant.

name must be a single filename of at most 240 UTF-8 bytes, without directories, reserved device names or invalid filename characters. conflictAction decides what happens when that name already exists: 'uniquify' (default) adds a counter, 'overwrite' replaces the existing file with the same name in the download folder, and 'prompt' lets Chrome and Edge ask you when that name already exists. Firefox has not implemented 'prompt', so it is rejected there before any transfer; use saveAs: true instead. Blob/data URL inputs, streaming, POST bodies and files larger than 16 MiB are unsupported. Files save to the browser's download directory, or its chooser when saveAs: true; browser prompts and protections remain in force. Files are never opened automatically. Saved files remain on disk after a script is disabled.

There are at most four active desktop helpers per connection, eight per script and 32 overall, with 32 attempts per helper kind per script per minute. Editing, disabling, deleting, page unload, permission revocation or connection loss clears owned notifications and cancels unfinished downloads where the browser still grants access. Pending callbacks/promises settle without retries. After an abrupt worker termination, an already accepted native save may still finish and its result cannot be delivered to the old promise; inspect the browser's Downloads page before retrying. Stale userscript notifications are cleared on worker startup or when permission is restored. Helpers are not a full implementation of every Violentmonkey option.

Element and tab helpers

Grant the exact spelling your script calls. GM_addElement('div', {textContent: 'Hello'}) adds an element to the body, or the document root while the body is absent. Script/style/link/meta elements default to the head or document root. GM.addElement(parent, 'span', {textContent: 'Hello'}) uses the supplied element, document fragment or shadow root. Attribute values must be strings; textContent sets text directly, and other entries use DOM attributes. Both spellings return the element immediately and support a one-use .then(element => ...), as does GM_addStyle. At most 64 elements may await a missing document root. Page CSP and Trusted Types still apply; this helper does not provide Violentmonkey's CSP-bypass behavior.

GM_openInTab('/next', {active: false}) resolves a relative URL against the current page and opens in its window. Both spellings return a control immediately, including GM.openInTab; they do not return promises. Options are active (default true), insert (default true) and pinned (default false). A boolean second argument means open in background, so true means active: false. Insertion places the tab next to its source and requests a native opener; insert: false leaves placement to the browser. URL credentials, non-HTTP(S) destinations and unknown options are rejected. Source windows are preserved. In Firefox, a new tab keeps the source tab's container; container: 0 selects the default container and 1, 2, … select container (user context) IDs. Firefox requires cookie access for containers, so a Firefox script with this grant asks for it under Allow helper access. Without it, a tab from a container fails with an error instead of opening outside that container. Private windows keep their own store and reject container. Chrome and Edge have no containers and ignore the option.

Use handle.close() to close only the tab created by that script instance, including immediately after requesting it. handle.closed updates after confirmed closure, and handle.onclose = () => ... receives one notification. Creation errors mark the handle closed and log a console error without invoking onclose; failed closes log an error and can be retried. There are at most 8 connected handles per instance, 16 per script and 64 overall; at most 4 openings per script and 8 overall may be pending. Each script can request 32 openings per minute. These limits bound the helper, not arbitrary page JavaScript.

Editing, disabling, deleting, page unload, permission revocation or native connection loss invalidates existing handles while leaving their tabs open. They are not reattached or replayed after reconnection; closed retains its last confirmed state and no close callback is fabricated. An opening already accepted by the browser can finish after revocation. Ad filtering still applies to helper destinations. Automatic blocked-popup cleanup requires an opener in the browser's initial creation event; an API-created tab may lack that initial evidence and need handle.close() instead.

Preparing dependencies

Save a script with its absolute @require URL and @resource name URL declarations. While it is disabled, choose Prepare dependencies. Downloads require HTTPS, with HTTP allowed only on localhost, 127.0.0.1 or [::1] for development. URL credentials, relative URLs and redirects are rejected. Downloads omit cookies and referrers, have a 30-second total deadline, and run as data without executing code in the manager. A #sha256=<64 hex characters> fragment pins the exact bytes; the manager always records a SHA-256 digest. A digest without a trusted pin detects changes to the cache, but is not proof of publisher identity.

Use Review contents to inspect the readonly preview, URL, size and hash, then enable the script. @require must be valid UTF-8 JavaScript; HTML responses are rejected. Libraries run in declaration order before the main source in the same native script world. The wrapper is strict JavaScript; libraries relying on sloppy-mode globals or the page's JavaScript objects may still need adaptation. Resources retain their bytes and MIME type. Imports, saves, startup and page loads do not fetch dependencies; startup verifies cached hashes before registering enabled scripts. Preparation failure preserves the old cache. Changing declarations clears it; body-only edits preserve it and still disable the script. Editing, deleting, cancellation or turning off the module aborts pending preparation and rejects stale results. Up to four preparations may run concurrently, without holding the manager's control queue.

Userscript HTTP requests

Grant GM_xmlhttpRequest or GM.xmlHttpRequest explicitly. The manager shows @connect destinations; self means the current page's hostname, a hostname includes its subdomains, and * permits all HTTP(S) destinations. Without @connect, the network grant permits any HTTP(S) destination. This is separate from page-matching scope. Only enable this grant for code you trust with page data and destination cookies.

Supported options: url (relative to the page or absolute HTTP(S)), method (GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS), headers, data, timeout, anonymous, redirect, user, password, responseType, overrideMimeType, context, upload, and onloadstart, onreadystatechange, onprogress, onload, onerror, onabort, ontimeout, onloadend. Data may be a string, URLSearchParams, Blob, ArrayBuffer, typed array, DataView, FormData or a ReadableStream of Uint8Array chunks. A stream is read completely within the 8 MiB upload limit before sending; it is not streamed to the server incrementally, and aborting cancels it. In Firefox's isolated mode, only browser-made streams such as Blob.stream() or Response.body carry bytes. Firefox refuses new ReadableStream({...}) with a script-owned source, and chunks a script writes into a TransformStream arrive as undefined, so the request is rejected. There, pass the Blob or bytes directly. user and password (strings up to 1 KiB, no colon in user) are sent as HTTP Basic authentication on the first request; an explicit Authorization header takes precedence. Challenge-based schemes such as Digest or NTLM are not supported. FormData preserves ordered duplicate fields, Unicode, file names and binary bytes; let the browser set its Content-Type and boundary. It supports at most 256 entries, with framing included in the upload allowance. Responses support text, JSON, arraybuffer, Blob and inert parsed documents. Response fields include status, statusText, finalUrl, responseHeaders, readyState and response; text responses also populate responseText, and document responses responseXML. context stays local. HTTP errors such as 404 still produce onload/a resolved promise; transport errors reject. Invalid JSON returns null. Callback errors are reported without skipping terminal cleanup.

Requests are limited to 8 MiB upload, 8 MiB response, 32 KiB headers and 30 seconds, even for timeout 0. There may be four active requests per script instance, eight per script or browser tab, and 32 overall. HTTP and downloads share a 64 MiB reservation allowance. Native upload-progress XHR reserves its request body and full response allowance before starting. A streaming fetch reserves its request body and 256 KiB up front, then grows its share as response bytes arrive (or at once from a declared Content-Length); a transfer that cannot grow, or a new one, is rejected until another finishes. This is not a hard RAM cap: encoding and browser buffers add overhead. Cookies follow browser policy by default; anonymous: true omits them and prevents response cookie storage. Cookie/Host/Origin/Referer/User-Agent and other browser-controlled headers, embedded URL credentials (use user/password), responseType: 'stream', synchronous requests and unsupported options are rejected. Intermediate progress does not expose partial response bodies. Accepted requests are never retried after disconnect or worker restart, including POST requests. Disable/edit/delete, permission revocation, port loss and page unload cancel pending requests.

Redirects follow by default, up to five hops; redirect: 'error' rejects the first redirect. Every destination must satisfy @connect, credentials in URLs are rejected and HTTPS cannot downgrade to HTTP. A 301/302 changes POST to GET, a 303 changes non-HEAD requests to GET, and 307/308 preserve method and body. All caller-supplied headers are removed across origins; browser cookies follow the destination policy unless anonymous. Source installation and dependency preparation still reject redirects.

For actual upload progress, supply upload: {onloadstart, onprogress, onload, onerror, onabort, ontimeout, onloadend} with whichever callbacks you need. These describe sending the body; main callbacks describe the response. Progress frequency is browser-dependent, and a followed 307/308 can produce another upload cycle. Choose Allow helper access first: Chrome/Edge use an optional offscreen document for upload events, while Firefox needs optional webRequestBlocking to stop native redirects before checking their destinations. Firefox also needs that access to follow ordinary HTTP/download redirects. Requests fail closed when the required guard is unavailable. Plain FormData without upload callbacks uses the normal HTTP transport.

For example, this local script saves a setting and exposes a page command:

// ==UserScript==
// @name Local page setting
// @namespace local.module-engine
// @match https://example.com/*
// @run-at document-body
// @grant GM_getValue
// @grant GM.setValue
// @grant GM_registerMenuCommand
// ==/UserScript==
let compact = GM_getValue('compact', false);
document.body.classList.toggle('compact', compact);
GM_registerMenuCommand('Toggle compact view', async () => {
  const next = !compact;
  await GM.setValue('compact', next);
  compact = next;
  document.body.classList.toggle('compact', compact);
}, { id: 'compact', autoClose: false });

The module boundary is explicit: src/background/modules.js registers bundled adapters; src/background/background.js keeps the existing verified blocker transaction and restricts management messages to extension pages; src/userscripts/userscripts-runtime.js owns its scheduler, storage key and native registrations; src/userscripts/userscripts-core.js parses metadata and compiles wrapper source without evaluating user code in the extension. Ad-filter settings are not migrated or duplicated. New privileged modules must ship as reviewed extension code.

Native registration, world configuration and persistent library writes are verified and rolled back on failure. Worker startup, browser startup and extension-update handlers restore saved intent. Script APIs use native onUserScriptMessage / onUserScriptConnect channels, a per-script capability, declared grants and browser-provided document/frame/URL information. No page-event bridge carries privileged requests. Capabilities rotate on edits and both enable and disable transitions; scripts cannot use these channels to change modules or protection settings. Connections are bounded to 256 overall and 64 per script or tab. The implementation follows the browser's userScripts API and Firefox's optional-permission requirements.

Manager operations have their own bounded capacity and run before waiting GM storage requests. One runner serializes all library writes, so a shutdown waits for the active transaction to finish before taking priority; it does not race or abandon an in-progress save. GM limits include active and waiting requests, apply across frames in the same native browser tab, and release capacity on success or failure. Queued requests recheck the current capability after management changes, so an old request cannot write after a successful disable or delete. A failed management change restores its prior state and reports the failure.

Controls and scope

  • The master switch pauses all static and custom network rules, cosmetic filtering and prompt protection. Reload open pages to remove installed page API hooks.

  • Individual switches select the ad, tracker, reported-threat and cosmetic layers. The old unverified malware toggle remains retired. Reported Threats is off until you turn it on in the popup. That applies to new installs: an existing install keeps the choice it saved, so a profile that had the layer on keeps it on. Saved global pause and other preferences are preserved.

  • Reported-threat rules match only the listed hostname, including its root-dot spelling and ports. They do not infer subdomains or block shared hosting platforms. Explicit site exceptions still take precedence. This covers browser requests, not operating-system DNS or other applications.

  • When the evidence expires. By default an expired list keeps blocking until a newer list replaces it, and the popup shows the date it expired. Its evidence is then older than the review window, so a host may have changed hands; a site exception or the Reported Threats switch still overrides it. My lists → Stop blocking and warn when the evidence expires makes the layer switch itself off on that date instead, and the popup then asks for an update. That switch is off for new and existing installs, and it never changes the Reported Threats switch. While it is on, an expiry alarm, hourly guard and worker/startup checks disable the layer. Browser alarms may be delayed during sleep or suspension; disabling occurs when the browser dispatches the alarm or at the next reconciliation. Expiry depends on the local clock. Either way, a missing or malformed policy or unavailable alarms keep this layer inactive with an error; other filters remain usable. A newer list needs a new manual evidence review, delivered either in a new release or as a signed update (below).

  • Signed reported-threat updates. A release can name an update folder, normally the project's public repository. While Reported Threats is on, Module Engine then checks that folder at most once a day, and My lists → Check for updates checks at once. A check downloads four small files without cookies, a referrer or redirects. Nothing about you or your browsing is sent, although the server sees an ordinary request from your browser. A downloaded list is installed only if all of the following hold: it is signed by a key built into this release; its evidence matches its rules and policy byte for byte; it passes the same evidence checks as the bundled list; it has not expired; and it was reviewed later than the list in use. An installed list replaces the bundled list's rules with the same exact-host rules. It is checked again whenever the background starts. If the browser does not accept a new list, the previous one stays in use; a refused or failed check changes nothing. A newer release's bundled list takes over from an older installed update. This version names no update folder, so it never checks and uses the list bundled with it.

  • Site exceptions include subdomains. The popup names an inherited parent exception; Resume on example.com removes matching exceptions for that parent scope, including sibling subdomains that inherited it. Cosmetic filtering also respects the top page's exception inside frames from other origins. Reload the page after changing a site exception so frame-level network permissions are recalculated.

  • Custom entries accept DNS hostnames, IPv4 addresses, localhost, or HTTP(S) URLs. Only the hostname is used; paths and ports do not limit a domain rule. International names are stored in punycode. A leading www. is folded into the parent domain, preserving the original extension behavior. IPv6, credentials and filter syntax are rejected.

  • Settings updates are serialized. Success is shown only after the browser accepts the network rules and their readback matches. Failed changes return an error, attempt to restore the previous rules/settings, preserve the entered text and show a retry control.

  • Invalid entries saved by an older version are retained in local storage under quarantinedDomains, displayed as inactive entries, and excluded from active rules. Add corrected hostnames through the popup.

  • Cosmetic filtering hides matching page elements. It does not inspect downloaded files or determine whether a page is trustworthy.

  • Community lists are a separate switch. It covers EasyList, EasyList China and uBlock filters, the main list of uBlock Origin. The builder converts supported domain and URL-pattern blocks with their third-party, resource-type, site (domain=), match-case, important and pop-up options, their exceptions, generic and site-specific CSS, the advanced operators and the scriptlet filters documented below. From uBlock filters it uses the parts written for every browser: parts marked for only Firefox or only Chromium browsers, for phones, for Safari or for uBlock Origin's HTML filtering are left out, and so are its HTML filters. Plain domain blocks with identical options are merged into domain-list rules. Unsupported filters, including network regexes and unsupported scriptlets, are skipped and counted in rules/community-info.json. List exceptions rank below reported threats, custom blocks and site pauses, and never apply to domains Module Engine's own ad, tracker or site-check lists block. Browser rules cannot tell a pop-up from a normal page load, so a list pop-up pattern that is not tied to one host applies only to page loads started by another site.

  • Filter-list updates (My lists → Filter lists, on by default). While protection and Community lists are on, Module Engine downloads EasyList and EasyList China from their publishers as often as the lists ask. EasyList asks every four days and EasyList China daily; after a failed attempt it tries again 12 hours later. Downloads carry no cookies or referrer. The lists are converted on this computer by the same converter that built the bundled rules. A download is used only if it is an Adblock Plus-format list with the expected title and a version number, and no list is older than the one in use. At least one must be newer. Its conversion must also keep at least half of the bundled network and site hiding rules.

    • The update is installed as a change from the bundled rules: bundled rules the new lists dropped are switched off, and new or changed rules are added as dynamic rules. Site hiding follows the new lists.
    • Generic hiding, rules without a site, changes only with a new release, because its stylesheets are packaged files.
    • The change must fit the browser: Firefox allows 5,000 dynamic rules and 5,000 switched-off bundled rules, shared with your own rules. A change that does not fit is refused, and the bundled lists stay in use until a new release.
    • If the browser refuses the new rules, the previous lists stay in use. A new release brings newer bundled lists and replaces an installed update.
    • uBlock filters is never downloaded; it changes only with a new release. An update converts the copy packaged with this version beside the new EasyList copies, so its rules stay in use. If that copy does not match the hash recorded when this version was built, the check fails and the bundled lists stay.
    • Check for updates checks at once, even with automatic updates off. The card shows the versions in use, the date of the bundled uBlock filters and the last result.
  • Always Allowed Domains (popup list, or the Allow button next to a blocked server in the activity log): requests to these domains and their subdomains are never blocked by the ad, tracker, site-check or community lists, on any site. Unlike Pause on this site, which turns filtering off on the pages of a site, this allows one server everywhere. Reported threats and your custom blocks still apply; the same domain cannot be in both Custom Blocked and Always Allowed. Entries accept a hostname or URL like custom blocks.

  • Block pop-ups and redirects (popup switch, per site and its subdomains): a page-level script on the chosen site and each injectable child frame refuses windows opened by script, script-made clicks on links to another host scope, and clicks on disguised links to another host scope (invisible, or page-covering overlays). An exact host and its parent or child hosts share a scope; independent sibling hosts are kept separate so tenants on github.io, pages.dev and similar shared platforms cannot inherit each other's trust. Ordinary visible links still work. It does not depend on knowing the ad network's domains. Page-world block claims are deliberately not added to the activity log because a page could forge them. Reload after turning the switch off to remove an already-installed page hook; it is inactive on new pages while the site is paused or the master switch is off. Browser-restricted frames and pop-up routes that do not use these JavaScript hooks can still bypass this optional layer.

    On Chrome and Edge, the same switch also stops script-driven page replacements, including same-site URLs that could start a server redirect chain, scripted reloads, delayed redirects, script-submitted forms and meta refreshes. Stopping the first request keeps the current video document alive. Normal visible links, native forms, navigation within the same document, browser reload and Back/Forward remain usable. A synchronous script-handled link may navigate to its original exact destination. A real link or native form may follow server redirects normally; the guard does not know whether that chosen destination is wanted.

    Selected pages also receive a browser sandbox policy, inherited by embedded and nested frames, that prevents frames from navigating the top tab even after a genuine play click. Scripts, normal origins/storage, forms, presentation and other player capabilities remain allowed. Media and API response bodies are untouched. The policy is appended to the site's own CSP and cannot undo a stricter site policy. Locally generated video passed play, pause/resume, seeking and fullscreen checks in Chrome and Edge; player frames can still navigate and follow redirects within themselves.

    Compatibility is not universal: legitimate script-only full-page buttons, automatic next-page navigation and frame controls that intentionally navigate the top tab are also stopped. A blocked frame navigation can throw a browser security exception, so a player that performs that navigation before playback in the same handler may need this guard turned off. Pause protection or disable the guard and reload if a player depends on these behaviors. Already loaded pages retain their sandbox until reloaded. Responses generated entirely by a site's service worker may bypass the header policy; restricted injection, page-hook tampering and browsers without the Navigation API also limit protection. Live players, DRM playback and every redirect route have not been verified. The local tests never contacted a suspicious host.

  • Automatic cleanup of blocked pop-up tabs works in Firefox and unpacked Chrome/Edge, independently of the per-site pop-up switch. It considers only a new tab with a browser-reported opener and its first HTTP(S) navigation. Chrome/Edge require a failed navigation and native feedback identifying a Module Engine block rule. Firefox requires a native aborted navigation plus confirmation from the actual enabled static, dynamic and session rules that a matching block outranks all possible exceptions or redirects; disabled static rules are excluded. Firefox checks domain and common URL patterns conservatively: regex, initiator/party constraints, unfamiliar conditions, or an exhausted matching budget cannot establish a block and may prevent cleanup. Ambiguous tabs stay open while browser network filtering continues. Existing or pinned tabs, tabs that already received page content, ordinary blank tabs without a confirmed block, and tabs without an opener are preserved. A blocked link opened in a new tab can also be closed because opener metadata does not distinguish it from a script-created pop-up. Pending navigation and rule changes cancel cleanup. The activity log records successful closes. Candidates expire after ten seconds, are capped at 64, and are not restored after a background restart. Firefox needs no debugging preference or new permission. Chrome/Edge installations without native match feedback keep the tab open.

  • Flag suspected ads (popup switch, on by default): Module Engine watches requests that actually loaded (it never sees, and never flags, ones it blocked) and flags third-party servers that look like ads, for you to decide later. Signals: ad-like addresses (/ads/, banner, popunder, prebid, VAST), ad placement settings (zoneid=, placement, campaign), impression or click trackers, known ad-network script shapes, long random-looking script addresses, throwaway-looking domains (two words joined by a hyphen) loading scripts or frames, and on the page itself, frames in standard ad sizes from another site and elements labelled "Ad", "Sponsored" or 广告/廣告. Flags are grouped by exact server name in the Flagged for review table at the top of My lists, with the reasons, the page hosts they were seen on, a count and examples; Block adds that exact server to Custom Blocked Domains, Allow to Always Allowed Domains, Ignore stops flagging it, and Clear all flags empties the table. Nothing is blocked by a flag. Sibling hosts are conservatively treated as separate unless one is a parent of the other; this avoids merging unrelated shared-hosting tenants but may produce an extra harmless flag. Private tabs and tabs whose privacy status cannot be verified do not contribute flags. Flags are kept in local storage (up to 500 servers, the oldest dropped first) until you decide or clear them; only page hosts, server names, reason codes and short paths without query strings are stored, and nothing is sent anywhere. Paused sites and always-allowed servers are not flagged; the master switch and the popup switch turn flagging off. Pattern matching misses ads served from the same host scope or ordinary-looking addresses and can flag harmless files, which is why it only flags.

  • My lists (popup → My lists, or from the activity log): one page with tables for Always Allowed Domains, Custom Blocked Domains, Paused Sites and Pop-up and Redirect Blocking Sites, each with an add box and a remove button for every row, and a filter across all tables. Removing a row removes exactly that entry (the popup's Resume also removes a parent entry that covers the current site). A read-only table lists the hosts added from site checks, with the site each was found on and what it did.

  • Activity log (popup → Open activity log): a page listing recent blocked requests (time, site, blocked server and path, layer) and extension events (settings changes, failures, installs/reloads, skipped YouTube video ads), with a per-server summary showing which sites each blocked server appeared on. It keeps up to 1,000 entries in session storage, so it is cleared when the browser closes; Clear log empties it and Export JSON saves a copy. Query strings are not recorded, and nothing is sent anywhere. Blocked-request entries come from the browser's rule-match feed, which Chrome and Edge provide while Module Engine is loaded unpacked. Firefox 159.0.1 does not provide it (even with extensions.dnr.feedback enabled), so in Firefox the log lists events only and says so. The YouTube player-data filter runs in the page and does not report to the log.

  • On Fandom, cosmetic filtering also hides its ad wrappers after network blocking leaves them empty. This selector is restricted to Fandom hostnames and follows the existing cosmetic, site-pause and master settings.

  • On YouTube (youtube.com, its subdomains and youtube-nocookie.com), the ad layer removes known ad schedules (adPlacements, adSlots, playerAds) from recognized player data, including bounded nested responses and batches. The page filter runs at document start; changing another protection no longer temporarily unregisters it. If an ad still reaches a player marked as playing an ad, the fallback mutes/accelerates it and uses an available skip button or seeks to a finite, seekable end. It also notices newly inserted players and controls. Sound and speed are restored when the ad state ends, protection is paused, or the page is left; newer player/user changes are preserved. The activity log reports a skip only after a skip/seek attempt is followed by the ad state ending. Unknown/live durations are never sought. These checks cannot guarantee that every live YouTube ad format is recognized.

  • The YouTube cosmetic layer separately hides feed, search, sidebar, masthead and in-player overlay ad slots. Pausing YouTube updates the page filter's exclusions; turning off Ads unregisters it. These changes affect new documents: reload the extension in edge://extensions after updating this checkout, then reload open YouTube tabs. Existing page-world hooks cannot be removed by a settings change. In a YouTube embed on a paused parent site, the page filter still runs because it cannot see the parent page; the isolated fallback honors both frame and parent pauses.

Network log

Open Modules & scripts from the popup, then choose Network in the sidebar. It is also linked from My lists, Activity log and MCP. Select All browser traffic or one HTTP(S) tab and click Start new capture, then browse or reload the page you want to inspect. Refresh tabs updates the scope choices. Starting a new capture clears the previous log.

Rows show the observed URL, method, resource type, status, timing and error. Redirect hops have separate rows with the same browser request ID. Select a request for its timing, initiator origin, tab/frame, cache indication and redirect destination. If the browser omits the start event, the row says its coverage is partial and has no invented duration. HTTP 4xx/5xx responses are separate from network failures.

Filter by text, tab, type or result. Live view pauses table updates while capture continues; Stop ends recording. Clear discards retained entries without stopping capture. Export filtered JSON saves only the entries matching your current view. Results are paginated at 100 rows.

Capture starts off and uses session memory, with up to 2,000 entries or 2 MiB; older entries are discarded when either limit is reached. It stops after 30 minutes, when its owning Network page or selected tab closes, or when the background restarts. Another open Network page can review the retained log. Extension reload/update/disable or browser restart clears session storage. A storage failure stops capture and displays an error. Capturing is independent of the ad-blocking and userscript switches and does not change requests.

URL credentials, query strings and fragments are removed before retention. Headers, cookies, request bodies and response bodies are not recorded. Paths can still contain private information, so review an export before sharing it. Capture itself uploads nothing. The separate Captured network request metadata approval on MCP lets your connected agent read bounded, filtered copies. That scope starts unchecked; it cannot start, stop or clear capture. Your MCP client may retain returned metadata. See MCP network access.

MCP and Appearance are available in the sidebar. Sections switch within the same tab, preserving MCP approval, Network capture, editor drafts and scroll positions. The MCP sidebar indicator shows when it is connected and how many proposals await review. Back and Forward switch sections too. Closing or reloading the tab ends its MCP connection and capture; switching sections does not extend their 30-minute limits. Use a modified click if you intentionally want a separate tab.

Coverage is limited to browser-reported HTTP(S) traffic and WebSocket handshakes. It cannot show other Windows apps, WebSocket messages, response content or every browser/cache/blocked event. A failed request does not prove Module Engine blocked it; the available browser error is shown. Use Activity log for rule-match attribution where the browser provides it. Selected-tab capture excludes requests the browser attributes to a background context, including some GM HTTP requests; choose all-browser scope to inspect those.

Appearance

Choose Appearance in the sidebar of any Module Engine page. Each choice saves as you make it and applies at once to the popup and every open Module Engine page, including sections already open in the same tab.

  • Theme: System, the default, follows your device's light or dark setting and changes with it. Light or Dark keeps that theme whatever the device uses.
  • Accent colour: fills switches that are on, main buttons and the current page in the sidebar, and colours links and highlighted text. Pick one of seven presets, or use Custom colour for any colour; Lime is the default. Filled controls use your exact colour. Where needed, text and edges use a lighter or darker shade of the same hue: accent text keeps at least a 4.5:1 contrast ratio (WCAG AA) in both themes, and text on a filled button is dark or white, whichever reads better.
  • Success messages and switches use the accent, so the page tells you when a custom colour is close to the warning or error colours, or to a switch that is off.
  • Reset theme and colour returns to System and Lime. It leaves the website setting and its sites as they are.

Your choice is stored in this browser profile's extension storage and never leaves the computer. Each page also keeps a copy of the theme and accent in its local storage so it opens in the right theme straight away. If that copy is missing, for example after Firefox clears site data, a page can show the default theme briefly before your choice loads.

Dark websites

Turn on Use the dark theme on websites to give light websites a dark version whenever the theme is dark: always with Dark, while your device is dark with System, and never with Light. It is off by default, and open pages change as soon as you switch it or the theme. While it is off, websites are left exactly as they are.

  • How it looks: a page's colours are inverted with their hues kept, so a white page turns near-black and dark text turns light. Photos, video, canvases and embedded frames are turned back to their own colours. SVG images are treated as icons and follow the text colour. Modal dialogs and pop-overs are darkened too, and full-screen video shows its own colours.
  • Already-dark sites are recognised from their own colours and left alone, including sites that switch to their own dark theme after loading. Cookie notices and dialogs that dim the whole window are looked through, so they do not decide whether a site is dark. A page's own background counts more than a dark banner across part of the screen.
  • Sites that keep their own colours: turn off Dark website theme in the popup's This site section, or add a site under Sites that keep their own colours on the Appearance page. Each entry includes its subdomains and everything embedded in that site's pages. Turning the switch back on removes the entry that covers the site.

This is a filter-based dark mode, so it is an approximation, not each site's own design:

  • Strongly saturated colours in images and video can look slightly duller.
  • Background pictures set in a site's stylesheets are inverted.
  • Dark sections of a light page, such as a dark banner, turn light along with the rest of the page.
  • The dimming layer behind a cookie notice or a dialog brightens the page to grey instead of darkening it. Dialogs built with the HTML <dialog> element dim correctly.
  • Dark logos with transparent backgrounds can be hard to see.
  • Frames that Module Engine cannot run in, such as built-in PDF viewers, keep their light colours.
  • Busy pages may scroll less smoothly.

Add a site that looks wrong to the list. A page's first moment can still be light while the setting loads, and Windows contrast themes switch the website theme off. The element picker and the notices Module Engine shows on websites follow the page's colours.

Notification and install prompts

Under Filters → Prompt & button protection, the two prompt switches start on, including when upgrading an older installation:

  • Notification requests answers new page requests with denied and rejects the page's push-subscription prompt path with NotAllowedError. It also hides recognized English notification reminders, including “Click Allow to prove you are human” overlays with an Allow button.
  • Deceptive install prompts hides recognized English dialogs and fixed overlays asking you to install/update a codec, player, plug-in or browser extension to play, watch, download or continue. It requires both the claim and an install action. Ordinary inline download links, product pages, articles, warning text and unrelated dialogs are preserved by the conservative rules.

To allow prompts and button actions on a trusted site, turn off Prompt & button protection under This site in the popup, or add the hostname under My lists → Prompt and button exceptions. This exception includes subdomains and leaves ad blocking active. Removing an exception from My lists removes that exact row; enabling protection in the popup removes covering parent exceptions, as with the existing site-pause controls. A full site pause or the master switch also disables these protections. Prompt filtering is independent of Cosmetic Element Hiding.

Reload the website after changing notification protection, site exceptions, or reloading the extension. DOM hiding responds to settings immediately and restores owned changes; existing page API hooks last until the document is replaced. Closed native modals release their browser-managed backdrop, and cleanup repairs root scroll/pointer locks and inert main content while preserving unrelated dialogs and widgets.

This is a page guard and a conservative pattern filter, not a browser-wide permission policy or malware scanner. The notification hook starts at document start in HTTP(S) top pages and guards accessible same-origin iframe APIs when their realm is obtained or loaded. Cross-origin frames, workers, restricted browser pages and page attempts to evade/replace hooks are not guaranteed coverage. Already granted notification permissions and existing subscriptions are unchanged; revoke those in the browser's site settings if needed. Module Engine's optional GM.notification helper and its extension permission dialog remain separate.

Unknown wording, other languages, closed shadow roots and prompts inside protected content/form containers can be missed. Large or mutation-heavy pages can reach a bounded scan limit; that cleanup stops for the page while network ad blocking continues. No prompt text is stored or transmitted, no host is automatically labeled malicious, and downloaded files or operating-system install dialogs are not inspected. Validation uses authored offline fixtures, not live scam sites.

Deceptive play and download buttons

Filters → Prompt & button protection → Deceptive play/download buttons starts on, including on upgrade. Reload the extension and existing websites after installing this version. Later button-setting changes take effect in open pages without reloading.

Once the page has received its protection settings, it stops these recognizable actions before ordinary page click handlers and link navigation:

  • A Play/Download control inside an explicitly marked ad placement or a small nearby visible Ad/Advertisement/Sponsored label.
  • An external link covering a real video player (at least half of the video), including an empty link trapping the click. A player's own title, channel or "watch on" link over a strip of the video stays usable.
  • A Play control linking to an installer or script filename, such as .exe, .msi, .crx, .xpi or .ps1.

The brief notice explains the matching reason and lets clicks pass through it. It disappears automatically; the guard does not remove controls, lock scrolling, move focus or replay a blocked action. Ordinary software Download links, direct media links and player controls stay available unless they match one of the additional signals. A Download label or a third-party destination by itself is insufficient.

Use the per-site Prompt & button protection switch or My lists → Prompt and button exceptions for a site you trust. This shared exception also allows its notification/install prompts; existing exceptions cover the new button guard. Ad blocking remains active. The independent button switch, full site pause and master pause are also respected. Cosmetic hiding is independent, so a control can still be hidden by an ad filter after button protection is turned off.

Detection examines the action at input time, so later insertions, changed labels and accessible open shadow roots are covered. English action labels and play glyphs are recognized. This does not prove a destination malicious or a permitted download safe. Unmarked fakes, other wording/languages, closed shadow roots, video substitutes without a real video element, earlier page handlers, later rewritten destinations and deliberate evasion can escape detection. Manually entered URLs, context-menu navigation, hover actions and browser/OS install dialogs are outside this guard. It does not inspect downloaded bytes, use a remote reputation service or store/transmit clicked labels and destinations. Native desktop checks use authored local fixtures; live-site and touch-device coverage is unverified.

Custom request filters

Open My lists → Custom request filters → Edit network filters. One line describes one request rule; blank lines and ! comments are allowed. For example, these original fixtures use reserved .test addresses:

||cdn.example.test/sponsor/*$script,third-party,domain=news.example.test
@@||cdn.example.test/sponsor/needed.js|$script,domain=news.example.test

The first rule blocks matching scripts initiated by the chosen site or its subdomains; the second allows that specific request. domain= refers to the frame initiating a request, which can differ from the top page. Full site pauses take precedence. Reported-threat rules and explicit domain blocks take precedence over these request exceptions. Always Allowed overrides a custom request block. Turning off cosmetic filtering or individual bundled lists does not disable custom request filters; the master switch does.

Supported patterns are ||host^, ||host/path*, and absolute HTTP(S)/WS(S) URLs anchored with |. A final | requires an exact URL ending. Hostnames are normalized without stripping www; internationalized hosts are encoded, and paths must already be URL-encoded. Supported resource options are document, subdocument, stylesheet, script, image, font, object, xmlhttprequest/xhr, ping, media, websocket and other, including ~ exclusions. first-party/1p, third-party/3p, their negations, domain=site.test|~excluded.site.test, and match-case are supported. Without resource options, a rule includes document navigation. @@ allows matching requests, not an entire page.

The editor accepts at most 500 unique rules, 100,000 characters overall, 2,000 characters per rule, and 100 initiating-site entries per rule. These rules share the browser's dynamic-rule budget with domain lists. Regexes, scriptlets (which belong in custom hiding rules), redirects, parameter rewriting, remote includes, IPv6 hosts, bare global patterns and other unsupported options are rejected with a line number; the entire save remains unapplied. This is a bounded syntax subset, not a general uBO/EasyList importer.

Saved rules affect future requests; reload an affected page to revisit loaded resources. Saves use the existing transaction and browser readback. If another edit changed the stored text, the save is refused and the draft remains visible. Discard draft explicitly loads the current saved version, including deletions. Failed updates report errors and attempt to restore the previous configuration; a failed restore is surfaced as a protection error. Protection status is not inferred from a successful parse.

The Reported-threat evidence panel shows the list in use: the bundled files, or an installed signed update, which it checks again the same way. It also shows the update folder, the last check and its result, with a Check for updates button when the release names a folder, and holds the Stop blocking and warn when the evidence expires switch. After the expiry date it says whether the rules stay in use or the layer has stopped. The builder validates the source catalog and generates rules/threat-evidence.json with hashes of the exact rule and policy bytes. The viewer also checks each host against its compiled exact-host rule and verifies the expiry calculation. These checks detect mismatched artifacts; they do not authenticate a security publisher or establish a host's current reputation. Observation dates retain their source precision, including month-only dates. Threat hosts are inert, defanged text; only the approved publisher reports have links, and none are fetched automatically. Search filters these entries too. Missing, expired or unverified evidence does not appear as current active protection.

Permissions

Permission/access Purpose
declarativeNetRequest Browser-enforced static and dynamic blocking and site exceptions, including switching off bundled community rules that an updated list dropped.
storage Local settings, quarantined entries and failure status; flags, userscript source and per-script GM values in local storage; the activity log and short-lived picker sessions in session storage.
userScripts (optional) Register user-provided code through the browser's dedicated API after the user grants access. Scripts have explicit site matches, separate worlds and no general extension API access. The same access lets scriptlet filters start before a page's own scripts.
clipboardWrite (optional) Copy text or HTML for scripts granted a clipboard helper; never reads clipboard contents.
offscreen (optional, Chromium) Run the bundled clipboard and upload-progress helpers from a service worker. Firefox uses its background document instead.
webRequestBlocking (optional, Firefox) Stop userscript redirects before following them, so each destination can be checked against @connect. Also required for upload progress.
notifications (optional) Create and remove notifications owned by a granted script instance.
downloads (optional) Save bounded userscript HTTP responses, observe their completion and cancel their unfinished saves. Scripts cannot query general download history or open/delete files.
activeTab Identify the page when the toolbar popup is opened.
alarms Disable dated threat rules when their evidence expires, if you asked for that, and recheck after suspension. The same hourly recheck starts filter-list checks when they are due, and the daily signed-list check while Reported Threats is on and the release names an update folder.
webRequest Observe requests for suspected-ad reporting and userscript redirect destinations. Firefox's separate optional webRequestBlocking access can cancel owned userscript redirects.
declarativeNetRequestFeedback Local rule matching diagnostics where the browser exposes debug events; no telemetry. Omitted from Chrome and Edge store packages because their debug event is available only to unpacked extensions.
scripting + host access to all sites (<all_urls>) Register the bundled page scripts: src/blocking/youtube.js on YouTube while the ad layer is on, and src/blocking/popups.js on sites where pop-up blocking was turned on. Inject the packaged picker into the top frame when opened from the popup. Without userscript access, start a frame's scriptlet filters in its page world. The background also uses browser-provided tab/frame metadata to inject src/blocking/popups.js into that selected page's cross-origin child frames; it never trusts a page-supplied top hostname. Chrome injects scripts only where the extension has host access. The content script already runs on all sites, so this adds no new install warning; the background also uses existing host access for explicitly prepared userscript dependencies and granted GM HTTP requests. It checks native script identity, grants and @connect scope before starting those requests.
Content scripts on matching pages Insert and remove cosmetic CSS; this broad page access is needed by the current cosmetic feature. On YouTube it also mutes and skips a video ad that still starts playing. On Reddit it hides recognized app promotions and releases their interaction locks while Page hiding is enabled.

Cosmetic filtering

  • Generic Cosmetic Filters is enabled by default and can be switched off in the popup or My lists → Page hiding. It uses the existing local snapshots; no lists were downloaded for this upgrade. Native CSS handles elements added after page load without a repeated JavaScript scan.

  • Generic selectors are packaged as two stylesheets that the browser applies from the start of every HTTP(S) frame, so they normally hide before the page first paints. Each frame then receives only its site-specific rules. Switches, site pauses, hiding pauses and your own exceptions still reach open pages without a reload: the frame's content script revokes the stylesheets and takes the generic selectors that still apply from its settings reply. Limits of this approach:

    • The stylesheets match each frame by its own address. In a cross-origin frame of a paused page they apply until that frame's settings reply arrives, and are then revoked.
    • Saving a custom exception for a bundled generic selector, such as example.com#@#.ad-banner, moves that site off the stylesheets. Its frames receive generic selectors in their settings reply as before.
    • About:blank frames get no generic hiding, as before.
    • In Firefox, these stylesheets now win against a page's own !important display rule of equal specificity. Chrome and Edge still let the page's rule win.
    • Chrome and Edge previously ignored roughly the last 6,200 of the 14,409 generic selectors, because Blink drops the selectors after the first 8,192 simple selectors of one CSS rule. All of them now apply, as they already did in Firefox, so some extra elements may be hidden there.
    • Page code can remove the root attribute that revokes the stylesheets, much as it could remove the extension's style element.
  • Sites with hiding disabled restores hidden elements on a site and its embedded frames while ad, tracker, community and reported-threat network rules stay enabled. This is narrower than the existing full site pause. Entries cover their subdomains and can be removed individually in My lists.

  • Custom hiding rules accepts one site-scoped CSS or supported advanced rule per line, for example example.com##.sponsored-card. Use example.com#@#.sponsored-card to exempt that exact selector, including matching bundled selectors. Multiple sites and exclusions are supported: example.com,~shop.example.com##.sponsored-card. Custom rules require at least one positive site; site names retain www and are normalized to ASCII for IDNs. Empty lines and ! comments are allowed.

  • The editor validates CSS in the current browser before saving, reports the failing line, preserves unsaved drafts, and refuses to overwrite a newer save from another window. Limits: 500 rules, 100,000 text characters and 1,000 characters per selector. Saving an empty list clears it. Open tabs react to saves, removals, switches and cosmetic pauses. Changes use the existing serialized settings transaction and rollback path.

  • Generic and site selectors respect exact-selector exceptions and whole-host generichide / elemhide exceptions supported by the compiler. Excluded sites affect only the rule carrying that exclusion. generichide suppresses generic hiding; elemhide suppresses all cosmetic hiding on the matching frame, including custom rules. These exceptions never create network allow rules. Custom hiding otherwise remains available when Community lists is off.

  • Advanced Page Hiding is enabled by default and has its own switch in the popup and My lists. Supported operators are case-sensitive literal :has-text(text) / :-abp-contains(text), nested :has(...) / :-abp-has(...), and :upward(1) through :upward(10) or :upward(.container) within ten ancestors. For example, example.com##.label:has-text(Sponsored):upward(1) hides the label's parent. Quoted text supports escaped quotes and backslashes; regex text is refused. An operator must follow its CSS subject directly: descendant forms such as .content :has-text(Sponsored) are refused, because dropping the space would hide .content itself. #?# explicitly selects the advanced engine, with #@?# for exceptions. With ##, native CSS :has() stays in CSS when it contains no advanced operator.

  • Advanced blocking requires a positive site scope. Limits per rule: four nested levels and eight operators; literal text is limited to 200 characters. Sibling-relative queries, procedural selector lists, CSS suffixes after an advanced step and unsupported operators are refused. The compiler reports skipped entries instead of broadening them. Browser CSS validation checks every selector fragment before activation.

  • The runtime restores a container when it stops matching or filtering is paused. It owns a random marker attribute and one style element, preserving inline styles. Mutation bursts share one pending scan. Each pass allows at most 64 active rules, 5,000 selected candidates, 20,000 operations, 1,048,576 UTF-16 text units and 32 ms measured between operations. Native selector calls are synchronous and cannot be preempted, so 32 ms is not a hard wall-clock ceiling. A limit stops advanced hiding for that frame and restores its changes; CSS and network filtering continue. The activity log records the reason. Edit the rules, toggle Advanced Page Hiding off/on, or reload the page to retry. Repeated unrelated setting changes do not retry a suspended rule set.

Scriptlet filters

A scriptlet filter runs one of Module Engine's small built-in page scripts on the sites it names. Instead of hiding an element, it changes what the page's own JavaScript does: it stops an anti-adblock check, a pop-up or an ad request, or sets a value the page reads. The filters use uBlock Origin's syntax, so an existing filter works when it names a supported scriptlet.

  • Writing them. Add them to My lists → Custom hiding rules, one per line:
    • example.com##+js(set-constant, adsBlocked, false) runs a scriptlet on example.com and its subdomains. Several sites and exclusions work as for hiding rules: example.com,~shop.example.com##+js(...).
    • example.com#@#+js(set-constant, adsBlocked, false) cancels that exact call there; an alias counts as the same scriptlet. example.com#@#+js() turns every scriptlet off on that site.
    • Commas separate arguments. Write \, for a comma inside one, or quote the argument with ', " or backticks.
    • Patterns are literal text or a /regular expression/; where the table says so, a leading ! negates.
    • Every rule needs a site. The editor refuses an unknown scriptlet or a bad argument with its line number and saves nothing.
  • From lists. List updates and the bundled build convert scriptlet filters too. EasyList and EasyList China contain none; the bundled uBlock filters gives 7,178 scriptlet rules on about 16,000 sites, which run by default as each page loads (scriptletRules in rules/community-info.json counts them). Its filters that need a trusted scriptlet, one Module Engine does not have, or a name.* site are skipped and counted. A list's exception also cancels your own scriptlet, as list hiding exceptions do.
  • Switch. Scriptlet Filters in the popup and in My lists → Page hiding, on by default. They also stop with the master switch, Cosmetic Element Hiding, a site pause, a hiding pause and a list's $elemhide exception for the site. Changes reach pages loaded afterwards, so reload open pages.
  • When they start. My lists shows which applies:
    • With userscript access, your own scriptlet rules start before the page's own scripts. That is the optional permission the Userscripts module uses: Allow userscript access in My lists, and in Chrome and Edge also Allow User Scripts in the extension's details. Module Engine registers your rules with the browser for the start of every matching frame, in up to 32 groups of sites, so a page loads only its own group's rules.
    • Without it, and for the lists' rules always, each frame starts its scriptlets when it first asks for its hiding rules. That is usually before ad and anti-adblock scripts arrive from the network, but after the page's first inline scripts. A scriptlet that must act first can then miss, such as remove-node-text on an inline script.
    • The lists' rules are not registered because of what that cost in Chrome: registering uBlock filters' rules made every page load about 50 ms slower, and the first page after each change of the registrations (a site pause, a rule edit, a list update) took 1.5 to 3.5 seconds. To start one of them first on a site, copy it into your custom hiding rules.
  • Frames use the rules for their own site, as site hiding does. A paused top page turns scriptlets off in its frames too. With userscript access, a frame learns its top page from the browser's location.ancestorOrigins, which Chrome, Edge and Firefox 160 provide. A browser without it would run a cross-origin frame's own scriptlets. About:blank frames run none.
Scriptlet (aliases) Arguments What it does
set-constant (set) property path, value Fixes the property to true, false, null, undefined, '', noopFunc, trueFunc, falseFunc, throwFunc, []/emptyArr, {}/emptyObj or a whole number from −32767 to 32767. A path through objects the page creates later is followed. A property that already holds a value of another type is left alone.
abort-on-property-read (aopr) property path Reading the property throws, which stops the script reading it.
abort-on-property-write (aopw) property path Writing the property throws.
abort-current-script (acs, acis, abort-current-inline-script) property path, [script text pattern], [script address pattern] Reading or writing the property throws only inside a script whose text (or data: body) and address match.
json-prune properties to remove, [properties that must all be present], [stack pattern, !] Removes properties from data read by JSON.parse and Response.json(). Paths are space-separated names joined by dots; [] means every array item and * every property. Array items are removed without leaving gaps.
no-setTimeout-if (nostif, prevent-setTimeout, setTimeout-defuser) [callback pattern, !], [delay: n, min-max, min- or -max, !] A matching timer still starts but runs nothing. Give at least one argument.
no-setInterval-if (nosiif, prevent-setInterval, setInterval-defuser) as above The same for intervals.
no-requestAnimationFrame-if (norafif, prevent-requestAnimationFrame) callback pattern, ! The same for animation frames.
nano-setTimeout-booster (nano-stb, adjust-setTimeout) [callback pattern], [delay, default 1000, * for any], [factor, default 0.05, limited to 0.02–50] Multiplies a matching timer's delay, for example to skip a countdown.
nano-setInterval-booster (nano-sib, adjust-setInterval) as above The same for intervals.
addEventListener-defuser (aeld, prevent-addEventListener) [event type pattern], [handler pattern], option elements, <selector> (or window, document) A matching listener is not added. Give at least one pattern.
no-fetch-if (prevent-fetch) conditions, [response], [response properties] Answers a matching fetch() itself, so nothing is sent. Every space-separated condition must match: an address pattern, or name:value for method, body, mode, credentials, cache, redirect, referrer, referrerPolicy, integrity or keepalive; ! negates. The response is empty, or true (ten random characters), emptyObj, emptyArr, emptyStr or length:n / length:n-m. Response properties are JSON with ok, type and statusText.
no-xhr-if (prevent-xhr) conditions (method: or address), [response] The same for XMLHttpRequest.
no-window-open-if (nowoif, prevent-window-open, window.open-defuser) [address pattern, !] Refuses a matching pop-up; with no pattern, every pop-up. The page receives null, as when the browser blocks a pop-up. A delay and decoy are accepted but not used.
remove-attr (ra) attributes separated by |, [selector], [timing: asap, stay, complete] Removes the attributes from matching elements when the document is ready, and again as the page changes until it has loaded. asap also starts at once, complete waits for the load, and stay keeps watching while the page is open.
remove-class (rc) classes separated by |, [selector], [timing] The same for classes.
remove-node-text (rmnt) element name or #text, text pattern, options stay, 1 and quitAfter, <ms> Empties matching nodes as the page's parser adds them, until the document is ready. An inline script emptied before it runs does nothing, so this needs userscript access.
noeval (noeval-silent, silent-noeval) none eval() runs nothing.
noeval-if (prevent-eval-if) code pattern eval() runs nothing for matching code.
set-local-storage-item, set-session-storage-item key, value Sets the item to a fixed value: a whole number from −32767 to 32767, one of the words set-cookie accepts, true, false, null, undefined, '', {}, [], emptyObj, emptyArr or emptyStr. $remove$ deletes it.
set-cookie name, value, [path, default /, or none], options reload, 1 and dontOverwrite, 1 Sets a session cookie for the site to a whole number or a fixed word such as accept, accepted, yes, ok, necessary or dismissed, in any case. reload, 1 reloads once after the cookie changed.
alert-buster none alert() shows nothing; the message goes to the console.

Not supported, and refused or counted rather than approximated:

  • the trusted-* scriptlets, which take arbitrary values;
  • forms that would only log calls, such as ##+js(nostif) with no arguments;
  • the runAt, log and debug options;
  • scriptlets for every site (##+js(...) without one);
  • Adblock Plus #$# and AdGuard #%# snippets.

How they run:

  • Arguments are data. Each is compared with page values or used as a property name, CSS selector or fixed value. None is evaluated, fetched or turned into code.
  • The code is Module Engine's own. The scriptlets run in the page's own JavaScript world, as the page's scripts do. They reach no extension API, and a page can detect or work around them.
  • Aborted scripts stay quiet. Started at document start, an aborted script's error reaches neither the page's error handlers nor the console. Started late, an error handler the page set first can still see it in Chrome and Edge.
  • Origin. The names and arguments follow uBlock Origin's resource library and static filter syntax. The parser and scriptlets are original code.

Reddit app-promotion overlays

With Page hiding enabled, Module Engine recognizes English Reddit app prompts such as Get the best of Reddit in the app together with an app button inside a dialog or large fixed overlay. It hides the promotion and an associated decorative backdrop, closes native app modals, and releases their scrolling, pointer and main-content inertness locks. Late insertions and discovered open shadow roots are supported. Comments, inline discussions of the app, other websites, and separate login dialogs are preserved.

This uses the existing Page hiding switch, site hiding pause and full site pause; it does not require a userscript or new permission. Pausing restores the repair's changes while preserving newer page style edits. Reload the extension and Reddit tabs after installing this source update. In Edge, first load the repository at edge://extensions → Developer mode → Load unpacked.

The fix is verified against locally authored fixtures, not the live Reddit DOM in the screenshot. Different wording, closed shadow roots, unrelated overlays or page event handlers may need a separate targeted adjustment.

Visual element picker

  1. On an ordinary HTTP(S) page, open Module Engine and choose Pick an element to hide. Cosmetic filtering must be enabled for that site.
  2. Point to an element and click, or use Parent, Child, Previous, Next and Use element with the keyboard. Selection does not activate the link underneath.
  3. Review or edit the CSS selector and match count. Preview hides current matches temporarily; Restore preview, Pick again, Cancel or Escape restores them without overwriting inline styles.
  4. Choose Save hiding rule to persist the rule. Edit or remove it later in My lists → Custom hiding rules. A failed save keeps the draft open and reports the error.

The picker prefers a unique ID or a short tag/class selector, then a structural path if necessary. It does not derive selectors from page text, links or form values. Generated paths are limited to 16 ancestor levels and 1,000 characters. The preview accepts plain CSS matching 1–100 current elements; it refuses document roots, its own controls and unsupported selectors. DOM changes refresh the preview; saving checks the current matches again. Saved CSS can match additional elements added later. Changing site layouts or generated class names can require adjusting a rule. Advanced operators remain available through the text editor.

The picker operates in the top document. It can select an iframe or shadow host as a whole, but cannot pick elements inside another frame or a shadow root. Its controls use a closed shadow root; the isolated extension context keeps the draft and last validated selector, accepts native user edits, and rechecks that state when saving. Page scripts cannot replace a saved selector by rewriting a control before a genuine Save click. It restores temporary changes when cancelled, replaced, paused, expired, removed from the page or unloaded by navigation. It does not make a page trustworthy or prevent the page from modifying its own DOM.

Opening the picker creates a capability valid for ten minutes, held only in session storage (at most 20 recent sessions). Saving is tied to the browser-provided tab, top frame, URL and document ID when available; the hostname comes from that tab, including www. The background rechecks pauses, existing exceptions and editor limits, and appends to the latest saved text so concurrent edits are preserved. A capability cannot save a second, different selector. The general settings-writing interface remains restricted to extension pages. uBO's element-picker documentation informed the feature choice; this selector generator, overlay and authorization flow are original code.

This upgrade does not establish full uBO parity or superiority. Unsupported procedural operators, scriptlets other than the supported ones, network regex filters, some path-specific cosmetic exceptions and other unsupported list options remain skipped and counted in rules/community-info.json. Custom request filters are edited in My lists; the picker saves cosmetic CSS only. There is no network-request picker or temporary zapper. Filter lists and the reported-threat list update as described in controls and scope; generic hiding changes only with a new release. Streaming-ad and anti-blocker behavior varies by site; offline checks do not prove live YouTube/Twitch/Google coverage or anti-detection. uBO's procedural filtering documentation informed the earlier feature choice; the parser and runtime here are also original code.