Nvirya AdGuard Official Knowledge Base

Current Release: v11.7.0 | License: MIT | Execution Model: Userscript (@run-at document-start)

Nvirya AdGuard (displayed in the interface header as Nvirya AdGuard X) is an open-source userscript that filters known advertising elements, blocks unwanted pop-ups and automated cross-site redirects, mitigates stealth click-trap overlays, and provides interactive page-cleanup controls inside compatible mobile and desktop browsers.

This knowledge base explains how the script operates, what it can and cannot do within browser security boundaries, how to resolve common site compatibility issues, and how to submit actionable bug reports.

Who This Project Is For#

Nvirya AdGuard is designed for:

• Mobile browser users on iOS/iPadOS (such as Safari with the Stay userscript manager) and Android browsers that support userscript extensions or built-in script managers (such as XBrowser or Firefox/Chromium browsers with Tampermonkey or Violentmonkey).
• Desktop browser users who want page-level ad filtering, redirect confirmation, and an on-page element picker through a standard userscript manager.
• Users browsing ad-heavy media, news, or file-hosting sites where invisible click overlays, pop-unders, locked page scrolling, or unexpected external redirects frequently interrupt navigation.

How the Userscript Model Works#

Unlike a standalone application or a system-wide network filter, a userscript is a JavaScript file injected into web pages by a userscript manager.

When you load a web page matching *://*/*, your userscript manager injects Nvirya AdGuard at document-start (before most page scripts and DOM elements finish loading). From inside the page environment, the script:

1. Applies cosmetic CSS rules (<style data-nvirya-cosmetic>) and custom per-site rules (<style data-nvirya-site-rules>) to hide known ad containers and sponsored slots.
2. Monitors dynamic page changes using the browser's MutationObserver API to collapse newly inserted ad placeholders, orphaned dark backdrops, and transparent click-trap overlays.
3. Wraps selected page-level JavaScript APIs—including Window.fetch, XMLHttpRequest, Navigator.sendBeacon, and window.open—when the execution environment allows main-world script injection.
4. Renders an isolated control panel inside an open Shadow DOM container (<div data-nvirya-ui>) so you can pause protection, unlock scrolling, hide custom elements, or inspect third-party domains on the current page.

Realistic Expectations vs. Non-Guarantees#

Because Nvirya AdGuard operates strictly as a userscript inside the browser tab, its behavior depends on your browser engine, userscript manager, script injection timing, granted permissions, and how each website is built.

Prerequisites and Installation Assumptions#

To run Nvirya AdGuard v11.7.0, your environment must provide:

1. A compatible userscript manager that supports the userscript metadata block (@run-at document-start, @all-frames true) and the following @grant APIs:
   • GM_addStyle
   • GM_getValue and GM_setValue (falls back to window.localStorage per origin if unavailable)
   • GM_registerMenuCommand (optional, for browser toolbar menu shortcuts)
   • GM_xmlhttpRequest (used for update checks, remote host-list synchronization, and issue reporting; falls back to fetch where CORS allows)
   • unsafeWindow (used to bridge main-world protections where supported)
2. Verified script distribution URLs (from the script metadata header):
   • Standard Userscript Update & Download URL: https://raw.nvirya.com/adguard/nvirya-adguard.user.js
   • iOS / iPadOS Stay Callback URL: stay://x-callback-url/install?scriptURL=https%3A%2F%2Fraw.nvirya.com%2Fadguard%2Fnvirya-adguard.user.js

Note: Always install or update the script from the official distribution URL above. Because userscript managers differ across operating systems and app stores, follow your specific userscript manager's documentation for importing a .user.js URL.

Documentation Navigation#

Use the guides below to explore specific topics:

• How It Works — Understand the architectural differences between userscripts, browser extensions, and VPN/DNS filters, as well as how DOM filtering and JavaScript network hooks work in v11.7.0.
• Feature Guide — Learn how to use every control in the Overview, Settings, and About tabs, including the Quick Action Button, Hide Page Element picker, Connection Log, and External Link Confirmation modal.
• Known Limitations — Read detailed technical explanations of YouTube mobile ad handling delays, VPN/DNS filter interactions, Android CPU/battery considerations, and iOS Safari/WebKit restrictions.
• Troubleshooting Guide — Follow step-by-step recovery procedures for leftover dark overlays, Cloudflare/CAPTCHA loops, blocked download links, Google/Bing Translator issues, slow pages, and missed ads.
• Remote Rules and Advanced Configuration — Configure Sync from Remote URL for raw domain lists and export or import custom per-site CSS rules.
• Feedback and Issue Reporting — See exactly what diagnostic data is collected when submitting a report, how URL sanitization works, and how to submit clear bug reports or feature suggestions.
• Frequently Asked Questions (FAQ) — Quick answers to common questions about coverage, platform differences, updates, and site recovery.