revisit middle mouse click behavior

* deprecate middlemouse.contentLoadURL since its default
* add browser.tabs.searchclipboardfor.middleclick to prevent clipboard leaks to search engines by mistake

.gitlab-ci.yml

@@ -0,0 +1,6 @@
+stages:
+  - dummy
+dummy-job:
+  stage: dummy
+  script:
+    - echo "Hello, world!"

.gitlab/issue_templates/Default.md

@@ -0,0 +1,26 @@
+### pre-requisites
+
+<!--
+
+if you ignore the pre-requisites and the template the issue might be closed.
+issues that have the `provide info` label need user input or they will be quarantined after a week,
+and closed after ten days.
+
+suggestions are appreciated in the form of merge requests or alternatively well documented issues.
+
+make sure you are in the right repository:
+https://librewolf.net/docs/faq/#i-have-a-problem-where-do-i-open-a-new-issue
+
+-->
+
+- [ ] I've read and followed the [contribution guidelines](https://librewolf.net/docs/faq/#do-you-have-any-contribution-guidelines);
+- [ ] I've reproduced the issue in a new LibreWolf profile;
+- [ ] I've checked that the problem is not present in a stock Firefox profile;
+
+### details
+- browser version & OS:
+- steps to reproduce:
+- expected result:
+- actual result:
+- console errors and warnings:
+- others:

README.md

@@ -9,10 +9,12 @@ we encourage users to find **their own setup** and to use our default configurat
 - [faq](https://librewolf.net/docs/faq/): for any question you might have, and to help you creating your own pref file.
 - [all releases](https://gitlab.com/librewolf-community/browser).
 - [issue tracker](https://gitlab.com/librewolf-community/settings/-/issues).
+  - if you ignore the pre-requisites and the template the issues might be closed.
+  - issues that have the `provide info` label need user input or they will be quarantined after a week, and closed after ten days.
 - find us on [gitter](https://gitter.im/librewolf-community/librewolf) / [matrix](https://matrix.to/#/#librewolf:matrix.org) / [reddit](https://www.reddit.com/r/LibreWolf/) / [lemmy](https://lemmy.ml/c/librewolf).
 
 ## Notes and thanks
 - this repository benefits from the knowledge and research provided by [arkenfox](https://github.com/arkenfox), so special thanks to the project.
-we do not use arkenfox's user.js but we try to keep up with it, and we also consider it a great resource for users who want to find their own setup.
-- some of the older prefs in this project were taken from [pyllyukko](https://github.com/pyllyukko/user.js/) and many more were investigated on [bugzilla](https://bugzilla.mozilla.org/home);
+we do not use arkenfox's `user.js` but we try to keep up with it, and we also consider it a great resource for users who want to find their own setup.
+- many thanks to the firefox team and to the people working on [bugzilla](https://bugzilla.mozilla.org/home);
 - thanks to the whole LibreWolf community and to all the contributors of this repo.

docs/Changelog.md

@@ -1,6 +1,457 @@
 This changelog will be used from now on to document changes in a precise manner, with a list of changes for each setting version.
 Setting versions are documented using the pref `librewolf.cfg.version`, available in about:config.
 
+# 7.7
+
+**base librewolf version**: 115.x
+
+**References**:
+- https://gitlab.com/librewolf-community/settings/-/issues/262
+
+#### Added preferences
+
+```
+defaultPref("browser.urlbar.suggest.weather", false);
+defaultPref("extensions.quarantinedDomains.enabled", false);
+```
+
+# 7.6
+
+**base librewolf version**: 111.x - 114.x
+
+**References**:
+- the prefs added in the `LOGGING` section are off by default in the official Mozilla builds, so we are just acting like Firefox here;
+
+#### Removed preferences
+
+```
+defaultPref("browser.contentblocking.report.monitor.enabled", false); // default
+```
+
+#### Changed preferences
+
+```
+defaultPref("app.support.baseURL", "https://support.librewolf.net/");
+```
+
+#### Added preferences
+
+```
+pref("browser.dom.window.dump.enabled", false);
+pref("devtools.console.stdout.chrome", false);
+```
+
+# 7.5
+
+**target commit**: from 71a20c6fff90e7fbcb216f1d644ca1b40b32b8e2 to 6fe09c63cbfb83ebfb6a17f5e624248f2501b97e
+
+**base librewolf version**: 109.x and 110.x
+
+**References**:
+
+- thumbnails are only used in privileged code to populate New Tab Page and Ctrl+Tab previews.
+- the startup blank window doesn't break anything and the perceived performance boost is irrelevant on modern hardware.
+- reset popup events to default as it's mostly a non-issue.
+
+#### Removed preferences
+
+```
+defaultPref("browser.pagethumbnails.capturing_disabled", true);
+defaultPref("browser.startup.blankWindow", false);
+defaultPref("dom.popup_allowed_events", "click dblclick mousedown pointerdown");
+```
+
+# 7.4
+
+**target commit**: b0d277a77b36e3bcc5c0f7a1b0eca7a54a388d9d
+
+**base librewolf version**: 108.x
+
+**References**:
+
+- win7/8.x don't need this pref thanks to Firefox's own implementation of mDNS.
+
+#### Removed preferences
+
+```
+defaultPref("media.peerconnection.ice.no_host", true); // don't use any private IPs for ICE candidate
+```
+
+# 7.3
+
+**target commit**: from 9395f5c0e061250acbcbcb523d2270d57136d411 to 240e184b785e4e46c09ca6881111f7c2d4d31a3f
+
+**base librewolf version**: 107.x
+
+**References**:
+
+- mixed content is already covered by HTTPS-only-mode;
+- [dom.disable_beforeunload is no longer necessary](https://github.com/arkenfox/user.js/issues/1575);
+- [beacon API is fine](https://gitlab.com/librewolf-community/settings/-/issues/229);
+- [Firefox Vew pref was removed in previous commit](https://gitlab.com/librewolf-community/settings/-/commit/9395f5c0e061250acbcbcb523d2270d57136d411), adding reference to the changelog;
+
+#### Removed preferences
+
+```
+defaultPref("security.mixed_content.block_display_content", true); // block insecure passive content
+defaultPref("dom.disable_beforeunload", true);
+defaultPref("dom.disable_open_during_load", true); // default
+defaultPref("browser.tabs.firefox-view", false);
+pref("beacon.enabled", false);
+```
+
+# 7.2
+
+**target commit**: from 7211e954b82da3cde5c5cf2d613fe1f84288e635 to eb51b4785e5b67fc388bcbd06a8324d5a54f5850
+
+**base librewolf version**: 106.x
+
+**References**:
+
+- hide Firefox View til reviewed, see https://gitlab.com/librewolf-community/browser/source/-/issues/78;
+- hotfix for syntax error;
+
+#### Removed preferences
+
+```
+defaultPref("browser.ssl_override_behavior", 1); // deprecated
+```
+
+#### Added preferences
+
+```
+defaultPref("browser.tabs.firefox-view", false);
+```
+
+# 7.1
+
+**target commit**: 33e1ec1cb97d1f16a696057fe9007ae8391def6b
+
+**base librewolf version**: 106.x
+
+**References**:
+
+- change most `lockPref()` to `pref()` or `defaultPref()`, see https://gitlab.com/librewolf-community/settings/-/issues/204;
+- offline autodetection is mature enough and it is used by some APIs;
+- if someone wants to get the mozilla extension for USB debugging, that's fine.
+
+#### Removed preferences
+```
+defaultPref("network.manage-offline-status", false);
+defaultPref("devtools.remote.adb.extensionURL", "");
+defaultPref("devtools.chrome.enabled", false); // default
+```
+
+# 7.0
+
+**target commit**: from ed9334d258d20830deafe1a02b87b0cea678236d to 1bdfd333e31c3d119c0bf5506a56b2026ead3583
+
+**base librewolf version**: 105.x
+
+**References**:
+
+- [enable APS](https://github.com/arkenfox/user.js/issues/1530#issuecomment-1242850653);
+- trim unnecessary or default NTP prefs, then tidy existing ones;
+- stick to default session restore interval for writes;
+- remove a bunch of default prefs that have been that way for the longest;
+- offer accessibility by default;
+- remove hardcore svg security pref since CVEs are very old and irrelevant, see [this discussion](https://github.com/arkenfox/user.js/issues/1529);
+- improve [autoplay behavior](https://gitlab.com/librewolf-community/settings/-/issues/213).
+
+#### Added preferences
+```
+defaultPref("privacy.partition.always_partition_third_party_non_cookie_storage", true);
+defaultPref("privacy.partition.always_partition_third_party_non_cookie_storage.exempt_sessionstorage", false);
+```
+
+#### Removed preferences
+```
+defaultPref("browser.newtab.preload", false);
+lockPref("browser.newtabpage.activity-stream.feeds.discoverystreamfeed", false);
+lockPref("browser.newtabpage.activity-stream.discoverystream.enabled", false);
+lockPref("browser.newtabpage.activity-stream.feeds.snippets", false); // default
+lockPref("browser.newtabpage.activity-stream.feeds.system.topstories", false);
+defaultPref("browser.sessionstore.interval", 60000); // increase time between session saves
+defaultPref("network.http.windows-sso.enabled", false); // default
+defaultPref("privacy.partition.serviceWorkers", true); // default v105+
+defaultPref("accessibility.force_disabled", 1); // block accessibility services
+lockPref("toolkit.telemetry.shutdownPingSender.enabledFirstSession", false); // default
+lockPref("toolkit.telemetry.reportingpolicy.firstRun", false); // default
+defaultPref("network.http.referer.XOriginPolicy", 0); // default
+lockPref("browser.safebrowsing.passwords.enabled", false); // default
+lockPref("browser.safebrowsing.provider.google4.dataSharing.enabled", false); // default
+defaultPref("gfx.font_rendering.opentype_svg.enabled", false); // disale svg opentype fonts
+defaultPref("media.autoplay.blocking_policy", 2);
+```
+
+# 6.9
+
+**target commit**: 49a705f835e1438372fbdf1a779fbc5846212a68
+
+**base librewolf version**: 104.x
+
+**References**:
+- autofill prefs have been replaced in a migration, we now only keep the bare minimum;
+
+#### Removed preferences
+```
+defaultPref("browser.fixup.alternate.enabled", false); // default v104+
+defaultPref("browser.urlbar.dnsResolveSingleWordsAfterSearch", 0); // default v104+
+defaultPref("extensions.formautofill.available", "off"); // deprecated
+defaultPref("extensions.formautofill.creditCards.available", false); // deprecated
+defaultPref("extensions.formautofill.heuristics.enabled", false);
+```
+
+# 6.8
+
+**target commit**: 381cbed42c98d2376faf7e4ec449623bb99b0be1
+
+**base librewolf version**: 103.x
+
+**References**:
+- [geoclue](https://github.com/arkenfox/user.js/issues/1504);
+
+#### Added preferences
+```
+defaultPref("geo.provider.use_geoclue", false); // [LINUX]
+```
+
+#### Removed preferences
+```
+defaultPref("network.cookie.cookieBehavior", 5); // default
+```
+
+# 6.7
+
+**target commit**: from e505ddbf0242aec1017a565a74ff9ff5aa458fe5 to 02212c3f44e7aa68b22c8febd9158580d7e4b74f
+
+**base librewolf version**: 103.x
+
+**References**:
+- the cookie lifetime policy pref has been deprecated, see https://gitlab.com/librewolf-community/settings/-/issues/199;
+- stop disabling IPv6, see https://gitlab.com/librewolf-community/settings/-/issues/96;
+- discussion about domain guessing is available at https://gitlab.com/librewolf-community/settings/-/issues/197.
+
+#### Removed preferences
+```
+defaultPref("network.cookie.lifetimePolicy", 2); // deprecated
+defaultPref("network.dns.disableIPv6", true);
+```
+
+#### Unlocked preferences
+```
+defaultPref("browser.fixup.alternate.enabled", false); // default v104+
+```
+
+# 6.6
+
+**target commit**: from bc16f4f14185e8791d819a69b7d798082ace67f8 to c983fcc8bea8fab31265bc345217b59ce5128de2
+
+**base librewolf version**: 102.x
+
+**References**:
+- sha1 certificates: https://bugzilla.mozilla.org/1767489 and https://bugzilla.mozilla.org/1766687.
+- trimming only applies to http websites so it's very minimal.
+- crlite: https://bugzilla.mozilla.org/show_bug.cgi?id=1773371, we can stick to default 3 till v103, then the value will be changed to 2 which is the best possible if mozilla feels like it's ready usability wise.
+- add more entries to the native query stripping list, to [get in line with brave](https://github.com/brave/brave-core/blob/master/browser/net/brave_site_hacks_network_delegate_helper.cc).
+- `services.settings.server` can now be used as a pref, see: https://gitlab.com/librewolf-community/browser/source/-/merge_requests/37
+
+#### Added preferences
+```
+defaultPref("services.settings.server", "https://%.invalid") // set the remote settings URL (REMOTE_SETTINGS_SERVER_URL in the code)
+```
+
+#### Removed preferences
+```
+defaultPref("security.pki.sha1_enforcement_level", 1); // default
+defaultPref("browser.urlbar.trimURLs", false);
+defaultPref("security.pki.crlite_mode", 3); // default
+defaultPref("security.OCSP.enabled", 1); // default
+```
+
+#### Changed preferences
+```
+defaultPref("privacy.query_stripping.strip_list", "__hsfp __hssc __hstc __s _hsenc _openstat dclid fbclid gbraid gclid hsCtaTracking igshid mc_eid ml_subscriber ml_subscriber_hash msclkid oft_c oft_ck oft_d oft_id oft_ids oft_k oft_lk oft_sk oly_anon_id oly_enc_id rb_clickid s_cid twclid vero_conv vero_id wbraid wickedid yclid");
+```
+
+# 6.5
+
+**target commit**: b10dcbdd84e63787c4f2f6d34d41724b437df5be
+
+**base librewolf version**: 101.x
+
+**References**:
+- query stripping is now [part of strict mode](https://hg.mozilla.org/mozilla-central/rev/9d9425eb1ded).
+- session cookie prefs are useless given that we sanitize on close, [more details at arkenfox](https://github.com/arkenfox/user.js/pull/1443/commits/3207478033fefc19e933dab4eef6445125341ec4).
+- fission has been a default for the longest now.
+
+#### Removed preferences
+```
+defaultPref("privacy.query_stripping.enabled", true);
+defaultPref("network.cookie.thirdparty.sessionOnly", true);
+defaultPref("network.cookie.thirdparty.nonsecureSessionOnly", true);
+defaultPref("fission.autostart", true);
+```
+
+# 6.4
+
+**target commit**: eea09ca07333dc166213fa9c873e4916d979e97f
+
+**base librewolf version**: 100.x
+
+**References**:
+- hide Firefox Focus promo in private tabs.
+- double checking revoked certificates with both CRL and OCSP allows to detect false positives and it is also [the default](https://hg.mozilla.org/mozilla-central/rev/a6ba7b4ee17).
+- [clearOnShutdown prefs now respect exceptions](https://github.com/arkenfox/user.js/issues/1441) so we can tick all boxes in that UI as well.
+
+#### Added preferences
+```
+lockPref("browser.promo.focus.enabled", false);
+defaultPref("privacy.clearOnShutdown.offlineApps", true);
+```
+
+#### Changed preferences
+```
+defaultPref("security.pki.crlite_mode", 3); // prev 2
+```
+
+#### Removed preferences
+```
+defaultPref("privacy.clearOnShutdown.cookies", false);
+```
+
+# 6.3
+
+**target commit**: e84fc950bfd7c3542cb974e9d545b9b8e18c010d
+
+**base librewolf version**: 99.x
+
+**References**:
+- Fixes the uBlock Origin installation URL
+
+# 6.2
+
+**target commit**: ac95f5195ed82ca6bcec48acf9d1241e3c683b25
+
+**base librewolf version**: 99.x
+
+**References**:
+- vpn pref was set to the wrong value by mistake.
+- offscreencanvas cannot be read back using JS, plus it is being tracked upstream. see [this comment](https://github.com/arkenfox/user.js/issues/1418#issuecomment-1093390017), which solves doubts from 6.1 changelog.
+
+#### Removed preferences
+```
+defaultPref("gfx.offscreencanvas.domain-enabled", false);
+```
+
+#### Changed preferences
+```
+lockPref("browser.vpn_promo.enabled", false);
+```
+
+# 6.1
+
+**target commit**: 465257e5993893cd7896ef1533d37e245f206fb9
+
+**base librewolf version**: 99.x
+
+**References**:
+- csp pref has been deprecated.
+- quicksuggest prefs are redundant as it has a master switch. the master switch is now force applied on each restart of the browser.
+- do not whitelist offscreencanvas for now, we need to first check how it is tied to the "normal" canvas.
+
+**Notes**: using the vpn pref should allow us to get rid of one patch.
+
+#### Added preferences
+```
+lockPref("browser.vpn_promo.enabled", true);
+defaultPref("gfx.offscreencanvas.domain-enabled", false);
+```
+
+#### Removed preferences
+```
+lockPref("security.csp.enable", true); // enforce csp, default
+lockPref("browser.urlbar.suggest.quicksuggest.nonsponsored", false);
+lockPref("browser.urlbar.suggest.quicksuggest.sponsored", false);
+lockPref("browser.urlbar.quicksuggest.dataCollection.enabled", false); // default
+lockPref("browser.urlbar.quicksuggest.scenario", "history");
+```
+
+#### Changed preferences
+```
+pref("browser.urlbar.quicksuggest.enabled", false);
+```
+
+# 6.0
+
+**target commit**: 0822d491d2b377b5cd7f0429cee5aa916538fa50
+
+**base librewolf version**: 98.x
+
+**References**:
+- we are going to force history to custom mode and hide the UI for always on PB mode, a bunch of pointers are collected in [this MR](https://gitlab.com/librewolf-community/browser/source/-/merge_requests/21).
+- [handlers prefs are deprecated](https://bugzilla.mozilla.org/show_bug.cgi?id=1733497).
+- for OCSP see [this issue](https://gitlab.com/librewolf-community/settings/-/issues/150).
+
+#### Added preferences
+```
+pref("privacy.history.custom", true);
+pref("browser.privatebrowsing.autostart", false);
+defaultPref("browser.preferences.moreFromMozilla", false); // hide about:preferences#moreFromMozilla
+defaultPref("security.OCSP.require", true); // set to hard-fail
+```
+
+#### Removed preferences
+```
+/** [SECTION] HANDLERS
+ * remove the default handlers for several tipe of files and services.
+ */
+lockPref("gecko.handlerService.schemes.mailto.0.uriTemplate", "");
+lockPref("gecko.handlerService.schemes.mailto.0.name", "");
+lockPref("gecko.handlerService.schemes.mailto.1.uriTemplate", "");
+lockPref("gecko.handlerService.schemes.mailto.1.name", "");
+lockPref("gecko.handlerService.schemes.irc.0.uriTemplate", "");
+lockPref("gecko.handlerService.schemes.irc.0.name", "");
+lockPref("gecko.handlerService.schemes.ircs.0.uriTemplate", "");
+lockPref("gecko.handlerService.schemes.ircs.0.name", "");
+```
+
+#### Changed preferences
+```
+defaultPref("security.OCSP.enabled", 1);
+```
+
+# 5.5
+
+**target commit**: 0fc1ff53c99379d9d4625de65ea51287d57a0a3a
+
+**base librewolf version**: 97.x
+
+**References**:
+- showing the insecure connection text is redundant as there's already the lock UI for http websites.
+- `browser.places.speculativeConnect.enabled` controls speculative connections for bookmarks and will be fully effective only once we hit v98.
+- we will no longer disable history but we'll clear it on close. [reasoning](https://gitlab.com/librewolf-community/settings/-/issues/135).
+- [download annoyances](https://gitlab.com/librewolf-community/settings/-/issues/144).
+
+**Notes**: the settings have been re-organized and they should also be documented a bit better now.
+
+#### Removed preferences
+```
+defaultPref("security.insecure_connection_text.enabled", true); // display http websites as insecure in the ui
+defaultPref("places.history.enabled", true);
+```
+
+#### Added preferences
+```
+defaultPref("browser.places.speculativeConnect.enabled", false);
+defaultPref("browser.download.alwaysOpenPanel", false); // do not expand toolbar menu for every download, we already have enough interaction
+```
+
+#### Changed preferences
+```
+pref("security.tls.version.enable-deprecated", false); // make TLS downgrades session only by enforcing it with pref()
+```
+
 ## 5.4
 
 **target commit**:

librewolf.cfg

@@ -1,221 +1,210 @@
-//----------------------|
-//  LibreWolf settings  |
-//----------------------|
 
-/**
+/** LIBREWOLF SETTINGS
+ * 
+ * take the time to read and understand, but also to customize the settings to find your own setup.
+ * the answers to the most common questions can be found at https://librewolf.net/docs/faq/.
+ * 
+ * WARNING: make sure the first line of this file is empty. this is a known bug.
+ */
+lockPref("librewolf.cfg.version", "7.7");
 
- NOTE: please take the time to read and understand, but also to customize the settings to find your own setup.
- the answers to the most common questions are at this link https://librewolf.net/docs/faq/
 
+/** INDEX
+ * the file is organized in categories, and each one has a number of sections:
+ * 
+ * PRIVACY [ISOLATION, SANITIZING, CACHE AND STORAGE, HISTORY AND SESSION RESTORE, QUERY STRIPPING]
+ * NETWORKING [HTTPS, REFERERS, WEBRTC, PROXY, DNS, PREFETCHING AND SPECULATIVE CONNECTIONS]
+ * FINGERPRINTING [RFP, WEBGL]
+ * SECURITY [SITE ISOLATION, CERTIFICATES, TLS/SSL, PERMISSIONS, SAFE BROWSING, OTHERS]
+ * REGION [LOCATION, LANGUAGE]
+ * BEHAVIOR [DRM, SEARCH AND URLBAR, DOWNLOADS, AUTOPLAY, POP-UPS AND WINDOWS, MOUSE]
+ * EXTENSIONS [USER INSTALLED, SYSTEM, EXTENSION FIREWALL]
+ * BUILT-IN FEATURES [UPDATER, SYNC, LOCKWISE, CONTAINERS, DEVTOOLS, OTHERS]
+ * UI [BRANDING, HANDLERS, FIRST LAUNCH, NEW TAB PAGE, ABOUT, RECOMMENDED]
+ * TELEMETRY
+ * WINDOWS [UPDATES, OTHERS]
  */
 
-defaultPref("librewolf.cfg.version", "5.4");
 
-// -------------------------------
-// # SANITIZING, TP, SESSIONS
-// -------------------------------
 
-/**
- strict mode includes:
- - dFPI for both normal and private browsing
- - strict blocking lists for trackers, including crypto, fping and socialtracking
- - shims to avoid breakage caused by blocking lists
- - stricter policies for xorigin referrers
- - cookie cleaning mechanism specific to dFPI
-*/
+/** [CATEGORY] PRIVACY */
+
+/** [SECTION] ISOLATION
+ * default to strict mode, which includes:
+ * 1. dFPI for both normal and private windows
+ * 2. strict blocking lists for trackers
+ * 3. shims to avoid breakage caused by blocking lists
+ * 4. stricter policies for xorigin referrers
+ * 5. dFPI specific cookie cleaning mechanism
+ * 6. query stripping
+ * 
+ * the desired category must be set with pref() otherwise it won't stick.
+ * the UI that allows to change mode manually is hidden.
+ */
 pref("browser.contentblocking.category", "strict");
+// enable APS
+defaultPref("privacy.partition.always_partition_third_party_non_cookie_storage", true);
+defaultPref("privacy.partition.always_partition_third_party_non_cookie_storage.exempt_sessionstorage", false);  
 
-defaultPref("network.cookie.cookieBehavior", 5); // dFPI is default for strict mode, but enforce
-defaultPref("network.cookie.lifetimePolicy", 2); // keep cookies until end of the session, then clear
-defaultPref("privacy.partition.serviceWorkers", true); // isolate service workers
-
-// make third party and http cookies session-only
-defaultPref("network.cookie.thirdparty.sessionOnly", true);
-defaultPref("network.cookie.thirdparty.nonsecureSessionOnly", true);
-
-/**
- this way of sanitizing cookies would override the exceptions set by the users and just delete everything,
- we disable it but cookies and site data are still cleared per session unless exceptions are set.
- all the cleaning prefs true by default except for siteSetting and offlineApps, which is what we want.
-*/
-defaultPref("privacy.clearOnShutdown.cookies", false);
+/** [SECTION] SANITIZING 
+ * all the cleaning prefs true by default except for siteSetting and offlineApps,
+ * which is what we want. users should set manual exceptions in the UI if there
+ * are cookies they want to keep.
+ */
+defaultPref("privacy.clearOnShutdown.offlineApps", true);
 defaultPref("privacy.sanitize.sanitizeOnShutdown", true);
 defaultPref("privacy.sanitize.timeSpan", 0);
 
-// disable browsing, search and form history
-defaultPref("places.history.enabled", false);
-defaultPref("browser.formfill.enable", false);
+/** [SECTION] CACHE AND STORAGE */
+defaultPref("browser.cache.disk.enable", false); // disable disk cache
+/** prevent media cache from being written to disk in pb, but increase max cache size to avoid playback issues */
+defaultPref("browser.privatebrowsing.forceMediaMemoryCache", true);
+defaultPref("media.memory_cache_max_size", 65536);
+defaultPref("browser.shell.shortcutFavicons", false); // disable favicons in profile folder
+defaultPref("browser.helperApps.deleteTempFileOnExit", true); // delete temporary files opened with external apps
 
-// prevent websites from storing session data like cookies and forms, increase time between session saves
-defaultPref("browser.sessionstore.privacy_level", 2);
-defaultPref("browser.sessionstore.interval", 60000);
+/** [SECTION] HISTORY AND SESSION RESTORE
+ * since we hide the UI for modes other than custom we want to reset it for
+ * everyone. same thing for always on PB mode.
+ */
+pref("privacy.history.custom", true);
+pref("browser.privatebrowsing.autostart", false);
+defaultPref("browser.formfill.enable", false); // disable form history
+defaultPref("browser.sessionstore.privacy_level", 2); // prevent websites from storing session data like cookies and forms
 
-// -----------------
-// QUERY STRIPPING
-// -----------------
-
-/**
- * enable query stripping and set the strip list.
- * currently we use the same one that brave uses:
+/** [SECTION] QUERY STRIPPING
+ * currently we set the same query stripping list that brave uses:
  * https://github.com/brave/brave-core/blob/f337a47cf84211807035581a9f609853752a32fb/browser/net/brave_site_hacks_network_delegate_helper.cc#L29
  */
-defaultPref("privacy.query_stripping.enabled", true);
-defaultPref("privacy.query_stripping.strip_list", "__hsfp __hssc __hstc __s _hsenc _openstat dclid fbclid gbraid gclid hsCtaTracking igshid mc_eid ml_subscriber ml_subscriber_hash msclkid oly_anon_id oly_enc_id rb_clickid s_cid twclid vero_conv vero_id wbraid wickedid yclid");
-
+defaultPref("privacy.query_stripping.strip_list", "__hsfp __hssc __hstc __s _hsenc _openstat dclid fbclid gbraid gclid hsCtaTracking igshid mc_eid ml_subscriber ml_subscriber_hash msclkid oft_c oft_ck oft_d oft_id oft_ids oft_k oft_lk oft_sk oly_anon_id oly_enc_id rb_clickid s_cid twclid vero_conv vero_id wbraid wickedid yclid");
 /**
  * librewolf specific pref that allows to include the query stripping lists in uBO by default.
  * the asset file is fetched every 7 days.
  */
 defaultPref("librewolf.uBO.assetsBootstrapLocation", "https://gitlab.com/librewolf-community/browser/source/-/raw/main/assets/uBOAssets.json");
 
-// ----------------------
-// # NETWORKING
-// ----------------------
+/** [SECTION] LOGGING
+ * these prefs are off by default in the official Mozilla builds,
+ * so it only makes sense that we also disable them.
+ * See https://gitlab.com/librewolf-community/settings/-/issues/240
+ */
+pref("browser.dom.window.dump.enabled", false);
+pref("devtools.console.stdout.chrome", false);
 
-// https and mixed content
+
+
+/** [CATEGORY] NETWORKING */
+
+/** [SECTION] HTTPS */
 defaultPref("dom.security.https_only_mode", true); // only allow https in all windows, including private browsing
-defaultPref("network.auth.subresource-http-auth-allow", 1); // stop cross-origin resources from using HTTP authentication
-defaultPref("security.insecure_connection_text.enabled", true); // display http websites as insecure in the ui
-defaultPref("security.mixed_content.block_display_content", true); // block insecure passive content
+defaultPref("network.auth.subresource-http-auth-allow", 1); // block HTTP authentication credential dialogs
 
-defaultPref("network.dns.disableIPv6", true); // disable ipv6
+/** [SECTION] REFERERS
+ * to enhance privacy but keep a certain level of usability we trim cross-origin
+ * referers to only send scheme, host and port, instead of completely avoid sending them.
+ * as a general rule, the behavior of referes which are not cross-origin should not
+ * be changed.
+ */
+defaultPref("network.http.referer.XOriginTrimmingPolicy", 2);
 
-// always send xorigin referer but trim them
-defaultPref("network.http.referer.XOriginPolicy", 0); // default, might be worth changing to 2
-defaultPref("network.http.referer.XOriginTrimmingPolicy", 2); // trim referer to only send scheme, host and port
-
-defaultPref("network.file.disable_unc_paths", true); // hidden, disable using uniform naming convention
-defaultPref("network.IDN_show_punycode", true); // use punycode in idn to prevent spoofing
-
-// proxy
-defaultPref("network.proxy.socks_remote_dns", true); // forces dns query through the proxy when using one
-defaultPref("network.gio.supported-protocols", ""); // disable gio as it could bypass proxy
-
-// doh
-defaultPref("network.trr.confirmationNS", "skip"); // skip undesired doh test connection
-/**
- 0 = default
- 1 = browser picks faster
- 2 = DoH with system dns fallback
- 3 = DoH without fallback
- 5 = DoH is off, default currently
- 
- below prefs must be applied with pref in order to work
-*/
-// pref("network.trr.mode", 2);
-// pref("network.trr.uri", "https://dns.quad9.net/dns-query");
-
-// prefetching
-defaultPref("network.dns.disablePrefetch", true); // disable dns prefetching
-lockPref("network.predictor.enabled", false); // disable predictor
-lockPref("network.prefetch-next", false); // disable link prefetching
-lockPref("network.http.speculative-parallel-limit", 0); // disable prefetching on mouse over
-
-defaultPref("network.manage-offline-status", false); // let user control the offline behavior
-
-// ------------
-// # DOM
-// ------------
-
-// pop-ups and window related preferences
-defaultPref("dom.disable_beforeunload", true); // disable "confirm you want to leave" pop-ups on close
-defaultPref("dom.disable_open_during_load", true); // block pop-ups windows
-defaultPref("dom.popup_allowed_events", "click dblclick mousedown pointerdown"); // limit events that cause pop-ups
-defaultPref("dom.disable_window_move_resize", true); // block scripts from resizing windows
-defaultPref("browser.link.open_newwindow", 3); // open 'new windows' targeted links in 'new tab'
-defaultPref("browser.link.open_newwindow.restriction", 0); // ignore the size when applying the above pref
-
-// --------------------------------
-// # CACHE AND TEMPORARY FILES
-// --------------------------------
-
-defaultPref("browser.cache.disk.enable", false); // disable disk cache
-defaultPref("browser.privatebrowsing.forceMediaMemoryCache", true); // block media cache from writing to disk in pb mode
-defaultPref("media.memory_cache_max_size", 65536); // increase max cache size to avoid playback issues caused by above setting
-
-defaultPref("browser.shell.shortcutFavicons", false); // disable shortcut favicons from being stored in profile
-defaultPref("browser.helperApps.deleteTempFileOnExit", true); // delete temporary files opened with external apps
-defaultPref("browser.pagethumbnails.capturing_disabled", true); // disable page thumbnails capturing
-
-// ----------------------
-// # MEDIA
-// ----------------------
-
-/**
- * limit potential private IP leaks for webrtc users.
- * mDNS protects the value on linux, osx and win10+.
- * these prefs protect the value when allowing mic and camera access, and for win7/8.x.
- * */
-defaultPref("media.peerconnection.ice.no_host", true); // don't use any private IPs for ICE candidate
+/** [SECTION] WEBRTC
+ * there is no point in disabling webrtc as mDNS protects the private IP on linux, osx and win10+.
+ * the private IP address is only used in trusted environments, eg. allowed camera and mic access.
+ */
 defaultPref("media.peerconnection.ice.default_address_only", true); // use a single interface for ICE candidates, the vpn one when a vpn is used
-defaultPref("media.peerconnection.ice.proxy_only_if_behind_proxy", true); // force webrtc inside proxy, when one is used
 
-// autoplay
-defaultPref("media.autoplay.blocking_policy", 2); // only allow to play when a certain element is clicked
-defaultPref("media.autoplay.default", 5); // personal preference, currently apply blocking policy to all autplay including muted
+/** [SECTION] PROXY */
+defaultPref("network.gio.supported-protocols", ""); // disable gio as it could bypass proxy
+defaultPref("network.file.disable_unc_paths", true); // hidden, disable using uniform naming convention to prevent proxy bypass
+defaultPref("network.proxy.socks_remote_dns", true); // forces dns query through the proxy when using one
+defaultPref("media.peerconnection.ice.proxy_only_if_behind_proxy", true); // force webrtc inside proxy when one is used
 
-// --------------------------------------
-// # FINGERPRINTING
-// --------------------------------------
+/** [SECTION] DNS */
+defaultPref("network.trr.confirmationNS", "skip"); // skip undesired doh test connection
+defaultPref("network.dns.disablePrefetch", true); // disable dns prefetching
+/**
+ * librewolf does not use DoH, but it can be enabled with the following prefs:
+ * pref("network.trr.mode", 2);
+ * pref("network.trr.uri", "https://dns.quad9.net/dns-query");
+ * 
+ * the possible modes are:
+ * 0 = default
+ * 1 = browser picks faster
+ * 2 = DoH with system dns fallback
+ * 3 = DoH without fallback
+ * 5 = DoH is off, default currently
+ */
 
-defaultPref("privacy.resistFingerprinting", true); // master switch
+/** [SECTION] PREFETCHING AND SPECULATIVE CONNECTIONS
+ * disable prefecthing for different things such as links, bookmarks and predictions.
+ */
+pref("network.predictor.enabled", false);
+pref("network.prefetch-next", false);
+pref("network.http.speculative-parallel-limit", 0);
+defaultPref("browser.places.speculativeConnect.enabled", false);
+// disable speculative connections and domain guessing from the urlbar
+defaultPref("browser.urlbar.speculativeConnect.enabled", false);
 
-// rfp compatibility settings
+
+
+/** [CATEGORY] FINGERPRINTING */
+
+/** [SECTION] RFP
+ * librewolf should stick to RFP for fingerprinting. we should not set prefs that interfere with it
+ * and disabling API for no good reason will be counter productive, so it should also be avoided.  
+ */
+defaultPref("privacy.resistFingerprinting", true);
+// rfp related settings
 defaultPref("privacy.resistFingerprinting.block_mozAddonManager", true); // prevents rfp from breaking AMO
-defaultPref("browser.startup.blankWindow", false); // if set to true it breaks RFP windows resizing
-defaultPref("browser.display.use_system_colors", false); // default but enforced due to RFP
-
-defaultPref("privacy.resistFingerprinting.letterboxing", false); // expose hidden letterboxing pref, but do not enable by default
-
+defaultPref("browser.display.use_system_colors", false); // default, except Win
 /**
  * increase the size of new RFP windows for better usability, while still using a rounded value.
  * if the screen resolution is lower it will stretch to the biggest possible rounded value.
- * */
+ * also, expose hidden letterboxing pref but do not enable it for now.
+ */
 defaultPref("privacy.window.maxInnerWidth", 1600);
 defaultPref("privacy.window.maxInnerHeight", 900);
+defaultPref("privacy.resistFingerprinting.letterboxing", false);
 
-defaultPref("webgl.disabled", true); // master switch, disable webgl
+/** [SECTION] WEBGL */
+defaultPref("webgl.disabled", true);
 
-// --------------------------------
-// # SECURITY
-// --------------------------------
 
-defaultPref("fission.autostart", true); // enable fission by default
 
-// certificates
-defaultPref("security.cert_pinning.enforcement_level", 2); // enable strict public key pinning
-defaultPref("security.pki.sha1_enforcement_level", 1); // disable sha-1 certificates
-defaultPref("security.OCSP.enabled", 0); // disable ocsp fetching
+/** [CATEGORY] SECURITY */
 
-// crl with no ocsp fallback
+/** [SECTION] CERTIFICATES */
+defaultPref("security.cert_pinning.enforcement_level", 2); // enable strict public key pinning, might cause issues with AVs
+/**
+ * enable safe negotiation and show warning when it is not supported. might cause breakage
+ * if the the server does not support RFC 5746, in tha case SSL_ERROR_UNSAFE_NEGOTIATION
+ * will be shown.
+ */
+defaultPref("security.ssl.require_safe_negotiation", true);
+defaultPref("security.ssl.treat_unsafe_negotiation_as_broken", true);
+/**
+ * our strategy with revocation is to perform all possible checks with CRL, but when a cert
+ * cannot be checked with it we use OCSP stapled with hard-fail, to still keep privacy and
+ * increase security.
+ * crlite is in mode 3 by default, which allows us to detect false positive with OCSP.
+ * in v103, when crlite is fully mature, it will switch to mode 2 and no longer double-check.
+ */
 defaultPref("security.remote_settings.crlite_filters.enabled", true);
-defaultPref("security.pki.crlite_mode", 2);
+defaultPref("security.OCSP.require", true); // set to hard-fail, might cause SEC_ERROR_OCSP_SERVER_ERROR
 
-// safe negotiation
-defaultPref("security.ssl.require_safe_negotiation", true); // block websites that do not support safe negotiation, occasional breakage
-defaultPref("security.ssl.treat_unsafe_negotiation_as_broken", true); // show warning when safe negotiation is not enable and website is accessed
+/** [SECTION] TLS/SSL */
+pref("security.tls.enable_0rtt_data", false); // disable 0 RTT to improve tls 1.3 security
+pref("security.tls.version.enable-deprecated", false); // make TLS downgrades session only by enforcing it with pref(), default
+defaultPref("browser.xul.error_pages.expert_bad_cert", true); // show relevant and advanced issues on warnings and error screens
 
-// tls behavior
-lockPref("security.tls.enable_0rtt_data", false); // disable 0 round trip time to improve tls 1.3 security
-defaultPref("security.tls.version.enable-deprecated", false); // default but helps resetting the preference
-defaultPref("browser.ssl_override_behavior", 1); // prepopulate url on ssl warning screens
-defaultPref("browser.xul.error_pages.expert_bad_cert", true); // advanced ui infos for broken connections
+/** [SECTION] PERMISSIONS */
+pref("permissions.delegation.enabled", false); // force permission request to show real origin
+pref("permissions.manager.defaultsUrl", ""); // revoke special permissions for some mozilla domains
 
-// permissions
-lockPref("permissions.delegation.enabled", false); // force permission request to show the real origin
-lockPref("permissions.manager.defaultsUrl", ""); // revoke special permissions from some mozilla domains
-
-defaultPref("gfx.font_rendering.opentype_svg.enabled", false); // disale svg opentype fonts
-
-defaultPref("browser.download.useDownloadDir", false); // force user interaction on downloads, by always asking location
-
-lockPref("security.csp.enable", true); // default
-
-// ---------------------------------
-// # SAFE BROWSING
-// ---------------------------------
-
-// disable safe browsing, including the fetch of updates and all outgoing connections 
+/** [SECTION] SAFE BROWSING
+ * disable safe browsing, including the fetch of updates. reverting the 7 prefs below
+ * allows to perform local checks and to fetch updated lists from google.
+ */
 defaultPref("browser.safebrowsing.malware.enabled", false);
 defaultPref("browser.safebrowsing.phishing.enabled", false);
 defaultPref("browser.safebrowsing.blockedURIs.enabled", false);
@@ -223,157 +212,181 @@ defaultPref("browser.safebrowsing.provider.google4.gethashURL", "");
 defaultPref("browser.safebrowsing.provider.google4.updateURL", "");
 defaultPref("browser.safebrowsing.provider.google.gethashURL", "");
 defaultPref("browser.safebrowsing.provider.google.updateURL", "");
-
-// disable safe browsing checks on downloads, both local and remote
-defaultPref("browser.safebrowsing.downloads.enabled", false);
-lockPref("browser.safebrowsing.downloads.remote.enabled", false);
-lockPref("browser.safebrowsing.downloads.remote.url", "");
-lockPref("browser.safebrowsing.downloads.remote.block_potentially_unwanted", false);
-lockPref("browser.safebrowsing.downloads.remote.block_uncommon", false);
-
-// other safe browsing options, all default but enforce
-lockPref("browser.safebrowsing.passwords.enabled", false);
-lockPref("browser.safebrowsing.provider.google4.dataSharing.enabled", false);
-lockPref("browser.safebrowsing.provider.google4.dataSharingURL", "");
-
-// -----------------------
-// # DRM
-// -----------------------
-
-defaultPref("media.eme.enabled", false); // disable drm content, master switch that also controls widevine plugin
-defaultPref("media.gmp-manager.url", "data:text/plain,"); // prevent outgoing connections when DRM is disabled
-
-// disable the openh264 plugin
-defaultPref("media.gmp-provider.enabled", false);
-defaultPref("media.gmp-gmpopenh264.enabled", false);
-
-// ---------------------------------------------
-// # LOCATION, LANGUAGE AND REGION
-// ---------------------------------------------
-
-// use mozilla geo service as deault
-defaultPref("geo.provider.network.url", "https://location.services.mozilla.com/v1/geolocate?key=%MOZILLA_API_KEY%");
-
-// prevent use of OS location services
-lockPref("geo.provider.ms-windows-location", false); // [WINDOWS]
-lockPref("geo.provider.use_corelocation", false); // [MAC]
-lockPref("geo.provider.use_gpsd", false); // [LINUX]
-
 /**
-show language as en-US for all users, regardless of their OS language and browser language.
-must use pref and not defaultPref to work. spoof_english also sets the UI correctly.
+ * disable safe browsing checks on downloads, both local and remote. the resetting prefs
+ * control remote checks, while the first one is for local checks only.
+ */
+defaultPref("browser.safebrowsing.downloads.enabled", false);
+pref("browser.safebrowsing.downloads.remote.enabled", false);
+pref("browser.safebrowsing.downloads.remote.block_potentially_unwanted", false);
+pref("browser.safebrowsing.downloads.remote.block_uncommon", false);
+ // empty for defense in depth
+pref("browser.safebrowsing.downloads.remote.url", "");
+pref("browser.safebrowsing.provider.google4.dataSharingURL", "");
+
+/** [SECTION] OTHERS */
+defaultPref("network.IDN_show_punycode", true); // use punycode in idn to prevent spoofing
+defaultPref("pdfjs.enableScripting", false); // disable js scripting in the built-in pdf reader
+
+
+
+/** [CATEGORY] REGION */
+
+/** [SECTION] LOCATION
+ * replace google with mozilla as the default geolocation provide and prevent use of OS location services
+ */
+defaultPref("geo.provider.network.url", "https://location.services.mozilla.com/v1/geolocate?key=%MOZILLA_API_KEY%");
+defaultPref("geo.provider.ms-windows-location", false); // [WINDOWS]
+defaultPref("geo.provider.use_corelocation", false); // [MAC]
+defaultPref("geo.provider.use_gpsd", false); // [LINUX]
+defaultPref("geo.provider.use_geoclue", false); // [LINUX]
+
+/** [SECTION] LANGUAGE
+ * show language as en-US for all users, regardless of their OS language and browser language.
+ * both prefs must use pref() and not defaultPref to work.
  */
 pref("javascript.use_us_english_locale", true);
 pref("intl.accept_languages", "en-US, en");
+// disable region specific updates from mozilla
+pref("browser.region.network.url", "");
+pref("browser.region.update.enabled", false);
 
-// disable region updates
-lockPref("browser.region.network.url", "");
-lockPref("browser.region.update.enabled", false);
 
-// --------------------------------
-// # SEARCH AND URLBAR
-// --------------------------------
 
-// disable search suggestions
+/** [CATEGORY] BEHAVIOR */
+
+/** [SECTION] DRM */
+defaultPref("media.eme.enabled", false); // master switch for drm content
+defaultPref("media.gmp-manager.url", "data:text/plain,"); // prevent checks for plugin updates when drm is disabled
+// disable the widevine and the openh264 plugins
+defaultPref("media.gmp-provider.enabled", false);
+defaultPref("media.gmp-gmpopenh264.enabled", false);
+
+/** [SECTION] SEARCH AND URLBAR
+ * disable search suggestion and do not update opensearch engines.
+ */
 defaultPref("browser.urlbar.suggest.searches", false);
 defaultPref("browser.search.suggest.enabled", false);
-
-// firefox suggest, review to trim
-lockPref("browser.urlbar.quicksuggest.scenario", "history"); // prevent opt-in, doesn't work alone
-lockPref("browser.urlbar.quicksuggest.enabled", false); // disable suggest and hide its ui
-lockPref("browser.urlbar.suggest.quicksuggest.nonsponsored", false); // disable suggestions from firefox
-lockPref("browser.urlbar.suggest.quicksuggest.sponsored", false); // disable sponsored suggestions
-lockPref("browser.urlbar.quicksuggest.dataCollection.enabled", false); // default
-
-defaultPref("browser.search.update", false); // do not update open search search engines
-defaultPref("browser.urlbar.trimURLs", false); // do not trim urls in the urlbar
-
-// urlbar-dns interactions, avoid unwanted and speculative connections
-defaultPref("browser.urlbar.dnsResolveSingleWordsAfterSearch", 0);
-defaultPref("browser.urlbar.speculativeConnect.enabled", false);
-lockPref("browser.fixup.alternate.enabled", false);
-
-// ----------------------------------
-// # BROWSER BEHAVIOR
-// ----------------------------------
-
-lockPref("app.update.auto", false); // disable update auto installs
-
-defaultPref("identity.fxaccounts.enabled", false); // sync and firefox account
-
-// password manager
-defaultPref("signon.rememberSignons", false); // disable saving passwords in the browser
-defaultPref("signon.autofillForms", false); // disable username and password autofills
-defaultPref("signon.formlessCapture.enabled", false); // disable formless login capture
-
-// autofill
-defaultPref("extensions.formautofill.available", "off");
-defaultPref("extensions.formautofill.addresses.enabled", false);
-defaultPref("extensions.formautofill.creditCards.enabled", false);
-defaultPref("extensions.formautofill.creditCards.available", false);
-defaultPref("extensions.formautofill.heuristics.enabled", false);
-
-// containers
-defaultPref("privacy.userContext.enabled", true); // enable containers
-defaultPref("privacy.userContext.ui.enabled", true);  // enable containers ui
-
-defaultPref("pdfjs.enableScripting", false); // block pdf js scripting
-
-defaultPref("accessibility.force_disabled", 1); // block accessibility services
-
-// devtools
-defaultPref("devtools.chrome.enabled", false); // disable chrome debugging tools
-defaultPref("devtools.debugger.remote-enabled", false); // default, disable remote debugging
-defaultPref("devtools.remote.adb.extensionURL", ""); // url to download ad extension
-defaultPref("devtools.selfxss.count", 0); // required for devtools console to work
-
-// misc
-defaultPref("browser.shell.checkDefaultBrowser", false); // do not check if default browser
-defaultPref("browser.aboutConfig.showWarning", false); // disable about:config warning
-defaultPref("browser.download.autohideButton", false); // hide download button automatically
-defaultPref("browser.download.manager.addToRecentDocs", false); // do not add downloads to recents
-defaultPref("middlemouse.contentLoadURL", false); // prevent mouse middle click from opening links
-defaultPref("webchannel.allowObject.urlWhitelist", ""); // remove webchannel whitelist
-
-// --------------------------------------
-// # EXTENSIONS
-// --------------------------------------
-
+defaultPref("browser.search.update", false);
 /**
- allow extensions to work on all domains.
- default is "debug-notes.log"
+ * the pref disables the whole feature and hide it from the ui
+ * (as noted in https://bugzilla.mozilla.org/show_bug.cgi?id=1755057).
+ * this also includes the best match feature, as it is part of firefox suggest.
+ */
+pref("browser.urlbar.quicksuggest.enabled", false);
+defaultPref("browser.urlbar.suggest.weather", false); // disable weather suggestions in urlbar once they are no longer behind feature gate
+
+/** [SECTION] DOWNLOADS
+ * user interaction should always be required for downloads, as a way to enhance security by asking
+ * the user to specific a certain save location. 
+ */
+defaultPref("browser.download.useDownloadDir", false);
+defaultPref("browser.download.autohideButton", false); // do not hide download button automatically
+defaultPref("browser.download.manager.addToRecentDocs", false); // do not add downloads to recents
+defaultPref("browser.download.alwaysOpenPanel", false); // do not expand toolbar menu for every download, we already have enough interaction
+
+/** [SECTION] AUTOPLAY
+ * block autoplay unless element is right-clicked. this means background videos, videos in a different tab,
+ * or media opened while other media is played will not start automatically.
+ * thumbnails will not autoplay unless hovered. exceptions can be set from the UI.
+ */
+defaultPref("media.autoplay.default", 5);
+
+/** [SECTION] POP-UPS AND WINDOWS
+ * prevent scripts from resizing existing windows and opening new ones, by forcing them into
+ * new tabs that can't be resized as well.
+ */
+defaultPref("dom.disable_window_move_resize", true);
+defaultPref("browser.link.open_newwindow", 3);
+defaultPref("browser.link.open_newwindow.restriction", 0);
+
+/** [SECTION] MOUSE */
+defaultPref("browser.tabs.searchclipboardfor.middleclick", false); // prevent mouse middle click on new tab button to trigger searches or page loads
+
+
+
+/** [CATEGORY] EXTENSIONS */
+
+/** [SECTION] USER INSTALLED
+ * extensions are allowed to operate on restricted domains, while their scope
+ * is set to profile+applications (https://mike.kaply.com/2012/02/21/understanding-add-on-scopes/).
+ * an installation prompt should always be displayed.
  */
 defaultPref("extensions.webextensions.restrictedDomains", "");
-
-// set extensions scopes
 defaultPref("extensions.enabledScopes", 5); // hidden
+defaultPref("extensions.postDownloadThirdPartyPrompt", false);
+/**
+ * the pref disables quarantined domains.
+ * this is a security feature, we should remove it with v116 as there will be a UI to control this per-extension.
+ * unless we patch remote settings we rely on static dumps. this means even if we did not flip this pref it would
+ * not make a difference at the moment.
+ */
+defaultPref("extensions.quarantinedDomains.enabled", false);
 
-defaultPref("extensions.postDownloadThirdPartyPrompt", false); // force install prompt for thrid party extensions 
-
-// about:addons ui
-defaultPref("extensions.htmlaboutaddons.recommendations.enabled", false); // disable recommendations from addons list
-defaultPref("extensions.getAddons.showPane", false); // disable recommendations section
-defaultPref("extensions.getAddons.cache.enabled", false); // disable fetching of extension metadata
-defaultPref("lightweightThemes.getMoreURL", ""); // disable button to get more themes
-
-// extension firewall, disabled by default
-// defaultPref("extensions.webextensions.base-content-security-policy", "default-src 'none'; script-src 'none'; object-src 'none';");
-// defaultPref("extensions.webextensions.base-content-security-policy.v3", "default-src 'none'; script-src 'none'; object-src 'none';");
-
-// report site issue, disable button and url for in depth defense
+/** [SECTION] SYSTEM
+ * built-in extension are not allowed to auto-update. additionally the reporter extension
+ * of webcompat is disabled. urls are stripped for defense in depth.
+ */
+defaultPref("extensions.systemAddon.update.enabled", false);
+defaultPref("extensions.systemAddon.update.url", "");
 lockPref("extensions.webcompat-reporter.enabled", false);
 lockPref("extensions.webcompat-reporter.newIssueEndpoint", "");
 
-// system addons, prevent updates and strip url for in depth defense
-defaultPref("extensions.systemAddon.update.enabled", false);
-defaultPref("extensions.systemAddon.update.url", "");
+/** [SECTION] EXTENSION FIREWALL
+ * the firewall can be enabled with the below prefs, but it is not a sane default:
+ * defaultPref("extensions.webextensions.base-content-security-policy", "default-src 'none'; script-src 'none'; object-src 'none';");
+ * defaultPref("extensions.webextensions.base-content-security-policy.v3", "default-src 'none'; script-src 'none'; object-src 'none';");
+ */
 
-// --------------------------------
-// # URLS AND ANNOYANCES
-// --------------------------------
 
-// set librewolf support and releases urls
-defaultPref("app.support.baseURL", "https://librewolf.net/docs/faq/#");
+
+/** [CATEGORY] BUILT-IN FEATURES */
+
+/** [SECTION] UPDATER
+ * since we do not bake auto-updates in the browser it doesn't make sense at the moment.
+ */
+lockPref("app.update.auto", false);
+
+/** [SECTION] SYNC
+ * this functionality is disabled by default but it can be activated in one click.
+ * this pref fully controls the feature, including its ui.
+ */
+defaultPref("identity.fxaccounts.enabled", false);
+
+/** [SECTION] LOCKWISE
+ * disable the default password manager built into the browser, including its autofill
+ * capabilities and formless login capture.
+ */
+defaultPref("signon.rememberSignons", false);
+defaultPref("signon.autofillForms", false);
+defaultPref("extensions.formautofill.addresses.enabled", false);
+defaultPref("extensions.formautofill.creditCards.enabled", false);
+defaultPref("signon.formlessCapture.enabled", false);
+
+/** [SECTION] CONTAINERS
+ * enable containers and show the settings to control them in the stock ui
+ */
+defaultPref("privacy.userContext.enabled", true);
+defaultPref("privacy.userContext.ui.enabled", true);
+
+/** [SECTION] DEVTOOLS
+ * disable remote debugging.
+ */
+pref("devtools.debugger.remote-enabled", false); // default, but subject to branding so keep it
+defaultPref("devtools.selfxss.count", 0); // required for devtools console to work
+
+/** [SECTION] OTHERS */
+pref("webchannel.allowObject.urlWhitelist", ""); // remove web channel whitelist
+defaultPref("services.settings.server", "https://%.invalid") // set the remote settings URL (REMOTE_SETTINGS_SERVER_URL in the code)
+
+
+
+/** [CATEGORY] UI */
+
+/** [SECTION] BRANDING
+ * set librewolf support and releases urls in the UI, so that users land in the proper places.
+ */
+defaultPref("app.support.baseURL", "https://support.librewolf.net/");
 defaultPref("browser.search.searchEnginesURL", "https://librewolf.net/docs/faq/#how-do-i-add-a-search-engine");
 defaultPref("browser.geolocation.warning.infoURL", "https://librewolf.net/docs/faq/#how-do-i-enable-location-aware-browsing");
 defaultPref("app.feedback.baseURL", "https://librewolf.net/#questions");
@@ -382,18 +395,10 @@ defaultPref("app.releaseNotesURL.aboutDialog", "https://gitlab.com/librewolf-com
 defaultPref("app.update.url.details", "https://gitlab.com/librewolf-community/browser");
 defaultPref("app.update.url.manual", "https://gitlab.com/librewolf-community/browser");
 
-// remove default handlers and translation engine
-lockPref("gecko.handlerService.schemes.mailto.0.uriTemplate", "");
-lockPref("gecko.handlerService.schemes.mailto.0.name", "");
-lockPref("gecko.handlerService.schemes.mailto.1.uriTemplate", "");
-lockPref("gecko.handlerService.schemes.mailto.1.name", "");
-lockPref("gecko.handlerService.schemes.irc.0.uriTemplate", "");
-lockPref("gecko.handlerService.schemes.irc.0.name", "");
-lockPref("gecko.handlerService.schemes.ircs.0.uriTemplate", "");
-lockPref("gecko.handlerService.schemes.ircs.0.name", "");
-lockPref("browser.translation.engine", "");
-
-// disable welcome, what is new pages and ui tour
+/** [SECTION] FIRST LAUNCH
+ * disable what's new and ui tour on first start and updates. the browser
+ * should also not stress user about being the default one.
+ */
 defaultPref("browser.startup.homepage_override.mstone", "ignore");
 defaultPref("startup.homepage_override_url", "about:blank");
 defaultPref("startup.homepage_welcome_url", "about:blank");
@@ -401,46 +406,58 @@ defaultPref("startup.homepage_welcome_url.additional", "");
 lockPref("browser.messaging-system.whatsNewPanel.enabled", false);
 lockPref("browser.uitour.enabled", false);
 lockPref("browser.uitour.url", "");
+defaultPref("browser.shell.checkDefaultBrowser", false);
 
-// hide annoying ui elements from about:protections
-defaultPref("browser.contentblocking.report.lockwise.enabled", false);
-defaultPref("browser.contentblocking.report.monitor.enabled", false);
-lockPref("browser.contentblocking.report.hide_vpn_banner", true);
-lockPref("browser.contentblocking.report.vpn.enabled", false);
-lockPref("browser.contentblocking.report.show_mobile_app", false);
-
-defaultPref("browser.topsites.useRemoteSetting", false); // hide sponsored shortcuts button from about:preferences#home
-
-// ------------------------------------
-// # NEW TAB PAGE
-// ------------------------------------
-
-defaultPref("browser.newtab.preload", false);
+/** [SECTION] NEW TAB PAGE
+ * we want NTP to display nothing but the search bar without anything distracting.
+ * the three prefs below are just for minimalism and they should be easy to revert for users.
+ */
 defaultPref("browser.newtabpage.activity-stream.section.highlights.includeDownloads", false);
 defaultPref("browser.newtabpage.activity-stream.section.highlights.includeVisited", false);
 defaultPref("browser.newtabpage.activity-stream.feeds.topsites", false);
-
-// hide pocket and sponsored content, from new tab page and search bar
+// hide stories and sponsored content from Firefox Home
 lockPref("browser.newtabpage.activity-stream.feeds.section.topstories", false);
-lockPref("browser.newtabpage.activity-stream.feeds.system.topstories", false);
-lockPref("browser.newtabpage.activity-stream.feeds.telemetry", false);
-lockPref("browser.newtabpage.activity-stream.feeds.section.topstories.options", "{\"hidden\":true}"); // hide buggy pocket section from about:preferences#home
 lockPref("browser.newtabpage.activity-stream.showSponsored", false);
 lockPref("browser.newtabpage.activity-stream.showSponsoredTopSites", false);
+// disable telemetry in Firefox Home
+lockPref("browser.newtabpage.activity-stream.feeds.telemetry", false);
 lockPref("browser.newtabpage.activity-stream.telemetry", false);
+// hide stories UI in about:preferences#home, empty highlights list
+lockPref("browser.newtabpage.activity-stream.feeds.section.topstories.options", "{\"hidden\":true}");
 lockPref("browser.newtabpage.activity-stream.default.sites", "");
-lockPref("browser.newtabpage.activity-stream.feeds.discoverystreamfeed", false);
-lockPref("browser.newtabpage.activity-stream.discoverystream.enabled", false);
-lockPref("browser.newtabpage.activity-stream.feeds.snippets", false); // default
 
-// disable recommend as you browse
+/** [SECTION] ABOUT
+ * remove annoying ui elements from the about pages, including about:protections
+ */
+defaultPref("browser.contentblocking.report.lockwise.enabled", false);
+lockPref("browser.contentblocking.report.hide_vpn_banner", true);
+lockPref("browser.contentblocking.report.vpn.enabled", false);
+lockPref("browser.contentblocking.report.show_mobile_app", false);
+lockPref("browser.vpn_promo.enabled", false);
+lockPref("browser.promo.focus.enabled", false);
+// ...about:addons recommendations sections and more
+defaultPref("extensions.htmlaboutaddons.recommendations.enabled", false);
+defaultPref("extensions.getAddons.showPane", false);
+defaultPref("extensions.getAddons.cache.enabled", false); // disable fetching of extension metadata
+defaultPref("lightweightThemes.getMoreURL", ""); // disable button to get more themes
+// ...about:preferences#home
+defaultPref("browser.topsites.useRemoteSetting", false); // hide sponsored shortcuts button
+// ...and about:config
+defaultPref("browser.aboutConfig.showWarning", false);
+// hide about:preferences#moreFromMozilla
+defaultPref("browser.preferences.moreFromMozilla", false);
+
+/** [SECTION] RECOMMENDED
+ * disable all "recommend as you browse" activity.
+ */
 lockPref("browser.newtabpage.activity-stream.asrouter.userprefs.cfr.features", false);
 lockPref("browser.newtabpage.activity-stream.asrouter.userprefs.cfr.addons", false);
 
-// --------------------------------
-// # TELEMETRY
-// --------------------------------
 
+
+/** [CATEGORY] TELEMETRY
+ * telemetry is already disabled elsewhere and most of the stuff in here is just for redundancy.
+ */
 lockPref("toolkit.telemetry.unified", false); // master switch
 lockPref("toolkit.telemetry.enabled", false);  // master switch
 lockPref("toolkit.telemetry.server", "data:,");
@@ -449,9 +466,7 @@ lockPref("toolkit.telemetry.newProfilePing.enabled", false);
 lockPref("toolkit.telemetry.updatePing.enabled", false);
 lockPref("toolkit.telemetry.firstShutdownPing.enabled", false);
 lockPref("toolkit.telemetry.shutdownPingSender.enabled", false);
-lockPref("toolkit.telemetry.shutdownPingSender.enabledFirstSession", false); // default
 lockPref("toolkit.telemetry.bhrPing.enabled", false);
-lockPref("toolkit.telemetry.reportingpolicy.firstRun", false); // default
 lockPref("toolkit.telemetry.cachedClientID", "");
 lockPref("toolkit.telemetry.previousBuildID", "");
 lockPref("toolkit.telemetry.server_owner", "");
@@ -464,56 +479,47 @@ lockPref("datareporting.healthreport.uploadEnabled", false);
 lockPref("datareporting.policy.dataSubmissionEnabled", false);
 lockPref("security.protectionspopup.recordEventTelemetry", false);
 lockPref("browser.ping-centre.telemetry", false);
-
-// crash report
-lockPref("breakpad.reportURL", "");
-lockPref("browser.tabs.crashReporting.sendReport", false);
-
-// normandy and studies
+// opt-out of normandy and studies
 lockPref("app.normandy.enabled", false);
 lockPref("app.normandy.api_url", "");
 lockPref("app.shield.optoutstudies.enabled", false);
-
-// personalized extension recommendations
+// disable personalized extension recommendations
 lockPref("browser.discovery.enabled", false);
 lockPref("browser.discovery.containers.enabled", false);
 lockPref("browser.discovery.sites", "");
+// disable crash report
+lockPref("browser.tabs.crashReporting.sendReport", false);
+lockPref("breakpad.reportURL", "");
+// disable connectivity checks
+pref("network.connectivity-service.enabled", false);
+// disable captive portal
+pref("network.captive-portal-service.enabled", false);
+pref("captivedetect.canonicalURL", "");
 
-// connectivity checks
-lockPref("network.connectivity-service.enabled", false);
+/** [CATEGORY] WINDOWS
+ * the prefs in this section only apply to windows installations and they don't have any
+ * effect on linux, macos and bsd users.
+ */
 
-// captive portal
-lockPref("network.captive-portal-service.enabled", false);
-lockPref("captivedetect.canonicalURL", "");
-
-// prevent sending server side analytics
-lockPref("beacon.enabled", false);
-
-// --------------------------------
-// # WINDOWS
-// --------------------------------
-
-// disable windows specific background update service
+/** [SECTION] UPDATES
+ * disable windows specific update services.
+ */
 lockPref("app.update.service.enabled", false);
 defaultPref("app.update.background.scheduling.enabled", false);
 
-defaultPref("network.protocol-handler.external.ms-windows-store", false); // disable links launching windows store
-
-lockPref("toolkit.winRegisterApplicationRestart", false); // disable automatic Firefox start and session restore after reboot
-
+/** [SECTION] OTHERS */
+lockPref("default-browser-agent.enabled", false); // disable windows specific telemetry
+defaultPref("network.protocol-handler.external.ms-windows-store", false); // prevent links from launching windows store
+pref("toolkit.winRegisterApplicationRestart", false); // disable automatic start and session restore after reboot
 lockPref("security.family_safety.mode", 0); // disable win8.1 family safety cert
 
-lockPref("default-browser-agent.enabled", false); // disable windows specific telemetry
 
-defaultPref("network.http.windows-sso.enabled", false); // disable MS auto authentication via sso
 
-// -----------------------------------
-// # OVERRIDES
-// -----------------------------------
-
-// allow settings to be overriden with a file at `~/.librewolf/librewolf.overrides.cfg`
-// or `~/.var/app/io.gitlab.librewolf-community/.librewolf/librewolf.overrides.cfg` (Flatpak).
+/** [CATEGORY] OVERRIDES
+ * allow settings to be overriden with a file placed in the right location
+ * https://librewolf.net/docs/settings/#where-do-i-find-my-librewolfoverridescfg
+ */
 let profile_directory;
 if (profile_directory = getenv('USERPROFILE') || getenv('HOME')) {
-  pref('autoadmin.global_config_url', `file://${profile_directory}/.librewolf/librewolf.overrides.cfg`);
+  defaultPref('autoadmin.global_config_url', `file://${profile_directory}/.librewolf/librewolf.overrides.cfg`);
 }