Feature Guide

This guide documents every user-facing feature, control, and keyboard shortcut present in Nvirya AdGuard v11.7.0. All UI labels below match the English interface strings defined in the script.

1. Quick Action Button (FAB) and Keyboard Shortcuts#

What it does#

The Quick Action Button is a floating shield icon (46×46 px) rendered inside an isolated Shadow DOM container (<div data-nvirya-ui>) in the top browser frame (window.self === window.top). It provides one-tap access to the Nvirya AdGuard X control panel and displays a color-coded status dot in its top-right corner:

• Green dot (data-state="ok"): Protection is active on the current site.
• Orange dot (data-state="warn"): Filtering is paused for the current session or the current domain is allowlisted.
• Gray dot (data-state="off"): Smart Shield (config.enabled) is turned off globally.

After 3,000 ms (3 seconds) of inactivity while the panel is closed, the button enters an idle state, sliding partially into the left or right screen edge (translateX(±58%) scale(0.92), opacity: 0.42). It automatically hides whenever a video or element enters fullscreen mode (fullscreenchange).

When to use it#

Use the Quick Action Button on mobile browsers where keyboard shortcuts are unavailable, or drag it vertically along either edge of the screen to keep it out of the way of site navigation bars. Your chosen side (l or r) and vertical ratio (y) are saved in storage (nvirya_x_fab).

How to activate it#

• Touch / Mouse: Tap or click the Quick Action Button. If the button is docked in its dimmed idle state on a touch screen, the first tap wakes it up (resetFabIdle) so you do not accidentally open the menu while scrolling; tapping it while awake opens the control panel.
• Keyboard Shortcut (Alt+A): Press Alt+A on any page to toggle the control panel open or closed, even if the Quick Action Button toggle is turned off in Settings.
• Userscript Manager Menu: Select Open Control Panel (Alt+A) from your userscript manager's extension menu.
• Closing the Panel: Tap the backdrop, tap the close (×) button, press Escape, or (on mobile screens ≤ 640 px wide) swipe the bottom sheet downward.

How to hide or recover it#

• Toggle Quick Action Button ("Automatically dock to the screen edge") off or on in Settings.
• If you hide the button on a mobile browser that does not expose GM_registerMenuCommand, you can still open the panel with an external keyboard (Alt+A) or by resetting script storage in your userscript manager.

2. Protection Summary and Weekly Activity#

Located at the top of the Overview tab:

• Mode Switch (This Page / All Time): Switches the four summary cards between current tab session counts (stats.session) and cumulative counts stored in nvirya_x_stats (stats.lifetime). Each card also displays the opposite mode's count in its subtitle (All Time: ... or This Page: ...).
• Counters:
  • Ads ("Cleaned"): Incremented when ad nodes are removed, ad scripts are neutralized, or video ads are handled.
  • Hidden Elements: Incremented when elements are hidden via [data-nvirya-hidden], disarmed click traps, or manual picker rules.
  • Pop-ups Blocked: Incremented when window.open calls or new-tab ad hijack clicks are blocked.
  • Trackers Blocked: Incremented when fetch, XMLHttpRequest, sendBeacon, <img>, or <script> requests to ad/tracker URLs are intercepted.
• Weekly Activity (Mon–Sun): Displays a 7-day bar chart of combined Ads + Hidden Elements counts for the current week (retaining up to 14 days of history in nvirya_x_weekly_history). Tap any past day column in the current week to inspect its count in the chart header.

3. Site Allowlisting and Session Pause#

Located under Overview → Quick Actions:

What happens when you pause or allow a site#

Calling either control triggers refreshProtection() → restorePageWhenDisabled() immediately without requiring a page reload:

1. Sets window.__NVIRYA_DISABLED__ = true and data-nvirya-disabled="1" on <html> so main-world fetch hooks pass requests through unmodified.
2. Reverts any anti-adblock modal hiding and scroll overrides (AntiAdblockEngine.revertAll()).
3. Stops active video ad listeners and restores original video volume/speed (stopVideoAdProtection()).
4. Disconnects the DOM MutationObserver and disables both <style data-nvirya-cosmetic> and <style data-nvirya-site-rules>.
5. Restores inline styles on disarmed click traps (state.disarmedNodes), removes [data-nvirya-hidden] attributes, and re-inserts nodes tracked in state.removedNodes back into their original DOM parents.

Limitation: Elements or scripts that were already blocked before execution at document-start require a page reload to execute their original initialization code.

You can also toggle session pause from your userscript manager menu via Turn off on this page (Temporarily) and Turn it back on this page.

4. Hide Page Element (Element Picker)#

What it does#

Hide Page Element ("Tap or swipe any unwanted element to hide it") launches an interactive visual selector with a blue highlight box, an element tag/class badge, and a floating bottom toolbar.

How to activate it#

• Open Overview → Quick Actions → Hide Page Element, or
• Select Select the element to block (Picker) from your userscript manager menu.

While the picker is active, window.open is locked down (state.pickerActive = true) and page click/touch events are intercepted in the capture phase so tapping an ad or link selects it instead of navigating away.

Toolbar controls and gestures#

Once you tap or click an element on the page, the picker builds an ancestor chain (buildPickerChain, up to 7 levels deep, stopping before <body> and <html>) and enables the toolbar:

• Depth Slider (Level {current}/{total}): Drag the horizontal range slider left or right to move between the selected child element (Level 1/...) and its parent containers.
• Expand: Steps one level up to the parent element (traversePicker(-1)).
• Narrow: Steps one level down to the child element (traversePicker(1)).
• Hide Element: Generates a unique CSS selector (makeSelector) for the highlighted element, asks for confirmation (`Hide this element?

{selector}), saves the rule to nvirya_x_site_rules[hostname]`, and hides the element immediately.

• Hide All ({count}): Appears only when makeSimilarSelector finds 2 or more elements on the page sharing the same tag and stable CSS classes. Hides all matching elements at once after confirmation (Hide all matching elements ({selector})?).
• Touch Swipe / Fling Gesture: On touch devices, once an element is highlighted, you can swipe/fling directly across the highlighted element (distance > 60 px or velocity > 0.4 px/ms). The element animates off-screen (triggerPickerFling) and is saved as a hidden rule without a confirmation prompt (unless it is part of a protected video player, which prompts: "This element is part of a video player. Hiding it may interrupt playback. Continue?").
• Cancel (or Escape key): Exits the picker without saving any changes.

Known limitations of the Element Picker#

• Websites that generate new random class names on every build (and lack stable id, data-testid, role, or aria-label attributes) may cause makeSelector to fall back to structural :nth-of-type(...) paths, which can stop matching if the site layout changes.
• You cannot select <body>, <html>, or Nvirya AdGuard's own UI elements.

5. Site Filter Rules#

Located under Overview → Quick Actions → Site Filter Rules ("Manage custom hidden elements on this site"):

• Displays a scrollable modal listing every custom CSS selector saved for the current hostname.
• Tap the red close (×) button next to any selector to delete that single rule (removeSingleRule) and immediately unhide matching elements on the page.
• To remove all custom rules for the current domain at once, go to About → Storage & Updates → Clear Site Rules ("Restore all manually hidden elements on this site").

6. Connection Log#

Located under Overview → Quick Actions → Connection Log ("Inspect and block third-party domains"):

• What it shows: Displays third-party hostnames recorded during the current page session (up to MAX_NET_BUFFER = 80 recent fetch, xhr, beacon, script, and img requests in networkRingBuffer, plus up to 300 static cross-origin <script>, <iframe>, and <img> elements scanned via scanStaticDomResources()), along with any domains you have previously custom-blocked.
• Controls:
  • Search bar (Filter domains...): Filters the domain list by hostname or sample URL.
  • Filter tabs (All / Blocked): Switches between all third-party domains and blocked domains only.
  • Block / Allow button: Tapping Block adds the domain to nvirya_x_custom_blocked, updates <style data-nvirya-cosmetic>, and immediately hides or removes matching DOM nodes on the page (purgeCustomBlockedDom). Tapping Allow removes a custom-blocked domain.
  • Built-in badge: Domains blocked by Nvirya AdGuard's built-in filter lists (RE_AD_HOST, RE_GAMBLING_HOST, or RE_SUSPECT_TLD) display a disabled Built-in button; to allow a built-in domain on a specific website, use Pause for This Session or Allow This Site.
  • Clear Session Log: Clears the in-memory session request list (networkRingBuffer).

7. Clean Leftover Frames#

Located under Overview → Quick Actions → Clean Leftover Frames ("Collapse empty ad placeholders immediately"):

• Queries up to 200 elements matching [id^="google_ads_"], ins.adsbygoogle, iframe[src*="googlesyndication"], iframe[src*="doubleclick"] (skipping protected video players) and marks them with data-nvirya-hidden="clean".
• Runs handleAntiAdblock() (AntiAdblockEngine.scanRoot) to detect and hide any visible anti-adblock walls or leftover modal backdrops, then shows the toast Cleaned leftover frames.

8. Preview Original Page (3s)#

Located under Overview → Quick Actions → Preview Original Page (3s) ("Temporarily reveal hidden elements for 3 seconds"):

• Temporarily disables both <style data-nvirya-site-rules> and <style data-nvirya-cosmetic>, closes the control panel, and shows the toast Previewing original page (3s)....
• After exactly 3,000 ms, re-enables both stylesheets and displays Filters restored.
• Limitation: This reveals elements hidden via CSS ([data-nvirya-hidden] and custom selectors), but does not re-create DOM nodes that were completely removed from the document tree (removeTrackedAdNode) or re-run blocked scripts. To test a page with all removed nodes restored, use Pause for This Session.

9. Unlock Page Scroll#

Located under Overview → Quick Actions → Unlock Page Scroll ("Restore scrolling locked by hidden overlays"):

• Runs unlockPageScroll() and forces overflow: auto !important and overflow-y: auto !important on document.documentElement (<html>) and document.body (<body>), while resetting position: fixed to static !important if applied to those root elements.
• Use this whenever a page refuses to scroll after an overlay, cookie banner, or ad modal disappears.

10. Undo (Ctrl+Z)#

Located under Overview → Quick Actions → Undo (Ctrl+Z) ("Restore the most recently hidden element"):

• How to activate: Tap Undo (Ctrl+Z) in the panel, or press Ctrl+Z (or Cmd+Z on macOS/iPadOS) when the control panel and Element Picker are closed and your cursor is not inside an <input>, <textarea>, or contenteditable field.
• How it works (undoLast):
  1. First checks if you have any custom site rules in state.siteRules[hostname]. If so, it pops the most recently added rule, updates storage, refreshes <style data-nvirya-site-rules>, removes data-nvirya-hidden from matching nodes, and displays Restored: {selector}.
  2. If no custom site rules exist for the current hostname, it pops the most recently removed DOM node from state.removedNodes (capped at 200 entries) and re-inserts it into its original parent node (Element restored).
  3. If both stacks are empty, it displays Nothing to undo.

11. Settings Tab Controls#

In the Settings tab, you can customize appearance, language, and protection modules:

• Theme (Auto | Light | Dark): Controls the color scheme of the Shadow DOM control panel and modals (can also be toggled via the sun/moon icon in the panel header).
• Language (Auto | EN | VI | 中文): Switches all UI labels, toasts, and modal prompts between Automatic browser locale detection, English (en), Vietnamese (vi), and Simplified Chinese (zh-CN).
• Protection Switches:
  • Smart Shield ("Block pop-ups, redirects & invisible traps"): Master toggle that controls enabled, popupProtection, redirectProtection, and cosmeticFiltering together.
  • Media Guard ("Optimize video players & auto-skip ads"): Controls playerProtection (default: On). Protects HTML5 video players from accidental removal, enables initYouTubeShield() on YouTube, and runs scheduleVideoAdScan() to skip/accelerate detected video ads.
  • Deep Network Filter ("Strictly block tracking & analytics domains"): Controls strictMode (default: Off). When enabled, blocks third-party analytics/tracking domains matching RE_TRACKER (such as Google Analytics, Hotjar, Mixpanel, Clarity, Segment, Amplitude) in fetch/XHR/sendBeacon and lowers the DOM heuristic threshold so single-signal ad candidates (signals >= 1) are hidden.
  • Quick Action Button ("Automatically dock to the screen edge"): Shows or hides the floating shield button (showFloatingButton).
  • Anti-Adblock Bypass ("Neutralize anti-adblock walls on news sites"): Controls antiAdblock (default: On where supported). Automatically disabled on iOS WebKit when checkBypassSupport() detects that main-world script injection is unavailable.

12. Redirect Protection and External Link Confirmation#

When Smart Shield (redirectProtection and popupProtection) is active:

• Automated Redirect Blocking: Blocks unprompted cross-site location.href, location.assign, location.replace, window.navigation.navigate, form.submit(), synthetic dispatchEvent(new MouseEvent('click')), and malicious cross-origin <meta http-equiv="refresh"> redirects during early page load or without user activation.
• Redirect Link Unwrapping: Automatically unwraps tracking redirect parameters (?url=, ?to=, ?target=, ?dest=, ?redirect=, etc., including Base64-encoded URLs) on trusted user clicks outside search engines.
• External Link Confirmation Modal: Displays a confirmation dialog showing the destination hostname before opening untrusted cross-site links in a new tab (target="_blank"), links with redirect/tracking hops, or suspicious download redirects.