docs: adding browser prefereces documentation

Author: LucasAlvws

README.md

@@ -316,9 +316,34 @@ from pydoll.browser.options import ChromiumOptions
 
 options = ChromiumOptions()
 options.binary_location = '/path/to/your/chrome'
+options.browser_preferences = {
+    'download': {
+        'default_directory': '/tmp/downloads',
+        'prompt_for_download': False
+    },
+    'intl': {
+        'accept_languages': 'en-US,en,pt-BR'
+    },
+    'profile': {
+        'default_content_setting_values': {
+            'notifications': 2  # Block notifications
+        }
+    }
+}
+
+options.set_default_download_directory('/tmp/downloads')
+options.set_accept_languages('en-US,en,pt-BR')
+options.prompt_for_download = False
+
 browser = Chrome(options=options)
 ```
 
+**Custom Preferences**
+- Set download directory, language, notification blocking, PDF handling, and more
+- Merge multiple calls; only changed keys are updated
+- See [docs/features.md](docs/features.md#custom-browser-preferences) for more details
+
+
 **Browser starts after a FailedToStartBrowser error?**
 ```python
 from pydoll.browser import Chrome

docs/deep-dive/browser-preferences.md

@@ -0,0 +1,36 @@
+# Deep Dive: Custom Browser Preferences in Pydoll
+
+## Overview
+The `browser_preferences` feature (PR #204) enables direct, fine-grained control over Chromium browser settings via the `ChromiumOptions` API. This is essential for advanced automation, testing, and scraping scenarios where default browser behavior must be customized.
+
+## How It Works
+- `ChromiumOptions.browser_preferences` is a dictionary that maps directly to Chromium's internal preferences structure.
+- Preferences are merged: setting new keys updates only those keys, preserving others.
+- Helper methods (`set_default_download_directory`, `set_accept_languages`, etc.) are provided for common scenarios.
+- Preferences are applied before browser launch, ensuring all settings take effect from the start of the session.
+- Validation ensures only dictionaries are accepted; invalid structures raise clear errors.
+
+## Example
+```python
+options = ChromiumOptions()
+options.browser_preferences = {
+    'download': {'default_directory': '/tmp', 'prompt_for_download': False},
+    'intl': {'accept_languages': 'en-US,en'},
+    'profile': {'default_content_setting_values': {'notifications': 2}}
+}
+```
+
+## Advanced Usage
+- **Merging:** Multiple assignments merge keys, so you can incrementally build your preferences.
+- **Validation:** If you pass a non-dict or use the reserved 'prefs' key, an error is raised.
+- **Internals:** Preferences are set via a recursive setter that creates nested dictionaries as needed.
+- **Integration:** Used by the browser process manager to initialize the user data directory with your custom settings.
+
+## Best Practices
+- Use helper methods for common patterns; set `browser_preferences` directly for advanced needs.
+- Check Chromium documentation for available preferences: https://chromium.googlesource.com/chromium/src/+/4aaa9f29d8fe5eac55b8632fa8fcb05a68d9005b/chrome/common/pref_names.cc
+- Avoid setting experimental or undocumented preferences unless you know their effects.
+
+## References
+- See `pydoll/browser/options.py` for implementation details.
+- See tests in `tests/test_browser/test_browser_chrome.py` for usage examples.

docs/features.md

@@ -662,6 +662,55 @@ These network analysis capabilities make Pydoll ideal for:
 - **Debugging**: Identify failed requests and network issues
 - **Security Testing**: Analyze request/response patterns
 
+## Custom Browser Preferences
+
+Pydoll now supports advanced browser customization through the `ChromiumOptions.browser_preferences` property. This allows you to set any Chromium browser preference for your automation session.
+
+### What You Can Customize
+- Download directory and prompt behavior
+- Accepted languages
+- Notification blocking
+- PDF handling
+- Any other Chromium-supported preference
+
+### Example: Setting Preferences
+```python
+from pydoll.browser.chromium import Chrome
+from pydoll.browser.options import ChromiumOptions
+
+options = ChromiumOptions()
+options.browser_preferences = {
+    'download': {
+        'default_directory': '/tmp/downloads',
+        'prompt_for_download': False
+    },
+    'intl': {
+        'accept_languages': 'en-US,en,pt-BR'
+    },
+    'profile': {
+        'default_content_setting_values': {
+            'notifications': 2  # Block notifications
+        }
+    }
+}
+
+# Helper methods for common preferences
+options.set_default_download_directory('/tmp/downloads')
+options.set_accept_languages('en-US,en,pt-BR')
+options.prompt_for_download = False
+
+browser = Chrome(options=options)
+```
+
+You can call `browser_preferences` multiple times—new keys will be merged, not replaced.
+
+### Why is this useful?
+- Fine-grained control for scraping, testing, or automation
+- Avoid popups or unwanted prompts
+- Match user locale or automate downloads
+
+---
+
 ## File Upload Support
 
 Seamlessly handle file uploads in your automation: