Architecture
┌──────────────────────────── SP Notes.app (SwiftUI + AppKit) ────────────────────────────┐
│ Features/… vues SwiftUI App/ AppEnvironment · WindowModel · SyncMonitor │
│ NoteSession (une par note ouverte) ── EditorController ── NoteTextView (TextKit 2) │
└───────────────┬───────────────────────────────┬─────────────────────────────────────────┘
│ SPNotesEditor (ce dépôt) │ SPNotesCore (../SPNotesCore, partagé avec iOS)
│ codec · styliseur · fragments │ SPNotesDocument · SPNotesStore · SPNotesAPI · SPNotesSync
▼ ▼
NSTextStorage SQLite (WAL, FTS5) ⇄ https://note.spboucher.ai 1. Éditeur natif (Editor/, paquet SPNotesEditor)
Le serveur stocke une note en JSON ProseMirror. Le module partagé SPNotesDocument l'aplatit en lignes : un bloc de
texte ou un bloc atomique, avec la chaîne de ses conteneurs (liste, élément, citation, encadré…). L'éditeur travaille sur un
NSTextStorage qui porte cette structure :
| Dans le stockage texte | Signification |
|---|---|
attribut sp.para (ParaStyle, même objet sur tout le paragraphe) |
la ligne sans son contenu : type, attributs, conteneurs. Les lignes d'un bloc de code partagent un même objet. |
attribut sp.marks (MarkSet) |
les marques brutes du passage (y compris celles que l'app ne connaît pas) |
caractère de pièce jointe + AtomAttachment |
un nœud édité d'un bloc : tableau, image, équation, fichier, mention, nœud inconnu |
\n final de chaque paragraphe, y compris le dernier |
porte les attributs du paragraphe : un paragraphe vide a un style et dessine sa puce |
DocumentCodecconvertit dans les deux sens, sans perte (test : tous les types du schéma web, puis édition + annulation).Stylerdérive polices, couleurs, retraits et décorations pour les seuls paragraphes touchés (élargis à la liste ou au bloc de code qui les contient). Jamais de reconstruction du document à la frappe : 3 ms par touche dans un document de 4 000 blocs.BlockLayoutFragment(NSTextLayoutFragment) dessine puces, numéros, cases à cocher, barres de citation, panneaux de code et d'encadré. Ces décorations ne sont pas des caractères : elles ne polluent ni la sélection ni le presse-papiers.NoteTextView(NSTextViewsur TextKit 2) : Entrée, Tab, Retour arrière structurés ; raccourcis Markdown ; menu « / » et « @ » ; primitivereplace(_:with:)par laquelle passe toute commande (une étape d'annulation, historique propre à la note).applyRemoteapplique un document venu d'ailleurs en ne remplaçant que les lignes qui diffèrent : le curseur ne bouge pas quand le changement est ailleurs, et les conteneurs voisins sont réalignés pour qu'une liste ne soit pas coupée.- Identifiants de blocs : générés à la création (même alphabet que le site), donc stables d'un enregistrement à l'autre et identiques à ce que le serveur attend.
2. Persistance (SPNotesStore)
Un fichier SQLite par serveur dans le conteneur de l'application (Application Support/SPNotes/notes-<hôte>.sqlite), mode WAL,
synchronous=FULL : une écriture confirmée survit à une coupure de courant. Chaque page garde son contenu, sa copie de base
(dernier état commun avec le serveur, pour la fusion), ses champs modifiés, et l'index plein texte FTS5 est mis à jour dans la
même transaction. Les pièces jointes sont des fichiers à côté (files-<hôte>/<id>.<ext>), référencés par chemin relatif.
NoteSession enregistre 350 ms après la dernière frappe, à la perte de focus de l'application, à la fermeture, et avant de
quitter (applicationShouldTerminate attend l'écriture et un point de contrôle). Un instantané d'historique local est pris
avant une salve de modifications (au plus toutes les dix minutes) et à chaque ⌘S.
3. Synchronisation (SPNotesSync + App/SyncMonitor)
Le serveur numérote chaque écriture (rev, migration 0002, voir AUDIT.md §7). Un cycle :
- créations (parents d'abord, identifiant choisi par le client, clé d'idempotence) ;
- envoi des fichiers joints ;
- métadonnées, tags, puis contenu avec
baseVersion; - file d'actions (corbeille, restauration, suppression définitive) ;
- lecture de
/api/sync?since=<curseur>jusqu'à épuisement ; application atomique, jamais par-dessus un contenu local modifié ; - téléchargement des images.
L'application déclenche un cycle au lancement, 2 s après une modification locale, au retour du réseau, au retour au premier plan et toutes les 75 s quand elle est active.
Conflits
| Situation | Résultat |
|---|---|
| Le serveur a la même chose que ce Mac | adopté, rien à faire |
| Deux appareils ont modifié des blocs différents | fusion à trois voies (base / local / serveur), renvoyée au serveur |
| Même bloc modifié des deux côtés, ou modification contre suppression | conflit enregistré : la copie locale reste intacte, la copie du serveur est gardée à côté ; bandeau dans la note, comparaison côte à côte, trois issues (la mienne / celle du serveur / les deux). Le serveur conserve les deux dans son historique quel que soit le choix. |
| Frappe non encore enregistrée au moment où un changement distant arrive | même fusion dans NoteSession ; si elle est impossible, la copie distante est versée dans l'historique local avant d'être remplacée, et un bandeau le dit |
| Suppression définitive ailleurs d'une note ouverte ici | la note passe en lecture seule avec « Enregistrer comme nouvelle note » |
Il n'y a nulle part de « dernier qui écrit gagne » silencieux.
4. Fenêtres
WindowGroup principal (plusieurs fenêtres) et un groupe « une fenêtre par note ». Les fenêtres partagent AppEnvironment ;
chacune a son WindowModel (sélection, panneaux). Deux fenêtres sur la même note partagent la même NoteSession, donc le même
texte et le même historique d'annulation. La vue AppKit de l'éditeur appartient à la session : SwiftUI l'héberge sans jamais la
reconstruire.
5. Ce que l'application ne fait pas
Voir FEATURE_MATRIX.md (lignes « — ») : bases de données, graphe, agents, recherche sémantique, tâches, poignée de
glisser-déposer par bloc, mise à jour automatique.
6. SP Notes 2.0 (branche next)
- Ouverture de la base :
AppEnvironmentappelleNotesStore.open(résultat typé). En cas d'échecstoreFailureest renseigné,MainWindow.root(for:)ne rend queStoreFailureView,start()ne démarre rien et chaque point d'entrée qui écrit (LibraryModel.newNote,session(for:), capture, Services, import) refuse. La copie d'avant migration est gardée 30 jours (AppEnvironment.backupRetention). - Navigation (
App/Navigation.swift) :Destination(notes + écrans),Route(pageId, blockId?),DeepLink.WindowModelporte la destination, la route en attente et sa propreLibraryModel(sélection, recherche, liste) ;env.libraryreste le modèle partagé qui prévient les sessions ouvertes. - Couche d'accueil des écrans : protocole
FeatureHosting(isAvailable,screen(for:),badge).NativeFeatureHostfournit Tâches, Boîte de réception et Recherche surNotesRepositories; les autres destinations ne sont pas disponibles et ne sont donc listées nulle part. Remplacerenv.featuressuffit pour brancher SPNotesFeatures. - Blocs :
Editor/AtomCards.swift(modèleAtomCardModel+ dessin),Editor/ChartDrawing.swift,Editor/NextCommands.swift. Côté application,BlockDetailProviding(NativeBlockDetails) fournit les feuilles ;EditorInsertionsest l'unique liste de ce qui s'insère ;EditorLookuprépond aux cartes depuis la base locale sans bloquer le dessin. - Design :
SPNotesDesign(jetons) dans l'application,Editor/EditorTokens.swiftpour AppKit. Les animations passent parNVMotion/withNVAnimation; l'ouverture d'une note estNoteTextView.playReveal(revealPlanest testable). - Plateforme :
Features/Platform/—PlatformServices(Spotlight, rappels, derrière deux protocoles pour les tests),QuickNote.swift(capture).CommandRegistryalimente le centre de commandes.
7. SPNotesFeatures dans l'application (2026-11-19, soir)
Features/Hosting/FeaturesHost.swift:WindowModelest leFeatureRouterdes écrans (openPage,openDatabase,openCanvas,openURL,presentError) ;FeaturesHostassocie chaqueDestinationà un écran de la bibliothèque (ou aux écrans Tâches / Boîte / Recherche de l'app) et ne la déclare disponible que si le serveur annonce la fonction (AppEnvironment.serverMeta, lu après chaque synchronisation et mémorisé par Core).Features/Hosting/FeatureBlockDetails.swift:FeaturesBlockDetails(leBlockDetailProvidingactif) enveloppe les vues de blocs de la bibliothèque dansFeatureBlockSheet; la vue rend un bloc modifié, l'app écrit le nœud.AppEnvironment. attachmentLoader(pageId:)lit les fichiers sur le Mac et range les nouveaux fichiers localement (dessin, enregistrement) : l'envoi est fait par la synchronisation, donc ces blocs s'éditent hors ligne.Features/Hosting/CommandCenterHost.swift: un seul registre (CommandRegistryde la bibliothèque, dansFeatureServices) ;AppCommandCatalogy enregistre les commandes de la fenêtre au premier plan à chaque ouverture.Features/Hosting/NotePages.swift: pages base / canvas natives, zoom sémantique, chronologie d'une note, choix du modèle.- Les produits Debug sont construits hors de
~/Desktop(~/Library/Developer/SPNotes/DerivedData) : un hôte de test en bac à sable qui charge un framework de paquet depuis le Bureau reste bloqué sur une décision de confidentialité.