Repository Public
1# Architecture — SP Browser23SP Browser est une application macOS native (Swift 6, concurrence stricte) : AppKit pour le cycle de vie, les fenêtres et les menus ; SwiftUI pour toute l'interface ; **WebKit (`WKWebView`) comme moteur de rendu**. SP Browser n'est pas un moteur web : la compatibilité des sites est celle de WebKit.45## Arborescence67```8SPBrowser/9 App/ main.swift, AppDelegate (cycle de vie, menus), AppEnvironment (racine de composition), Intents10 Core/ logique métier sans interface — compilée aussi comme paquet SwiftPM pour `swift test`11 Navigation/ AddressResolver (texte saisi → URL ou recherche)12 Search/ moteurs de recherche et raccourcis13 Security/ URLSafety (verdict de navigation), URLInspector (signaux d'adresse trompeuse), DownloadSafety, Keychain14 Storage/ SQLiteDatabase (+ migrations), JSONFileStore (écriture atomique, mise à l'écart des fichiers corrompus)15 History/ Bookmarks/ magasins SQLite, import/export HTML Netscape16 Tabs/ modèles de session, SessionStore (sauvegarde + copie de secours)17 Profiles/ profils, journalisation respectueuse de la vie privée18 Permissions/ décisions par site19 ContentBlocking/ génération des règles WKContentRuleList, analyse de listes20 Automation/ catalogue de commandes, raccourcis, scripts utilisateur21 AI/ fournisseurs, requêtes/réponses, construction des invites22 Settings/ AppSettings et sa migration23 BrowserEngine/ (WebKit, exclu du paquet) BrowserTab + délégués, ProfileContext, DownloadManager, ContentBlockerService, PageScripts24 Features/ vues SwiftUI : BrowserWindow, Sidebar, CommandBar, StartPage, Library, DeveloperTools, Intelligence, Settings25 DesignSystem/ jetons (couleurs, rayons), composants communs26 Resources/ Info.plist, entitlements, Assets.xcassets, en.lproj, fr.lproj27 Tests/ CoreTests (SwiftPM), AppTests (hébergés dans l'application)28Assets/Brand/ sources SVG de l'icône et script de génération29scripts/ build, test, release, notarisation, vérification, performance, localisation30```3132Le projet Xcode est généré par `xcodegen` à partir de `project.yml` ; le même code `Core/` est compilé dans l'application et dans le paquet `Package.swift`, sans duplication.3334## Couches et dépendances3536```37Vues SwiftUI ──observent──▶ BrowserWindowState ──possède──▶ BrowserTab ──possède──▶ WKWebView38 │ │39 ▼ ▼40 AppEnvironment ◀── protocole EngineEnvironment (réglages, bloqueur, téléchargements, scripts)41 │42 ▼43 magasins Core (SQLite / JSON / Trousseau)44```4546- **Injection de dépendances** : `AppEnvironment` construit tout à partir d'un dossier racine et d'un `SecretStore`. Les tests passent un dossier temporaire et un magasin de secrets en mémoire. Les onglets ne connaissent que les protocoles `EngineEnvironment` et `TabHost`.47- **Une seule voie pour les actions** : menus, raccourcis, palette ⌘K et App Intents passent tous par `BrowserWindowState.perform(_: CommandID)` ; l'activation est décidée par `isEnabled(_:)`. Les menus sont construits à partir du catalogue, ils ne peuvent donc pas diverger des raccourcis affichés.4849## Cycle de vie des vues web5051- **Un `WKWebView` par onglet chargé**, possédé par `BrowserTab`. Changer d'onglet ne recharge rien : la vue hôte SwiftUI (`WebViewHost`) rattache simplement la vue web existante.52- **Restauration paresseuse** : à la relance, seul l'onglet sélectionné de chaque fenêtre crée sa vue web ; les autres attendent d'être affichés (`interactionState` de WebKit conservé pour l'historique précédent/suivant).53- **Suspension** : un onglet d'arrière-plan inactif depuis N minutes (réglable, 30 par défaut, jamais les onglets épinglés ni l'onglet visible) libère sa vue web en gardant adresse, titre et `interactionState`.54- **Pas de cycles de rétention** : le délégué WebKit (`TabCoordinator`) tient l'onglet en `weak` ; l'onglet tient son hôte en `weak` ; les observations KVO sont invalidées dans `tearDownWebView()` ; le service de blocage référence les `WKUserContentController` par table faible.55- **Plantage du processus de contenu** : `webViewWebContentProcessDidTerminate` affiche une page dédiée avec rechargement ; les autres onglets (autres processus) ne sont pas touchés.56- **Fenêtres ouvertes par les pages** (`window.open`, `target=_blank`) : `createWebViewWith` crée un onglet avec exactement la configuration fournie par WebKit, comme l'API l'exige.5758## Profils et isolement5960| Contexte | Magasin WebKit | Historique | Signets / notes | Permissions |61|---|---|---|---|---|62| Profil | `WKWebsiteDataStore(forIdentifier: <UUID du profil>)`, persistant, distinct | SQLite du profil | SQLite du profil | JSON du profil |63| Fenêtre privée | `WKWebsiteDataStore.nonPersistent()`, neuf à chaque contexte | aucun (base en mémoire, jamais écrite) | ceux du profil parent (ajout explicite) | en mémoire |6465L'identifiant du profil par défaut est aléatoire et propre à chaque dossier de données : deux dossiers (application réelle, tests, démonstration) ne partagent jamais un magasin WebKit. Vérifié par tests : cookies distincts entre profils, magasin privé vide et non persistant, aucune écriture d'historique en privé.6667## Persistance6869| Donnée | Support | Garanties |70|---|---|---|71| Historique, signets, notes | SQLite par profil (`profile.sqlite`), WAL | Migrations ajoutées en fin de liste, suivies par `PRAGMA user_version`, chacune dans une transaction (testé : v1 → v2 sans perte, retour arrière si échec) ; requêtes paramétrées |72| Réglages, permissions, espaces, scripts, listes, téléchargements | JSON | Écriture atomique ; champs absents d'un ancien fichier = valeur par défaut ; fichier illisible renommé `.corrupt-<horodatage>` |73| Session | `Sessions/session.json` + `session.backup.json` | Écriture atomique, copie de secours de la dernière version valide, repli automatique, mise à l'écart si tout est illisible |74| Clés d'API | Trousseau macOS | Jamais dans les réglages, journaux ou adresses |75| Données de sites | WebKit | Par profil ; effacement par site ou global |7677## Journalisation7879`Log.event` écrit dans le journal unifié en développement et, seulement si l'utilisateur l'active, dans `diagnostics.log` (local). Les adresses sont réduites à `schéma://hôte`. Aucune télémétrie, aucun envoi.8081## Limites structurelles connues8283- Le compteur d'éléments bloqués n'existe pas : WebKit applique les règles sans rien rapporter.84- Les favicons sont en mémoire seulement (les onglets restaurés affichent une initiale jusqu'à leur chargement).85- Reprise d'un téléchargement : possible seulement si le serveur fournit des données de reprise et tant que l'onglet d'origine existe.86- Fichiers locaux : l'accès est limité au fichier ouvert (bac à sable) ; ses ressources voisines ne sont pas lisibles.87