SPB Git

Repository Public

ARCHITECTURE.md 7.1 KB

# Architecture — SP Browser

SP 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.

# Arborescence

text
SPBrowser/
  App/            main.swift, AppDelegate (cycle de vie, menus), AppEnvironment (racine de composition), Intents
  Core/           logique métier sans interface — compilée aussi comme paquet SwiftPM pour `swift test`
    Navigation/   AddressResolver (texte saisi → URL ou recherche)
    Search/       moteurs de recherche et raccourcis
    Security/     URLSafety (verdict de navigation), URLInspector (signaux d'adresse trompeuse), DownloadSafety, Keychain
    Storage/      SQLiteDatabase (+ migrations), JSONFileStore (écriture atomique, mise à l'écart des fichiers corrompus)
    History/ Bookmarks/   magasins SQLite, import/export HTML Netscape
    Tabs/         modèles de session, SessionStore (sauvegarde + copie de secours)
    Profiles/     profils, journalisation respectueuse de la vie privée
    Permissions/  décisions par site
    ContentBlocking/  génération des règles WKContentRuleList, analyse de listes
    Automation/   catalogue de commandes, raccourcis, scripts utilisateur
    AI/           fournisseurs, requêtes/réponses, construction des invites
    Settings/     AppSettings et sa migration
    BrowserEngine/  (WebKit, exclu du paquet) BrowserTab + délégués, ProfileContext, DownloadManager, ContentBlockerService, PageScripts
  Features/       vues SwiftUI : BrowserWindow, Sidebar, CommandBar, StartPage, Library, DeveloperTools, Intelligence, Settings
  DesignSystem/   jetons (couleurs, rayons), composants communs
  Resources/      Info.plist, entitlements, Assets.xcassets, en.lproj, fr.lproj
  Tests/          CoreTests (SwiftPM), AppTests (hébergés dans l'application)
Assets/Brand/     sources SVG de l'icône et script de génération
scripts/          build, test, release, notarisation, vérification, performance, localisation

Le 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.

# Couches et dépendances

text
Vues SwiftUI ──observent──▶ BrowserWindowState ──possède──▶ BrowserTab ──possède──▶ WKWebView
                                   │                           │
                                   ▼                           ▼
                             AppEnvironment  ◀── protocole EngineEnvironment (réglages, bloqueur, téléchargements, scripts)
                                   │
                                   ▼
                    magasins Core (SQLite / JSON / Trousseau)
  • 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.
  • 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.

# Cycle de vie des vues web

  • 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.
  • 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).
  • 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.
  • 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.
  • Plantage du processus de contenu : webViewWebContentProcessDidTerminate affiche une page dédiée avec rechargement ; les autres onglets (autres processus) ne sont pas touchés.
  • 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.

# Profils et isolement

Contexte Magasin WebKit Historique Signets / notes Permissions
Profil WKWebsiteDataStore(forIdentifier: <UUID du profil>), persistant, distinct SQLite du profil SQLite du profil JSON du profil
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

L'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é.

# Persistance

Donnée Support Garanties
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
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>
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
Clés d'API Trousseau macOS Jamais dans les réglages, journaux ou adresses
Données de sites WebKit Par profil ; effacement par site ou global

# Journalisation

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.

# Limites structurelles connues

  • Le compteur d'éléments bloqués n'existe pas : WebKit applique les règles sans rien rapporter.
  • Les favicons sont en mémoire seulement (les onglets restaurés affichent une initiale jusqu'à leur chargement).
  • 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.
  • Fichiers locaux : l'accès est limité au fichier ouvert (bac à sable) ; ses ressources voisines ne sont pas lisibles.
Files main
Menu

Theme