312 lines
27 KiB
Markdown
312 lines
27 KiB
Markdown
# macOS Browser Modularization Roadmap
|
||
|
||
Status: **DRAFT** · 2026-10-06 · analysis of `alex/spm-browser-package` (6a2217fbf3)
|
||
Related: [[projects/vscode-migration/vscode-migration]] · [[projects/vscode-migration/findings]]
|
||
|
||
## TL;DR
|
||
|
||
- The macOS browser code is now one SwiftPM target, `DuckDuckGo_Privacy_Browser`: **1,406 Swift files, ~271k lines, 103 feature folders**. It builds from Xcode and VSCode. **We are here.**
|
||
- Inside that target almost everything depends on everything. 93 of the 103 folders form **one dependency cycle**. A module can't be split off until the cycle is broken. So the next work is mostly **removing a few hubs**, not moving files.
|
||
- Six hubs cause most of the coupling:
|
||
- the `AppDelegate` service locator: 273 files, ~45 services;
|
||
- `UserText`: 275 files;
|
||
- feature flags reached through the app delegate: ~200 files;
|
||
- `GeneralPixel`: 115 files;
|
||
- `Preferences`: it holds both the settings models and the Settings UI;
|
||
- `Tab` with `TabExtensions`: every feature's tab extension is registered in one place.
|
||
- Proposed order:
|
||
1. Foundation modules.
|
||
2. Contracts and dependency injection.
|
||
3. Settings split.
|
||
4. Leaf features (can start at once).
|
||
5. Tab core.
|
||
6. Mid-tier features.
|
||
7. Shell.
|
||
|
||
Each step is a series of small PRs, and the app keeps building at every step.
|
||
- The sharing candidates with iOS are listed in [Cross-platform packages](#cross-platform-packages-ios--macos).
|
||
|
||
---
|
||
|
||
## Part 1: The road so far (VSCode migration)
|
||
|
||
| # | Step | Result | Status |
|
||
|---|---|---|---|
|
||
| 1 | Move non-Swift code (ObjC/C) to local packages | App target is Swift-only | ✅ Jun 2025 |
|
||
| 2 | Missing imports, unused files cleanup | Files compile outside the app target | ✅ Jun 2025 |
|
||
| 3 | Unify WebKit private methods; drop `#if SPARKLE/APPSTORE` | DMG and App Store targets compile the same files | ✅ Mar 2026 |
|
||
| 4 | Drop dead target flags (`SANDBOX_TEST_TOOL`, `ALPHA`, `NETWORK_EXTENSION` in shared files) | One set of compilation conditions | ✅ #6983 |
|
||
| 5 | Replace sandbox-test-tool with App Store UI tests | No extra target compiles app sources | ✅ #6980 |
|
||
| 6 | Drop storyboards (Feedback, PasswordManager, BookmarksBar, NavigationBar) | No IB module bindings to the app module | ✅ / last one in review |
|
||
| 7 | Asset resource initializers (`NSImage(resource:)`) instead of generated symbol extensions | Asset catalogs work from a package | ✅ committed |
|
||
| 8 | **Target file split**: stages A–X below | No app file is compiled into a helper target | 🔄 A+B in review, C ready, G done; the rest is shared by path |
|
||
| 9 | **Browser code as a SwiftPM package** (static lib for the app, dylib for VSCode; strings, assets, Core Data models and JSON in `Bundle.module`) | `swift build` + SourceKit-LSP; run and debug from VSCode | 🔄 **← we are here** (PR #7080, draft) |
|
||
|
||
### Target split stages (step 8)
|
||
|
||
The goal was a clean app directory: no file in `macOS/DuckDuckGo/` is compiled into the VPN agent, the PIR agent or the NetP extensions. Without that, the directory can't be one package target. We didn't move everything. Files that helpers still need stay **shared by path**: the helper targets compile them from the package folder.
|
||
|
||
| Stage | What | Where it goes | Status |
|
||
|---|---|---|---|
|
||
| A | `ApplicationBuildType`, `BuildFlags`, `DuckDuckGoUserAgent` | `AppKitExtensions` | ✅ in review (#7029) |
|
||
| B | DBP feature flagger, auth manager builder, settings environment, WebKit/Safari version providers | `DataBrokerProtection-macOS` | ✅ in review (#7029) |
|
||
| C | `NetworkProtectionPixelEvent` | `NetworkProtectionMac` → `VPNPixels` product | ✅ ready (`move-vpn-pixel-event`) |
|
||
| G | 10 helper-only sources | `DuckDuckGoVPN/`, `HelperTargetsShared/` | ✅ done |
|
||
| **— browser package split off here (we are here) —** | | | |
|
||
| D | Subscription pixels, environment, wide-event flag adapter, funnel origin | new shared subscription-support package | ⏸ later (still shared by path) |
|
||
| E1 | TipKit ×4, VPN IPC resources, VPN error recorder, VPN country labels, `VPNSettings+Environment` | `NetworkProtectionMac` | ⏸ later |
|
||
| E2 + H | Shared VPN strings, VPN location formatter; app icons, `macos-config.json`, VPN Lottie files, NetP string catalogs | `NetworkProtectionUI` resources | ⏸ after the per-module strings pattern (Phase 1) |
|
||
| F | `UserDefaultsWrapper`, `UserDefaults+NetworkProtectionShared` | replaced by `KeyedStoring` | ⏸ blocked on the KeyedStoring migration |
|
||
| X | `NETP_SYSTEM_EXTENSION` → runtime check | — | optional, needs VPN team |
|
||
|
||
D, E1, E2+H and F reappear below as part of Phase 1 and Phase 6. Once the strings and storage patterns exist, they are ordinary module extractions.
|
||
|
||
---
|
||
|
||
## Part 2: What the browser package looks like today
|
||
|
||
### Size
|
||
|
||
1,406 Swift files and ~271k lines in one module. The largest folders:
|
||
|
||
| Folder | Lines | Files | | Folder | Lines | Files |
|
||
|---|---:|---:|---|---|---:|---:|
|
||
| AIChat | 24.7k | 95 | | NetworkProtection (app side) | 8.6k | 54 |
|
||
| Tab (+ extensions, user scripts) | 22.2k | 87 | | Statistics | 7.1k | 34 |
|
||
| Common | 17.8k | 148 | | NewTabPage | 6.8k | 41 |
|
||
| NavigationBar | 16.4k | 37 | | Permissions | 6.6k | 32 |
|
||
| Bookmarks | 14.5k | 78 | | Fire | 6.4k | 17 |
|
||
| Preferences | 13.7k | 63 | | Application | 6.3k | 19 |
|
||
| DataImport | 11.8k | 58 | | Menus | 4.8k | 8 |
|
||
| TabBar | 10.1k | 29 | | FileDownload | 4.8k | 23 |
|
||
| SecureVault | 9.5k | 36 | | Onboarding | 4.5k | 31 |
|
||
|
||
Tests: `UnitTests` has 599 files, and 570 of them use `@testable import DuckDuckGo_Privacy_Browser`. `IntegrationTests` has 30 files, 28 of them with that import.
|
||
|
||
### Method
|
||
|
||
I took each top-level folder as a component, with second-level folders for `Common`, `Tab` and `NetworkProtection`. For each top-level type or function, I found the folder that declares it. Then I counted, for each folder, the files that reference symbols declared in another folder. Generic names (`Constants`, `Row`, `assert`, …) are excluded. The numbers are approximate. Extension members such as `UserText.foo` are attributed to the folder that declares the type.
|
||
|
||
### Finding 1: one big cycle
|
||
|
||
- 93 of 103 folders (~270k lines) are in **one strongly connected component**: every folder reaches every other one.
|
||
- Even with an ideal foundation layer moved out and the app shell (Application, MainWindow, Windows, Menus, StateRestoration) moved on top, **58 feature folders (~210k lines) still form a cycle**.
|
||
- The foundation folders themselves form a smaller cycle: Utilities ↔ Statistics ↔ VisualRefresh ↔ View ↔ Favicons ↔ Fireproofing ↔ Database ↔ FileSystem ↔ OSVersion.
|
||
|
||
So extracting a "big" feature now (Bookmarks, AIChat, Tab) means going through every hub first. The hubs come first.
|
||
|
||
### Finding 2: the hubs
|
||
|
||
| Hub | Where | Used by | What it is | Why it blocks |
|
||
|---|---|---|---|---|
|
||
| **App delegate service locator** | `Application/AppDelegate.swift` (2,810 lines) | 273 files | `Application.appDelegate.x` / `NSApp.delegateTyped.x` for ~45 services. Top: `windowControllersManager` 220, `featureFlagger` 103, `themeManager` 70, `subscriptionManager` 39, `webExtensionManager` 31, `privacyFeatures` 30, `faviconManager` 27 | Any file that uses it depends on the whole app |
|
||
| **Strings** | `Common/Localizables/UserText*.swift`, `Localizable.xcstrings` (1,980 keys) | 275 files | One `UserText` namespace for all features | A module needs its own strings |
|
||
| **Pixels** | `Statistics/GeneralPixel.swift` and friends | `GeneralPixel` in 115 files | One pixel enum for unrelated features; `Statistics` also refers back to `MainWindow`, `Menus`, `Permissions`, `Preferences`, `Onboarding` | Statistics can't go to the foundation layer |
|
||
| **Preferences** | `Preferences/Model` + `Preferences/View` | 54 folders depend on it, and it depends on 36 | Holds every feature's settings model (`AppearancePreferences` 37 files, `TabsPreferences` 16, `WebTrackingProtectionPreferences` 16, `AutofillPreferences` 15, …) **and** the Settings window that shows every feature's pane | Settings models must sit below features, the Settings UI above them |
|
||
| **Tab** | `Tab/Model`, `Tab/TabExtensions`, `TabBar/TabCollectionViewModel` | `Tab` 98 files, `TabCollectionViewModel` 48 | `TabExtensions.swift` registers all 30 feature tab extensions (AIChat, Autofill, Downloads, DuckPlayer, History, Privacy Dashboard, …) in one builder | Tab depends on every feature, and every feature depends on Tab |
|
||
| **Window management** | `Windows/WindowControllersManager*` | `WindowControllersManagerProtocol` in 58 files | Used to "open a tab", "show settings", "find the key window" | Features need a small navigation API, not the window manager |
|
||
| **Theme** | `VisualRefresh/Theme*` | 31 folders | `ThemeManaging`, `ThemeStyleProviding` | Fine as foundation, but depends on `AppearancePreferences` |
|
||
| **Promotions** | `Promotions/PromoTypes` + `Promotions/Promos` | 19 folders | Promo framework (types) + registration of every feature's promo | The types are foundation; the registration belongs in the shell |
|
||
| **Common/Extensions** | 71 files | 9 folders | Mostly generic, but some refer to `AppDelegate`, `Bookmarks`, `Preferences`, `MainViewController` | Has to be cleaned before it can go to the foundation layer |
|
||
| **Custom `assert`** | `Common/Utilities/Assertions.swift` | 178 + 68 files | Module-wide replacement of `assert`/`assertionFailure` for tests | Every extracted module needs it, so it goes in a foundation module |
|
||
|
||
### Finding 3: some features are already loose
|
||
|
||
Features ranked by how many symbols they use from other features or the shell (ignoring the foundation candidates). These can be extracted almost right away:
|
||
|
||
| Feature | Lines | Uses from other features / shell |
|
||
|---|---:|---|
|
||
| CrashReports, Geolocation, Sharing, NetP ExcludedApps | 0.4–0.5k each | nothing |
|
||
| AttributedMetric, DeviceAuthentication, FindInPage, UnifiedFeedbackForm, UserNotifications, Waitlist | 0.4–1.7k | 1 symbol (e.g. `Application`, `AutofillPreferences`, `MainWindow`) |
|
||
| AppHealth | 3.2k | `WindowControllersManager` only |
|
||
| MaliciousSiteProtection, TabPreview, JSAlert, PasswordManager, DBP, Updates | 0.3–2k | 3–5 symbols |
|
||
| AdBlocking, Suggestions, YoutubePlayer (Duck Player), Freemium, Autoconsent | 1–2.5k | 6–9 symbols |
|
||
|
||
At the other end, these need 40 or more symbols from other folders and come last:
|
||
- NavigationBar: 115;
|
||
- Tab/TabExtensions: 83;
|
||
- Preferences: 72;
|
||
- NewTabPage: 71;
|
||
- Tab/Model and Tab/View: 64 each;
|
||
- TabBar: 47;
|
||
- AIChat: 41;
|
||
- Tab/UserScripts: 40.
|
||
|
||
### Finding 4: some of this is already done in local packages
|
||
|
||
Some features are already half-extracted: most of the logic and UI live in a local package, and the app keeps the glue.
|
||
|
||
| Feature | Package | Left in the app |
|
||
|---|---|---|
|
||
| History | `HistoryView` | `History/` |
|
||
| New Tab Page | `NewTabPage` | `NewTabPage/`, `HomePage/` |
|
||
| Updates | `AppUpdater` | `Updates/` |
|
||
| Crash reports | `CrashReporting` | `CrashReports/` |
|
||
| VPN | `NetworkProtectionMac` | `NetworkProtection/AppTargets` |
|
||
| PIR | `DataBrokerProtection-macOS` | `DBP/` |
|
||
| Freemium | `Freemium` | `Freemium/` |
|
||
| VPN waitlist | `Waitlist-macOS` | `Waitlist/` |
|
||
| Sync | `SyncUI-macOS` | `Sync/` |
|
||
| Subscription | `SubscriptionUI` | `Subscription/` |
|
||
| Settings | `PreferencesUI-macOS` | `Preferences/` |
|
||
|
||
That's the existing pattern: the package holds the logic and UI, and the app holds the glue. Merging the glue in is the cheapest kind of extraction.
|
||
|
||
---
|
||
|
||
## Part 3: Target architecture
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────┐
|
||
│ App shell (DuckDuckGoApp + DuckDuckGoBrowserShell) │ composition root: AppDelegate builds
|
||
│ Application, MainWindow, Windows, Menus, StateRestoration, │ services and passes them to features;
|
||
│ NavigationBar & TabBar composition, Settings window, promo │ TabExtensionsBuilder; promo registry;
|
||
│ registration │ menus
|
||
├──────────────────────────────────────────────────────────────┤
|
||
│ Feature modules (one per feature; UI + logic, macOS only) │ depend only on Contracts, Foundation,
|
||
│ Bookmarks, History, Downloads, Permissions, Fire, Autofill, │ and shared packages; never on each
|
||
│ Sync, DuckPlayer, AIChat, VPN app UI, Onboarding, … │ other
|
||
├──────────────────────────────────────────────────────────────┤
|
||
│ BrowserContracts (macOS) │ protocols & value types features use
|
||
│ TabOpening / BrowserNavigating, TabContent, BurnerMode, │ to talk to each other and to the shell
|
||
│ PreferencePaneIdentifier, Promo types, settings models' │
|
||
│ protocols, TabExtension protocol │
|
||
├──────────────────────────────────────────────────────────────┤
|
||
│ Browser foundation (macOS) │ no knowledge of features
|
||
│ BrowserFoundation (Utilities, Extensions, FileSystem, │
|
||
│ Database, OSVersion, Assertions, KeyedStoring adapters), │
|
||
│ BrowserDesignSystem (Common/View, Theme, shared assets), │
|
||
│ BrowserStatistics (ATB, pixel infrastructure) │
|
||
├──────────────────────────────────────────────────────────────┤
|
||
│ Shared packages (iOS + macOS): BrowserServicesKit, Common, │
|
||
│ PixelKit, Persistence, Networking, AIChat, VPN, … │
|
||
└──────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
Rules:
|
||
1. **Features never import other features.** When they must talk, a protocol in `BrowserContracts` defines the call (e.g. `BookmarkStoring` for Suggestions) and the shell passes in the implementation.
|
||
2. **No service locator below the shell.** Dependencies arrive through initializers. `Application.appDelegate` is visible only in the shell module.
|
||
3. **Each module owns its resources:** string catalog (the `#bundle` `NSLocalizedString` shim makes this automatic), assets, Core Data model, JS/JSON.
|
||
4. **Each module owns its tests**, as a package test target that runs with `swift test` and from VSCode.
|
||
5. **Start with targets in the same `Package.swift`.** New targets in `macOS/DuckDuckGo/Package.swift` use `path: "Bookmarks"` and so on, and the main target adds that folder to `exclude`. The files don't move and the git history stays intact. Splitting into separate packages, or moving to `SharedPackages`, can come later.
|
||
6. **Measure build time.** More modules don't automatically mean a faster clean build: each module adds scan, emit-module and compile tasks. The gains are incremental-build scope, parallel compilation of independent modules, SwiftUI previews, ownership and sharing. Run a benchmark before and after the first two or three extractions.
|
||
|
||
---
|
||
|
||
## Part 4: Roadmap
|
||
|
||
Each phase is a set of small PRs, and the app builds and the tests pass after each one. Phases 1–3 mostly break dependencies, and files move into new targets as each folder gets clean. Phase 4 can run in parallel with Phase 1.
|
||
|
||
### Phase 1: Foundation modules (break the lowest cycle)
|
||
|
||
| Step | Module | Contents | Work needed | Size |
|
||
|---|---|---|---|---|
|
||
| 1.1 | `BrowserFoundation` | `Common/Utilities` (incl. `Assertions`, `PublishedAfter`, `UserDefaultsKeys`), `Common/Extensions`, `Common/FileSystem`, `Common/Database`, `Common/OSVersion`, `InternalUserDecider`, `UserAgent` | Move ~12 feature-aware extensions out of `Common/Extensions` to their owners (the ones that use `AppDelegate`, `MainViewController`, `BookmarkPasteboardWriter`, `DataClearingPreferences`, `DuckURLSchemeHandler`, …). Make `assert`/`assertionFailure` `public` and import it in every module | ~9k lines, M |
|
||
| 1.2 | Storage: `KeyedStoring` instead of `UserDefaultsWrapper` | 53 files use `UserDefaultsWrapper` | This is stage **F**. Until it's done, `UserDefaultsWrapper` lives in `BrowserFoundation` | ongoing, per feature |
|
||
| 1.3 | `BrowserDesignSystem` | `Common/View` (AppKit/SwiftUI/Lottie views), `VisualRefresh` (theme), `MessageViews`, `InfoViews`, shared colors and icons from `Assets.xcassets` | Move `ThemeAppearance` out of `Preferences` and put the theme API behind `ThemeManaging`. Split `Assets.xcassets`: shared design tokens go here, feature icons go to features (572 image sets, 230 color sets) | ~7k lines, M |
|
||
| 1.4 | Strings | `UserText` (1,980 keys) | Set the pattern: each module has its own `Localizable.xcstrings` and a `UserText` extension. A script moves keys to the module that uses them; common ones (OK, Cancel, …) go to `BrowserDesignSystem`. Check `loc_export.sh` and the translation import with several catalogs. This unblocks **E2 + H** | tooling S, then per feature |
|
||
| 1.5 | `BrowserStatistics` | `Statistics/ATB`, `StatisticsLoader`, `LocalStatisticsStore`, pixel helpers | Split `GeneralPixel` per feature; per-feature pixel enums already exist for History, NTP, Settings, Permissions and others. Remove the back references to `MainWindow`, `Menus`, `Permissions`, `Preferences`, `Onboarding` | ~7k lines, M |
|
||
| 1.6 | Favicons, Fireproofing, UnprotectedDomains | Data services that many features need | `Favicons` → `BookmarkManager` goes through a protocol. Each keeps its Core Data model | ~4k lines, S |
|
||
|
||
Exit criterion: the foundation modules have no cycle and import no feature code.
|
||
|
||
### Phase 2: Contracts and dependency injection (break the hubs)
|
||
|
||
| Step | What | How |
|
||
|---|---|---|
|
||
| 2.1 | `BrowserContracts` module | Value types and protocols that features share today: `TabContent`, `BurnerMode`, `LinkOpenBehavior`, `NewWindowPolicy`, `PreferencePaneIdentifier`, `Promotions/PromoTypes` (already a separate folder), `TabIdentifier`, `SubscriptionFunnelOrigin`, the `TabExtension` protocol |
|
||
| 2.2 | Narrow navigation API | Replace `WindowControllersManagerProtocol` in features (58 files) with small protocols: `TabOpening` (open URL / tab content in the current or a new window), `SettingsPresenting`, `KeyWindowProviding`. The shell implements them on top of `WindowControllersManager` |
|
||
| 2.3 | Remove the service locator, feature by feature | For each feature, constructor-inject what it reads from `Application.appDelegate`: `featureFlagger` (103 uses), `themeManager` (70), `subscriptionManager` (39), `privacyFeatures`, `faviconManager`, … Track the count: 273 files → 0 outside the shell. Most of the work is per feature, so it happens in Phases 4–6 |
|
||
| 2.4 | Settings split | Move each settings model from `Preferences/Model` into its feature or contract (`AppearancePreferences` → design system/theme; `TabsPreferences` → tab core; `DownloadsPreferences` → Downloads; `AutofillPreferences` → Autofill; `DuckPlayerPreferences` → Duck Player; `WebTrackingProtectionPreferences`, `CookiePopupProtectionPreferences` → Privacy Protections; …). The Settings window (`Preferences/View` + `PreferencesUI-macOS`) stays at the top. Each feature provides its pane through a `SettingsPaneProviding` protocol and the shell assembles the sidebar |
|
||
| 2.5 | Promotions split | `PromoTypes` + `PromoService` → contracts/foundation. `Promotions/Promos/PromoServiceFactory+*.swift` (19 files, one per feature) stays in the shell |
|
||
|
||
Exit criterion: no feature folder refers to `Application`, `AppDelegate`, `MainWindowController` or `WindowControllersManager`. Check it with a lint rule or a dependency script in CI.
|
||
|
||
### Phase 3: Leaf feature modules (can start right after 1.1)
|
||
|
||
These can be extracted with almost no refactoring. Use them to test the pattern (package target, strings, tests, VSCode).
|
||
|
||
| Order | Module | Merge into | Notes |
|
||
|---|---|---|---|
|
||
| 1 | CrashReports | `CrashReporting` package | 0 cross-feature deps |
|
||
| 2 | Geolocation, Sharing, FindInPage, DeviceAuthentication, UserNotifications | new targets | 0–1 deps each |
|
||
| 3 | AppHealth | new target | Needs only `KeyWindowProviding` (2.2) |
|
||
| 4 | UnifiedFeedbackForm, Feedback (the core, not `QuitSurvey`) | new `Feedback` target | Feedback needs `Tab`/`Fire` → contracts |
|
||
| 5 | Updates | `AppUpdater` | Promo types from 2.5 |
|
||
| 6 | Waitlist, VPN ExcludedApps/ExcludedDomains | `Waitlist-macOS`, `NetworkProtectionMac` | |
|
||
| 7 | MaliciousSiteProtection, AttributedMetric | new targets / `AttributedMetric` shared package | |
|
||
| 8 | DBP, Freemium | `DataBrokerProtection-macOS`, `Freemium` | Freemium ↔ DBP dependency goes through a protocol |
|
||
| 9 | PasswordManager (Bitwarden) | `BWIntegration` | Needs `AutofillPreferences` from 2.4 |
|
||
| 10 | Suggestions | new target | Needs `BookmarkStoring` and `HistoryProviding` contracts |
|
||
| 11 | Duck Player (`YoutubePlayer`) + AdBlocking | new target | Settings model from 2.4 |
|
||
|
||
### Phase 4: Tab core
|
||
|
||
This is the biggest single refactor, because the tab is where all features meet.
|
||
|
||
| Step | What |
|
||
|---|---|
|
||
| 4.1 | `BrowserTabCore` module: `Tab`, `TabContent`, `TabCollection`, `TabCollectionViewModel`, `TabViewModel`, lazy loading, `TabExtension` registry, navigation responders, base user scripts. `Tab.swift` is 1,686 lines |
|
||
| 4.2 | Invert the tab extensions: each of the 30 `*TabExtension.swift` files moves into its feature module (`HistoryTabExtension` → History, `DownloadsTabExtension` → Downloads, `AIChatTabExtension` → AIChat, …). `TabExtensionsBuilder.registerExtensions` stays in the shell and registers each feature's extension factory. The typed accessors (`tab.extensions.history`) become extensions declared in each feature |
|
||
| 4.3 | Split `Tab/UserScripts` the same way: each feature provides its user scripts, and `UserScripts` builds the list from the registry |
|
||
| 4.4 | `Tab/View` (`BrowserTabViewController`, `WebViewContainerView`) stays in the shell or a `BrowserTabUI` module. Content pages (NTP, Settings, Bookmarks manager, History view, DBP, Duck.ai) are provided through a `TabContentViewProviding` registry, not a switch over every feature |
|
||
|
||
### Phase 5: Mid-tier feature modules
|
||
|
||
After Phases 1–4, these depend only on contracts and the foundation. Suggested order: least coupled first, and features with an iOS counterpart early (see Part 5).
|
||
|
||
| Module | Folders | Merge into / new | Main blockers removed earlier |
|
||
|---|---|---|---|
|
||
| Permissions | `Permissions`, `Geolocation` | new | Settings models (2.4), `UserDialogRequest` → contracts |
|
||
| Downloads | `FileDownload` | new | `FireWindowSessionRef`, `MainMenu` → contracts; termination via `ApplicationTerminationDecider` protocol |
|
||
| History | `History`, `RecentlyClosed` model | `HistoryView` | `FireProtocol`, `TabCollection` → contracts |
|
||
| Bookmarks | `Bookmarks`, `BookmarksBar` | new (14.5k + 3.8k lines) | Tab/TabBar types, `DataImport` types → contracts |
|
||
| Fire (data clearing) | `Fire`, `Fireproofing` UI, `Tab/Services` | new | Needs History, Tab core and AIChat history cleaning behind protocols |
|
||
| Privacy protections | `ContentBlocker`, `Autoconsent`, `PrivacyDashboard`, `SmarterEncryption`, `UnprotectedDomains`, `PrivacyStats`, `BrokenSitePrompt` | new | `Onboarding` coupling of `ContentBlocker` goes through a protocol |
|
||
| Autofill & passwords | `SecureVault`, `Autofill`, `PasswordManager`, `DeviceAuthentication` | new + `BWIntegration` | `PinningManager`, `PopoverPresenter`, Sync promo → contracts |
|
||
| Data import | `DataImport`, `DataExport` | new | `SecureVault`, `Bookmarks`, Sync promo → contracts |
|
||
| Sync (app side) | `Sync` | `SyncUI-macOS` | Bookmarks/SecureVault adapters stay in the shell |
|
||
| Subscription (app side) | `Subscription`, subscription user scripts, stage **D** | `SubscriptionUI` / new `SubscriptionSupport` | Stage D package is shared with the helpers |
|
||
| VPN (app side) | `NetworkProtection/AppTargets`, stages **E1/E2/H** | `NetworkProtectionMac` | Navigation, pinning and `Waitlist` → contracts |
|
||
| Onboarding, Default browser & dock prompts, Remote messaging, Promotions UI | | `Onboarding` shared package / new | Promo types (2.5) |
|
||
| New Tab Page | `NewTabPage`, `HomePage` | `NewTabPage` | Each feature provides its NTP section through a protocol (AIChat, Subscription, Next Steps, Remote messages) |
|
||
| Web extensions, Dark Reader | | `WebExtensions` shared package / new | Tab core |
|
||
|
||
### Phase 6: Top layer
|
||
|
||
| Module | Notes |
|
||
|---|---|
|
||
| AIChat (Duck.ai): 24.7k lines | The largest feature, with 41 symbols from Tab, TabBar, Windows and NavigationBar. The logic and the omnibar/sidebar controllers go to a macOS module next to the shared `AIChat` package. Integration with the tab, sidebar and address bar goes through contracts. `PromptBar` comes along |
|
||
| NavigationBar (address bar): 16.4k lines | Uses 115 symbols from other folders: it shows buttons for every feature. Split it into `AddressBar` (text field, suggestions binding, editing) and the shell part that builds the button set from feature-provided `NavigationBarButtonProviding` items. `PinningManager` (38 files) → contracts |
|
||
| TabBar, PinnedTabs, TabPreview | Into `BrowserTabUI`, after the tab core |
|
||
| Shell | `Application`, `MainWindow`, `Windows`, `Menus`, `StateRestoration`, `Automation`, `LogExporter`, the Settings window, promo registration, tab extension registration. This is what's left of `DuckDuckGo_Privacy_Browser`, target ≈ 20–30k lines |
|
||
|
||
### Tracking progress
|
||
|
||
Add these checks to a script and run it in CI:
|
||
|
||
| Metric | Today | Target |
|
||
|---|---:|---:|
|
||
| Lines in `DuckDuckGo_Privacy_Browser` | 271k | ≤ 30k (shell) |
|
||
| Folders in the biggest dependency cycle | 93 / 103 | 0 |
|
||
| Files using `Application.appDelegate` / `NSApp.delegateTyped` | 273 | shell only |
|
||
| Files using `WindowControllersManager(Protocol)` | 78 | shell only |
|
||
| Unit test files with `@testable import DuckDuckGo_Privacy_Browser` | 570 | shell tests only |
|
||
| Keys in the app's `Localizable.xcstrings` | 1,980 | shell strings only |
|
||
|
||
---
|
||
|
||
## Part 5: Cross-platform packages (iOS + macOS)
|
||
|
||
_(see below)_
|
||
|
||
---
|
||
|
||
## Open questions
|
||
|
||
1. **Package layout:** keep all macOS feature modules as targets of `macOS/DuckDuckGo/Package.swift` (files stay in place, one manifest), or create one package per feature in `LocalPackages`? Recommendation: targets in the same package first. Move a module to `SharedPackages` when iOS starts using it.
|
||
2. **Strings tooling:** `loc_export.sh` / the translation pipeline with one catalog per module. This has to be verified before step 1.4 scales.
|
||
3. **KeyedStoring timeline** (stage F): who owns it and when.
|
||
4. **Code ownership:** module boundaries are a good moment to add CODEOWNERS per feature module.
|
||
5. **Build benchmarks:** measure clean and incremental builds after Phase 1 and the first leaf modules, with Xcode and `swift build`.
|