1.0.0+beta.4+build14,15,16

• (iOS) This is HUGE! Advanced blocking now works on iOS. This means complex ads, trackers, popups, and other annoyances as you choose (like YouTube ads) are now blocked! Wooooo!!
• (All platforms) Scriptlets updated to latest master
• (All platforms) We now check if a scriptlet/extended css/css/script has been injected already on a page, preventing duplicate injections
• (iOS, macOS) Updated to a new icon on iOS & macOS. iOS now has a dark mode icon.

And probably much more. This was unfortunately off the top of my head since I wanted to get out the advanced blocking support for iOS. All info for files changed is between commits 9c2c5fe and cae7629.

All platforms are already available for testing on TestFlight. Have fun browsing!

1.0.0-beta.3+build8,9,10

AI Summary of the Release Notes Below

WebShield TestFlight Release Notes Summary

Major Update Overview

This is the biggest update to WebShield yet, introducing 55 new regional filter lists optimized for various languages worldwide. To fully benefit from these changes, users must reset the model via:
WebShield > Settings > Developer > “Reset Model”

This action will delete custom lists but will load the new optimized lists. Future updates will aim to reduce the need for resets through SchemaMigrationPlans and VersionedSchemas.

Key Changes & Fixes

Filter Lists & Blocking Enhancements
• 55 new filter lists added, improving coverage for billions of users (~80% of the internet population).
• Improved iOS ad-blocking, fixing issues with YouTube ads and content blocker reload failures.
• Experimental lists added for internal development and validation.
• Reworked filter list logic, enhancing speed, reliability, and preventing content blocking errors.
• Ability to search filter list metadata for better list management.

Performance & Stability
• Improved memory & CPU usage via fixing of interconnected issues.
• WebShield Advanced optimizations reduce crashes and improve script execution reliability.
• Chunking system refined to prevent site crashes when applying advanced blocking.
• Background page persistence tweaks to enhance YouTube ad-blocking (iOS workaround still needed).

UI/UX Improvements
• Sidebar now displays all categories for better navigation.
• Added a new Help UI view in the toolbar.
• Redesigned popup page for better user experience.
• New checker view alerts users if extensions are disabled on startup.
• Error notifier added after refreshing filters.

Known Issues & Workarounds
• Some iOS filter updates may fail due to Safari limitations (try refreshing filters multiple times).
• YouTube ad-blocking on iOS may require a Safari restart or opening a new tab before it takes effect.
• Advanced script injection on iOS is unreliable in tests, despite working in practice.

Important Notes for Users
• Reset your model to avoid blank screens when opening WebShield after updating.
• Manually refresh filter lists every 1–2 weeks until automatic updates are implemented.
• If you encounter bugs or issues, report them via TestFlight, GitHub Issues, or Discord.

Developer’s Notes
• The app is still in pre-release beta, so some issues remain.
• Schema migration and automatic updates will be implemented in future versions.
• The developer is taking a short break due to burnout but will continue fixing reported issues.
• Users are encouraged to contribute via donations, PRs, or spreading awareness to keep WebShield free and user-focused.

“Let’s make ad-blocking great on Safari and improve the web, one update at a time!” 🚀

My Release Notes: The Biggest Update to WebShield Yet

IMPORTANT (PLEASE READ THIS): To get some of the changes in this benefit (massive amount of new regional lists, new internal model representation) its best to go to:

• WebShield > Settings > Developer > “Reset Model”

This will do a “factory reset” and remove your custom lists and reset enabled lists, BUT it will also add the 55 new optimized lists for languages across the world. For 99.99% of people the default pre-loaded lists will be enough. I can’t think of a reason why you would want to add a list when the lists for WebShield are (now) optimized per platform for the extension, unless you’re adding a list for a niche case, like Bypass Paywalls Clean.

In the future I will try to prevent the impact on doing “factory resets” on model updates by allowing you to export/import your settings. I will also, more importantly, do SchemaMigrationPlans and VersionedSchemas. The only reason I’m not doing this now is because

(1) the app is in the 3rd pre-release of first beta and
(2) there are (so many) bugs & features I’m trying to rapidly fix and add

Thus given the context and stage of development, I feel like it is a permissible decision to recommend users to do a “factory reset” to gain the most up to date version of the model. If you are angered by this, please keep in mind that

(1) this project is in a pre-release beta stage and
(2) I do this for free and pay with my free time, this is a passion project; I'm not even paid for this and the work I put into it

My time and motivation is limited. I want to ship as fast as possible at this stage, and that may mean that in some instances your QoL won’t be as good as a fully stable released product.

I have tried my best to prevent random crashes, have a good UI, do things right the first time for the most part. If you are worried about data loss, you can create a text file of all your custom list urls (by clicking the view source button). I know that is tedious if you have many custom lists, and it is not them most optimal or convenient solution, but I’ve tried to add the most common lists as pre-loaded into the app. I’m sorry for any inconvenience, but until I implement a json-based export & import system, or an auto-magic model conversion service, this is the best we have right now. I pretty much burned out the past few days (& weeks) doing all of these changes, so please bear with me.

Changes:

• Added ~55 filter lists for regional languages, covering billions of native speakers and around ~80% of the internet population
• Fixed content blockers not reloading on iOS, and YouTube ads not being blocked on iOS (advanced blocking - scriptlet/extended css injection).
  • Essentially iOS now has iOS filters that shouldn’t cause (that many) content blocker errors when reloading.
  • If it causes an error try refreshing filters again. I tried it on my device and it seems to work. Try refreshing until you don’t see an error.
  • If it persists, depending on the error, it could be jetsam terminating the process (WebShield X where X is the category) for being over 40mb RAM.
• You can now see all categories in the sidebar
• Added more experimental lists, primarily for internal development to validate and verify WebShield’s content blocking capabilities.
  • As a by-product end users can use these lists to determine which parts of WebShield is working and which isn’t, although I wouldn’t do it unless you know what you’re testing, otherwise you will probably just be confused. When in doubt, ask!
  • For some reason the scriptlet/script/css injection doesn’t pass the automated tests, despite me using the exact same code AdGuard uses for the content script and despite the injections running without any noticeable errors. It’s very weird, I have to do more investigations because it’s very unreliable in terms of passing the automated tests. Everything else should work fine.
• Re-did the logic for refreshing filter lists; lists now write to disk first, then reload. Improving speed & efficiency, and preventing those errors when reloading content blockers mentioned above. This fixed filter lists (content blocking & advanced blocking) not working due to bad logic for writing & saving content blockers (as mentioned above).
• Added the ability to search the descriptions of filter list metadata
• The resulting changes & refactors should have improved memory & cpu usage or at least not made it worse, and made the program a bit more reliable. Currently the biggest issue is memory usage with WebShieldAdvanced, particularly when loading the rules, but eventually it (& all content blockers) seem to go down to 16kb at least. I need to do instrument profiling to see what’s happening with WebShield Advanced, but I’m pretty sure I already know what is happening, but that’s beyond the scope of these release notes.
• Changed some internal SwiftData model representations
• Temporarily removed the refresh indicator since it’s broken.
  • For now please remember that after “reloading the model” in WebShield > Settings > Developer, you have to do a refresh of your desired filter lists. In fact it’s good practice to do a refresh of your filter lists every now and then (every 1/2 a week) until automatic filter list updates are figured out. It will probably be a background task thing like Wipr 2. You still need to refresh after you toggle a list on or off to update the blocker json anyway.
• Added checker view to see if any extensions are disabled on app startup
• Added an error notifier after refresh of filters. I couldn’t test it enough as I would like, but I wanted to ship fast at this point. Yes, it’s weird, but no matter how hard I tried to evoke an error naturally through the UI doing operations like a user would, I couldn’t get it to get an error when refreshing lists and thus the error popup didn’t trigger. I had to manually trigger errors, and it worked fine. So I don’t know if a crash will occur, but I see it as highly improbable given that I try to prevent crashes in the first place. If it does, report it on testflight, on the GitHub issues, and I’ll try to fix it as fast as I can.
• Advanced scripts now work better due to injection working more reliably (we still have issues on iOS, but I believe that may be site specific?). We also are able to fetch the latest advanced blocking data instead of requiring users to enable/disable the advanced extension each time they refresh filters. I'm not even sure if that was an issue in the first place, but I added a redundancy check just in case.
• We pass most content blocking tests in AdGuard’s test suite. This is HUGE as it shows that our blocker reliably works now. The only tests we don’t pass are the ones mentioned above (extended css/css injection/scriptlet & script injection), despite no errors showing up in the console, using the same code as AdGuard, even trying with a plethora of different implementations to fix the problems. Very weird and its an issue I'll continue to look into.
• Added help UI view sheet in the toolbar
• Redid...

1.0.0-beta.0+build0

Join the TestFlight! https://testflight.apple.com/join/1t5HfEGS
Join the Discord: https://discord.com/invite/gQ4ygPKyur

Disclaimer (macOS popup)

I should state that when you run WebShield and load new sites you will get a popup asking if WebShield can "access other apps data". This is because WebShield stores the blockerList.json and advancedBlocking.json in a shared group container for WebShield. The popup is an intended macOS security design to prevent rogue apps from accessing other apps data. I'll try to fix this in the next release. I saw how wBlock fixed it, and I would prefer an alternative approach. For now you can either accept each popup dialog, or you can give WebShield full disk access. If you're worried if WebShield accesses other apps' data, don't fret, it doesn't. And if you don't trust me you can verify this by viewing the source code. Specifically the files FilterListProcessor (saving filter lists to blockerList.json and scriptlet/extended css injection to advancedBlocking.json) and ContentView (where we save an empty blockerList.json if nothing is selected). You can also see ContentBlockerEngine for when we fetch advanced blocking rules, and ContentBlockerRequestHandler for when we fetch normal Safari content blocking rules converted from filter lists.

TLDR: you will get a popup asking if WebShield can access app data. This is completely normal as WebShield is accessing the info for filter lists for the current site. You can disable this by giving WebShield full disk access. WebShield only accesses data from its group container.

Beta woes

Keep in mind that WebShield is in beta, and this is the first release candidate of the first beta release, so there will be bugs. Please report any bugs in the issues tab of this GitHub repository. For real-time discussion and support you can join the discord. If you want to use a more indexable and persistent format (for search engines) you can use these GitHub discussions.

macOS Only (iOS, iPadOS, visionOS builds to come)

This release is macOS only. In a future release (soon) I will add support for iOS, iPadOS, visionOS. All I need to do is change from Safari App Extension for WebShield Scripts to a Safari WebExtension.

wBlock vs WebShield

If you want to see the differences between wBlock & WebShield, take a look here (scroll down to the section on wBlock vs WebShield).

Donations

Please consider donating if you have the desire, means, and disposable funds to do so. I work on WebShield for free, in my free time, practically part time, paying with my time as a full time student. There's no such thing as free lunch, and that's the cost. By contributing financially you can also join WebShield+ (for as low as one time payment of 1 USD). You can also make a recurring payment. The more you contribute, the greater your voice will influence the project. I will also set up WebShield+ for people who contribute code or add to documentation, which will come soon.

Please only open issues if you find a bug with WebShield, not a broken website or filter list issues. Those go to the dedicated filter list's issue tracker.

Let's try to make ad blocking and the web better for everyone.

Happy belated new years as well

-- Arjun

Note: The code in this repository (as of writing) technically isn't the latest as I'm working on adding new features as described in the issue tracker right now. The code as of this release should be functionally the same as the release on TestFlight.