Repository Public
1<!--2SP Notes (macOS)3File: README.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7<div align="center">89<img src="docs/brand/logo.svg" alt="Logo SP Notes" width="560">1011<br><br>1213<img src="docs/brand/icon.png" alt="Icône SP Notes" width="112" height="112">1415# SP Notes — macOS1617**Application de notes native pour macOS, cliente de note.spboucher.ai : éditeur TextKit 2 écrit sur mesure, tout fonctionne hors ligne, synchronisation par flux de changements avec fusion par blocs et conflits explicites. Aucune vue web, aucun moteur JavaScript.**1819**Auteur : [Simon-Pierre Boucher](https://www.spboucher.ai)**2021[](https://note.spboucher.ai)2223242526272829303132333435363738[](https://git.spboucher.ai/sp-notes-macos/commits)39[](https://git.spboucher.ai/sp-notes-macos/commits)40[](https://git.spboucher.ai/sp-notes-macos/insights)41[](https://git.spboucher.ai/sp-notes-macos)42[](https://git.spboucher.ai/sp-notes-macos/insights)43[](https://git.spboucher.ai/sp-notes-macos)44[](https://git.spboucher.ai/sp-notes-macos/branches)45[](https://git.spboucher.ai/sp-notes-macos/tags)46[](https://git.spboucher.ai/sp-notes-macos)474849505152535455565758596061626364656667</div>6869---7071## Sommaire7273- [Aperçu](#-aperçu)74- [Fonctions](#-fonctions)75- [Architecture](#-architecture)76- [Pile technique](#-pile-technique)77- [Organisation du dépôt](#-organisation-du-dépôt)78- [Compiler et lancer](#-compiler-et-lancer)79- [Configuration](#-configuration)80- [Écrans et intégration macOS](#-écrans-et-intégration-macos)81- [Données locales](#-données-locales)82- [Sécurité et confidentialité](#-sécurité-et-confidentialité)83- [Tests](#-tests)84- [Publication](#-publication)85- [Installation](#-installation)86- [Dépannage et pièges](#-dépannage-et-pièges)87- [Limites connues](#-limites-connues)88- [Documentation](#-documentation)89- [Auteur](#-auteur)90- [Licence](#-licence)9192---9394## 🎯 Aperçu9596Application de notes **native** pour macOS (Swift 6, SwiftUI, AppKit, TextKit 2), cliente de97[note.spboucher.ai](https://note.spboucher.ai). Aucune vue web, aucun moteur JavaScript : l'interface et l'éditeur sont98écrits sur mesure.99100| | |101|---|---|102| Système | macOS 15 ou plus récent · binaire universel (Apple Silicon et Intel) |103| Hors ligne | Tout fonctionne sans réseau ; chaque frappe est enregistrée sur le Mac, la synchronisation reprend seule |104| Synchronisation | MacLustr (note.spboucher.ai) : flux de changements, fusion par blocs, conflits explicites |105| Compte | Clé d'accès (passkey) — ou aucun compte : les notes restent sur le Mac |106| Sécurité | Bac à sable, runtime durci, jeton de session dans le trousseau, signé Developer ID et notarisé |107108<div align="center">109<img src="docs/img/main.png" alt="Fenêtre principale de SP Notes : bibliothèque, liste des notes et éditeur" width="820">110</div>111112### Famille113114| Dépôt | Rôle | Plateforme |115|---|---|---|116| [note-spboucher-ai](https://git.spboucher.ai/note-spboucher-ai) | Application web, API, base de données, flux de synchronisation | Web / PWA — note.spboucher.ai |117| [sp-notes-core](https://git.spboucher.ai/sp-notes-core) | Paquet Swift partagé : modèle de document, base locale, client d'API, moteur de synchronisation | Swift |118| **[sp-notes-macos](https://git.spboucher.ai/sp-notes-macos)** (ce dépôt) | SP Notes pour Mac | macOS 15+ |119| [sp-notes-ios](https://git.spboucher.ai/sp-notes-ios) | SP Notes pour iPhone et iPad | iOS / iPadOS |120121## ✨ Fonctions122123Détail fonction par fonction, avec l'état **vérifié / implémenté / non fait** : [`docs/FEATURE_MATRIX.md`](docs/FEATURE_MATRIX.md).124125| Domaine | Ce que fait l'application |126|---|---|127| **Éditeur** | Document ProseMirror lu et réécrit sans perte (nœuds et attributs inconnus compris) ; paragraphes, titres 1 à 3 ; gras, italique, souligné, barré, code, surligné, lien ; listes à puces, numérotées, de tâches, imbriquées ; citations, encadrés ; blocs de code avec coloration syntaxique native (une douzaine de langages) ; tableaux ; séparateurs ; équations LaTeX en bloc et en ligne (SwiftMath, pas de KaTeX) ; images et fichiers joints |128| **Frappe** | Raccourcis Markdown (`#`, `-`, `1.`, `[]`, `>`, ```` ``` ````, `---`) ; menu « / » des blocs ; menu « @ » des liens entre notes ; Entrée, Tab, Retour arrière structurés ; déplacement de bloc ⌃⌘↑ / ⌃⌘↓ ; annuler / rétablir avec un historique propre à chaque note |129| **Presse-papiers** | Copier-coller structuré (type privé), collage de texte enrichi (RTF), « Coller en Markdown » |130| **Organisation** | Arborescence présentée comme des dossiers, espaces (Notes, Documents, Projets, Recherche), tags, épingles, favoris, archives, corbeille, restauration, suppression définitive, dupliquer, déplacer, renommer, tri |131| **Recherche** | Plein texte locale (SQLite FTS5), hors ligne, avec mise en évidence ; filtres combinés ; ouverture rapide (⌘O) et palette de commandes (⇧⌘P) |132| **Hors ligne** | Tout faire sans réseau (créer, modifier, organiser, chercher, exporter) ; enregistrement local durable 350 ms après la dernière frappe ; file d'envoi persistante, reprise automatique |133| **Synchronisation** | Flux de changements du serveur (`/api/sync`) ; fusion automatique quand deux appareils modifient des blocs différents ; conflit explicite, les deux versions conservées, trois issues ; changement distant appliqué dans l'éditeur ouvert sans déplacer le curseur |134| **Pièces jointes** | Panneau, glisser-déposer, collage ; 200 Mo au plus, types dangereux refusés ; images téléchargées d'office (≤ 25 Mo) ; « Conserver hors ligne » ; Coup d'œil ; empreinte SHA-256 |135| **Historique** | Historique local (100 versions par note au plus) et restauration ; versions du serveur en ligne |136| **Assistant IA** | Actions sur la sélection ou la note : résumer, reformuler, corriger, raccourcir, développer, simplifier, expliquer, plan, points d'action, liste, tâches, tableau, continuer, traduire, consigne libre ; questions sur la note, sur toutes les notes, générales ; proposition affichée avant application, jamais d'écriture silencieuse |137| **Compte** | Connexion par clé d'accès, utilisation sans compte, liste des clés et des appareils, verrouillage local (Touch ID / mot de passe du Mac) |138| **Export / import** | Export Markdown, texte, HTML, RTF, PDF, ZIP ; impression ; partage ; import Markdown, texte, RTF |139| **macOS** | Fenêtres multiples, une fenêtre par note, mode sombre, barre de menus complète, note rapide (⌃⌥⌘N global), icône de barre des menus, service « Nouvelle note SP Notes avec la sélection », liens `spnotes://` |140141<div align="center">142<img src="docs/img/assistant.png" alt="Panneau de l'assistant à droite de l'éditeur" width="820">143</div>144145<details>146<summary><b>Rendu de tous les types de blocs, clair et sombre (rendu hors écran produit par les tests)</b></summary>147148<div align="center">149<img src="docs/img/editor-light.png" alt="Rendu de l'éditeur, apparence claire" width="400">150<img src="docs/img/editor-dark.png" alt="Rendu de l'éditeur, apparence sombre" width="400">151</div>152153</details>154155## 🏗 Architecture156157```mermaid158flowchart TB159 subgraph APP["SP Notes.app (SwiftUI + AppKit)"]160 F["Features/<br/>vues SwiftUI"]161 E["App/<br/>AppEnvironment · WindowModel · SyncMonitor"]162 S["NoteSession<br/>une par note ouverte"]163 C["EditorController"]164 T["NoteTextView<br/>TextKit 2"]165 F --> S166 E --> S167 S --> C --> T168 end169 subgraph ED["SPNotesEditor (ce dépôt, dossier Editor/)"]170 K["DocumentCodec · Styler · BlockLayoutFragment"]171 end172 subgraph CORE["SPNotesCore (../SPNotesCore, partagé avec iOS)"]173 D["SPNotesDocument"]174 ST["SPNotesStore"]175 A["SPNotesAPI"]176 SY["SPNotesSync"]177 end178 T --> K179 K --> D180 S --> ST181 E --> SY182 SY --> ST183 SY --> A184 ST --> DB[("SQLite · WAL · FTS5")]185 A -- HTTPS --> SRV["https://note.spboucher.ai"]186 K --> TS["NSTextStorage"]187```188189### Éditeur natif (`Editor/`, paquet `SPNotesEditor`)190191Le serveur stocke une note en **JSON ProseMirror**. Le module partagé `SPNotesDocument` l'aplatit en **lignes** : un192bloc de texte ou un bloc atomique, avec la chaîne de ses conteneurs (liste, élément, citation, encadré…). L'éditeur193travaille sur un `NSTextStorage` qui porte cette structure :194195| Dans le stockage texte | Signification |196|---|---|197| 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. |198| attribut `sp.marks` (`MarkSet`) | les marques brutes du passage (y compris celles que l'app ne connaît pas) |199| caractère de pièce jointe + `AtomAttachment` | un nœud édité d'un bloc : tableau, image, équation, fichier, mention, nœud inconnu |200| `\n` final de chaque paragraphe, y compris le dernier | porte les attributs du paragraphe : un paragraphe vide a un style et dessine sa puce |201202- **`DocumentCodec`** convertit dans les deux sens, sans perte.203- **`Styler`** dérive polices, couleurs, retraits et décorations **pour les seuls paragraphes touchés**. Jamais de204 reconstruction du document à la frappe : 3 ms par touche dans un document de 4 000 blocs.205- **`BlockLayoutFragment`** (`NSTextLayoutFragment`) dessine puces, numéros, cases à cocher, barres de citation,206 panneaux de code et d'encadré. Ces décorations ne sont pas des caractères : elles ne polluent ni la sélection ni le207 presse-papiers.208- **`NoteTextView`** (`NSTextView` sur TextKit 2) : toute commande passe par la primitive `replace(_:with:)` (une étape209 d'annulation).210- **`applyRemote`** applique un document venu d'ailleurs en ne remplaçant que les lignes qui diffèrent : le curseur ne211 bouge pas quand le changement est ailleurs.212- Identifiants de blocs générés à la création (même alphabet que le site), donc stables d'un enregistrement à l'autre.213214### Un cycle de synchronisation215216```mermaid217sequenceDiagram218 autonumber219 participant N as NoteSession220 participant B as Base locale (SPNotesStore)221 participant M as SyncMonitor / SyncEngine222 participant S as note.spboucher.ai223 N->>B: enregistrement 350 ms après la dernière frappe224 N->>M: cycle demandé (2 s après une modification locale)225 M->>S: créations (parents d'abord, identifiant choisi par le client)226 M->>S: envoi des fichiers joints227 M->>S: métadonnées, tags, puis contenu avec baseVersion228 alt 409 — modifié ailleurs229 M->>B: fusion à trois voies par bloc, sinon conflit enregistré (copie locale intacte)230 end231 M->>S: file d'actions (corbeille, restauration, suppression définitive)232 M->>S: GET /api/sync?since=curseur, jusqu'à épuisement233 M->>B: application atomique, jamais par-dessus un contenu local modifié234 M->>S: téléchargement des images235```236237L'application déclenche un cycle au lancement, 2 s après une modification locale, au retour du réseau, au retour au238premier plan et toutes les 75 s quand elle est active.239240### Conflits241242| Situation | Résultat |243|---|---|244| Le serveur a la même chose que ce Mac | adopté, rien à faire |245| Deux appareils ont modifié des blocs **différents** | fusion à trois voies (base / local / serveur), renvoyée au serveur |246| 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. |247| 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 |248| Suppression définitive ailleurs d'une note ouverte ici | la note passe en lecture seule avec « Enregistrer comme nouvelle note » |249250Il n'y a nulle part de « dernier qui écrit gagne » silencieux. Détail : [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).251252## 🧱 Pile technique253254| Couche | Technologie | Version | Rôle |255|---|---|---|---|256| Langage | Swift, concurrence stricte complète | 6.0 (`SWIFT_VERSION`) | isolation `MainActor` par défaut dans l'application |257| Interface | SwiftUI + AppKit | — | vues, fenêtres, menus |258| Éditeur | TextKit 2 (`NSTextView`, `NSTextLayoutFragment`) | — | paquet SwiftPM `SPNotesEditor`, AppKit pur, testable sans interface |259| Core partagé | [`SPNotesCore`](https://git.spboucher.ai/sp-notes-core) (paquet local `../SPNotesCore`) | commit `b06b1ed` | modèle de document, base locale SQLite/FTS5, client d'API, moteur de synchronisation |260| Mathématiques | [SwiftMath](https://github.com/mgriebling/SwiftMath) | 1.7.3 (exacte) | composition LaTeX |261| Stockage | SQLite du système | — | WAL, `synchronous=FULL`, FTS5 |262| Connexion | AuthenticationServices | — | clés d'accès du domaine `note.spboucher.ai` |263| Verrouillage | LocalAuthentication | — | Touch ID ou mot de passe du Mac |264| Raccourci global | `RegisterEventHotKey` (Carbon) | — | sans autorisation d'accessibilité |265| Projet | XcodeGen (`project.yml`) | — | génère `SPNotes.xcodeproj` |266| Cible | macOS | 15.0 minimum | binaire universel (arm64, x86_64) |267268## 🗂 Organisation du dépôt269270105 fichiers suivis, dont 44 fichiers Swift (6 577 lignes).271272```273sp-notes-macos/274├── App/ # 8 fichiers · point d'entrée, environnement, fenêtre principale, menus, synchronisation, verrouillage275├── Editor/ # 12 fichiers · moteur d'édition natif (paquet SwiftPM « SPNotesEditor », AppKit pur)276│ ├── DocumentCodec.swift EditorAttributes.swift Styler.swift SyntaxHighlighter.swift277│ ├── BlockLayoutFragment.swift NoteFragment.swift AtomAttachment.swift MathRenderer.swift278│ └── NoteTextView.swift EditorCommands.swift Completion.swift ExportComposer.swift279├── Components/ # 2 fichiers · pont SwiftUI de l'éditeur, système visuel280├── Features/ # 16 fichiers · Home (bibliothèque), Notes, Attachments, AI, History, Search, Settings, Account281├── Resources/ # Info.plist, entitlements (Release et Debug), Assets.xcassets282├── Tests/283│ ├── EditorTests/ # SwiftPM, Swift Testing — 31 tests284│ ├── AppTests/ # hébergés dans l'app, XCTest — 13 tests285│ └── UITests/ # XCUITest — 2 tests286├── Scripts/ # build, tests, signature, notarisation, profil de provisionnement, icônes, captures287├── docs/ # audit du site, matrice de parité, architecture, sécurité, installation, mises à jour, tests, notes de version288│ ├── img/ # captures réelles de l'application289│ └── brand/ # logo et icône du README290├── Package.swift # manifeste de SPNotesEditor291├── project.yml # définition XcodeGen : app, tests hébergés, tests d'interface292└── SPNotes.xcodeproj293```294295## 🚀 Compiler et lancer296297Prérequis : cloner [`sp-notes-core`](https://git.spboucher.ai/sp-notes-core) **à côté de ce dépôt sous le nom298`SPNotesCore`** (le projet et le paquet référencent `../SPNotesCore`), XcodeGen, et `rsvg-convert` pour régénérer les299icônes (`brew install librsvg`).300301```bash302Scripts/build.sh debug # génère le projet Xcode (XcodeGen) et compile en Debug303SPN_ONLY=Document swift test --scratch-path build/spm # tests du moteur d'édition (sans interface)304Scripts/integration-test.sh # tests hébergés dans l'app (base locale réelle)305Scripts/integration-test.sh --server # + synchronisation contre le backend de DÉVELOPPEMENT (tunnel SSH)306Scripts/run-dev.sh [--local] [--shot f.png] # lance le build Debug en arrière-plan, sans prendre le clavier307Scripts/build.sh ui-test # XCUITest (envoie de vraies frappes : Mac inoccupé)308309python3 Scripts/provision.py # App ID + Associated Domains + profil Developer ID (idempotent)310Scripts/release.sh # archive Release signée → dist/SP Notes.app311Scripts/verify-release.sh # signature, runtime durci, bac à sable, aucune vue web, aucun secret312Scripts/notarize.sh # notarisation Apple, agrafage, DMG signé et notarisé313```314315<details>316<summary><b>Tous les scripts</b></summary>317318| Script | Rôle |319|---|---|320| `Scripts/build.sh generate\|debug\|core-test\|app-test\|ui-test\|run` | point d'entrée de développement |321| `Scripts/integration-test.sh [--server]` | tests hébergés ; avec `--server`, tests de synchronisation de bout en bout contre le backend de développement |322| `Scripts/dev-session.sh` | ouvre un tunnel SSH vers le backend de **développement** et obtient une session pour sa base jetable (`eval "$(Scripts/dev-session.sh)"`) |323| `Scripts/run-dev.sh` | lance le build Debug avec une session de développement, en arrière-plan ; capture optionnelle |324| `Scripts/shot.sh` · `Scripts/window-shot.swift` | capture la fenêtre du build Debug en PNG |325| `Scripts/make-icon.sh` | rend les sources vectorielles de l'icône dans le catalogue d'assets (clair et sombre, toutes les tailles macOS) |326| `Scripts/check-headers.sh` | échoue si un fichier source n'a pas l'en-tête d'auteur |327| `Scripts/provision.py` · `Scripts/asc.py` | identifiant d'application, capacité Associated Domains et profil Developer ID par l'API App Store Connect (idempotent ; aucun certificat créé) |328| `Scripts/release.sh` | archive Release signée avec l'identité Developer ID **existante** |329| `Scripts/verify-release.sh` | contrôle l'application signée (code de sortie ≠ 0 si un contrôle échoue) |330| `Scripts/notarize.sh` | notarise et agrafe l'application, puis construit, signe, notarise et agrafe le DMG |331332</details>333334## ⚙️ Configuration335336Aucun secret dans le dépôt. Les scripts de publication utilisent l'identité Developer ID, la clé d'API App Store Connect337et le profil `notarytool` **déjà présents** sur le Mac ; ils n'en créent, n'en affichent et n'en modifient aucun.338339| Nom | Où | Rôle |340|---|---|---|341| `SPNOTES_SERVER`, `SPNOTES_SESSION_TOKEN` | builds Debug uniquement | serveur et session de développement, exportés par `Scripts/dev-session.sh` ; acceptés seulement pour un serveur en boucle locale |342| `SPNOTES_IT_SERVER`, `SPNOTES_IT_TOKEN` | tests hébergés | serveur de développement des tests de synchronisation |343| `NOTARY_PROFILE` | `Scripts/notarize.sh` | profil du trousseau créé au préalable avec `xcrun notarytool store-credentials` |344| `SPN_ONLY` | `swift test` | hérité de `SPNotesCore` : ne compiler qu'un module du Core |345346| Réglage de `project.yml` | Valeur |347|---|---|348| `MARKETING_VERSION` · `CURRENT_PROJECT_VERSION` | `1.0.2` · `3` |349| `PRODUCT_BUNDLE_IDENTIFIER` | `ai.spboucher.spnotes` (Release) · `ai.spboucher.spnotes.debug` (Debug) |350| `deploymentTarget` | macOS 15.0 |351| `SWIFT_STRICT_CONCURRENCY` | `complete` |352| `ENABLE_HARDENED_RUNTIME` | `YES` |353| Signature Release | manuelle, `Developer ID Application`, profil « SP Notes Developer ID », `--timestamp` |354| Signature Debug | locale (`-`), sans profil : aucun droit restreint (pas d'Associated Domains) |355356Droits de la version publiée ([`Resources/SPNotes.entitlements`](Resources/SPNotes.entitlements)) : bac à sable, réseau357sortant, fichiers choisis par l'utilisateur (lecture / écriture), impression, `webcredentials:note.spboucher.ai`, groupe358de trousseau de l'application.359360## 🖥 Écrans et intégration macOS361362| Écran | Source |363|---|---|364| Écran d'accueil du premier lancement (« Se connecter avec ma clé d'accès » / « Continuer sans compte ») | `Features/Account/WelcomeView.swift` |365| Barre latérale : bibliothèque, espaces, dossiers, archives, corbeille, état de synchronisation | `Features/Home/SidebarView.swift` |366| Liste des notes | `Features/Notes/NoteListView.swift` |367| Note : éditeur, barre d'outils, bandeaux | `Features/Notes/NoteDetailView.swift` |368| Inspecteur | `Features/Notes/InspectorPanel.swift` |369| Éditeurs de blocs atomiques | `Features/Notes/AtomEditors.swift` |370| Assistant | `Features/AI/AssistantPanel.swift` |371| Historique et conflits | `Features/History/HistoryAndConflicts.swift` |372| Palette de commandes et ouverture rapide | `Features/Search/CommandPalette.swift` |373| Compte | `Features/Account/AccountSheet.swift` |374| Réglages (⌘,) : apparence, police et taille du texte, orthographe, note rapide, verrouillage local, stockage | `Features/Settings/SettingsView.swift` |375376<div align="center">377<img src="docs/img/welcome.png" alt="Écran d'accueil du premier lancement" width="820">378</div>379380| Intégration | Détail |381|---|---|382| Schéma d'URL | `spnotes://` |383| Service macOS | « Nouvelle note SP Notes avec la sélection » |384| Note rapide | ⌃⌥⌘N global, icône de barre des menus |385| Catégorie | `public.app-category.productivity` |386| Langue de développement | français |387388## 🗃 Données locales389390`~/Library/Containers/ai.spboucher.spnotes/Data/Library/Application Support/SPNotes/` :391392| Élément | Contenu |393|---|---|394| `notes-note.spboucher.ai.sqlite` | notes, index plein texte, file d'envoi, historique local — un fichier SQLite par serveur, mode WAL, `synchronous=FULL` : une écriture confirmée survit à une coupure de courant |395| `files-note.spboucher.ai/` | pièces jointes (`<id>.<ext>`), référencées par chemin relatif |396| Trousseau | jeton de session |397398`NoteSession` enregistre 350 ms après la dernière frappe, à la perte de focus de l'application, à la fermeture, et avant399de quitter (`applicationShouldTerminate` attend l'écriture et un point de contrôle). Un instantané d'historique local400est pris avant une salve de modifications (au plus toutes les dix minutes) et à chaque ⌘S.401402Pour tout récupérer hors de l'application : Fichier → Exporter toute la bibliothèque (ZIP de fichiers Markdown et des403pièces jointes). Le schéma de la base est celui de [`sp-notes-core`](https://git.spboucher.ai/sp-notes-core).404405## 🔒 Sécurité et confidentialité406407| Sujet | Ce qui est fait |408|---|---|409| Bac à sable | App Sandbox actif. Droits : réseau sortant, fichiers choisis par l'utilisateur (lecture / écriture), impression. Pas de serveur, pas de caméra, pas de micro, pas d'accès large au disque. |410| Runtime durci | Actif, sans aucune exception (pas de JIT, pas de mémoire exécutable non signée, validation des bibliothèques). |411| Signature | Developer ID Application, horodatage sécurisé, profil Developer ID embarqué, notarisation Apple, ticket agrafé. |412| Code web | Aucun : ni WebKit ni JavaScriptCore ne sont liés ; aucune ressource HTML / JS / CSS dans le paquet (`Scripts/verify-release.sh`). |413| Connexion | Clés d'accès du domaine `note.spboucher.ai` par AuthenticationServices (droit `webcredentials:note.spboucher.ai`, fichier `apple-app-site-association` du serveur). L'application ne voit jamais de donnée biométrique ni de clé privée. |414| Session | Jeton opaque du serveur, gardé dans le trousseau de macOS (jamais dans un fichier ni dans les préférences), envoyé explicitement dans l'en-tête `Cookie`. Pas de pot à cookies, pas de cache HTTP, pas de suivi de redirection. |415| Transport | HTTPS vers le serveur de production ; TLS validé par le système, jamais affaibli. Un autre serveur n'est accepté que dans un build de développement, et seulement en boucle locale. |416| Actions sensibles | La suppression définitive et la gestion des appareils demandent au serveur une clé d'accès vérifiée depuis moins de cinq minutes ; l'application déclenche la vérification, elle ne la contourne pas. |417| Données locales | Notes, index et fichiers dans le conteneur de l'application. **Non chiffrés par l'application** : leur protection est celle du compte macOS et de FileVault. |418| Verrouillage local | Optionnel : Touch ID ou mot de passe du Mac à l'ouverture ou après inactivité. C'est un écran de verrouillage, pas un chiffrement, et il est indépendant de la session du serveur. |419| Fin de session | Une session expirée ou révoquée n'efface rien : les notes restent lisibles et modifiables, l'envoi reprend après reconnexion. La déconnexion volontaire propose de garder ou d'effacer la copie locale, et avertit s'il reste des modifications non envoyées. |420| Pièces jointes | 200 Mo au plus ; programmes, scripts, pages web et images disque refusés ; noms nettoyés ; les chemins venus de la base sont réduits à leur dernier composant avant tout accès disque. |421| Liens | Seuls `http`, `https` et `mailto` s'ouvrent ; un lien `javascript:` ou `file:` d'un document est refusé avec un message. |422| Assistant | Rien n'est envoyé sans une action explicite ; seul le texte concerné part (la sélection, ou la note), et le panneau le dit. Aucune clé de fournisseur n'est dans l'application : les modèles sont ceux du serveur. |423| Journaux | Aucun contenu de note, aucun jeton, aucune charge WebAuthn dans les journaux. |424| Raccourci global | `RegisterEventHotKey` (Carbon) : aucune autorisation d'accessibilité ni de surveillance du clavier. |425426**Ce que l'application ne prétend pas** : pas de chiffrement de bout en bout (le serveur lit les notes pour la recherche427et l'assistant) ; les fichiers ouverts avec Coup d'œil sont copiés sous leur vrai nom dans le dossier temporaire du428conteneur ; une copie de note exportée sort du contrôle de l'application. Détail : [`docs/SECURITY.md`](docs/SECURITY.md).429430## 🧪 Tests43143246 tests dans ce dépôt ; ce qui a été exécuté, avec les résultats, et ce qui ne l'a pas été :433[`docs/TEST_REPORT.md`](docs/TEST_REPORT.md).434435| Suite | Cadre | Tests | Vérifie |436|---|---|---|---|437| `CodecTests` | Swift Testing | 4 | aller-retour JSON ⇄ texte sans aucune différence sur tous les types du schéma web ; idem après une frappe annulée |438| `TypingTests` | Swift Testing | 10 | Entrée, raccourcis Markdown, sortie de liste, Tab / ⇧Tab, Retour arrière structuré, bloc de code, ⇧Entrée |439| `CommandTests` | Swift Testing | 8 | marques, liens, titres / listes / citation / code, case à cocher, annuler / rétablir une étape par commande, déplacement de blocs, édition de tableau |440| `RemoteAndPasteboardTests` | Swift Testing | 6 | changement distant sans déplacement du curseur, copier-coller structuré, document de 4 000 blocs |441| `CompletionTests` | Swift Testing | 2 | menu « / » : filtre, insertion, annulation |442| Rendu hors écran | Swift Testing | 1 | tous les types de blocs, clair et sombre (`docs/img/editor-light.png`, `editor-dark.png`) |443| `LocalTests` (hébergés) | XCTest | 7 | enregistrement automatique, arrêt brutal, organisation, historique local, exports, deux fenêtres sur une note, bibliothèque de 5 000 notes |444| `SyncTests` (hébergés, `--server`) | XCTest | 6 | scénario hors ligne de bout en bout, changement d'un autre appareil, fusion et conflit, image jointe hors ligne, corbeille dans les deux sens, assistant en flux |445| `SPNotesUITests` | XCUITest | 2 | écrits et compilés, **non exécutés** (ils envoient de vraies frappes au Mac) |446447Mesures prises dans les tests (rapport du 2026-11-18, MacBook Apple Silicon, macOS 27.0, Xcode 27.2, Swift 6.4) :448449| Mesure | Résultat |450|---|---|451| Document de 4 000 blocs | chargement 95 ms · 3,3 ms par frappe · sérialisation 32 ms |452| Bibliothèque de 5 000 notes | barre latérale + liste 2–3 ms · recherche FTS 4–5 ms |453454Le serveur de test est l'instance de **développement** du backend (base jetable, par tunnel SSH). Aucune donnée de455production ne sert aux tests.456457<details>458<summary><b>Ce qui n'a PAS été vérifié automatiquement</b></summary>459460| Sujet | Comment le valider |461|---|---|462| **Connexion par clé d'accès dans l'app signée** (feuille Touch ID, association de domaine côté macOS) | lancer `/Applications/SP Notes.app` → « Se connecter avec ma clé d'accès » |463| **Redémarrage réel du Mac** au milieu du scénario hors ligne, coupure réseau physique | refaire le scénario à la main avec un vrai redémarrage et le Wi-Fi coupé |464| Tests d'interface XCUITest | `Scripts/build.sh ui-test`, Mac inoccupé |465| Interactions à la souris : clic sur une case, double-clic sur un tableau, glisser-déposer de fichiers | à la main |466| Fenêtres : restauration au lancement, plein écran, plusieurs fenêtres à l'écran | à la main |467| Note rapide, Service macOS, liens `spnotes://`, barre des menus, Coup d'œil, impression, feuille de partage, verrouillage Touch ID | à la main |468| Assistant : actions autres que « Résumer », questions sur la note / sur toutes les notes | à la main |469| Historique du serveur dans l'app ; liste des clés d'accès et des appareils | à la main, connecté |470| Suppression définitive poussée au serveur | supprimer définitivement, puis « Confirmer avec ma clé d'accès » dans Compte |471| VoiceOver | à la main |472| Autre Mac, Mac Intel, macOS 15 / 26 | installer le DMG ailleurs (la tranche x86_64 du binaire universel n'a jamais été exécutée) |473474</details>475476## 📦 Publication477478Chaîne reproductible : `release.sh` → `verify-release.sh` → `notarize.sh`.479480```mermaid481flowchart LR482 P["provision.py<br/>App ID · Associated Domains · profil Developer ID"] --> R["release.sh<br/>archive Release signée → dist/SP Notes.app"]483 R --> V["verify-release.sh<br/>signature · runtime durci · bac à sable · aucune vue web · aucun secret"]484 V --> N["notarize.sh<br/>notarisation · agrafage · DMG signé et notarisé"]485 N --> D["dist/SPNotes-x.y.z.dmg"]486```487488| Version | Date | Contenu |489|---|---|---|490| **1.0.2 (3)** | 2026-11-18 | Écran d'accueil au premier lancement (« Se connecter avec ma clé d'accès » / « Continuer sans compte »), état de synchronisation plus clair, avertissement quand l'application n'est pas lancée depuis le dossier Applications. Core inchangé (`b06b1ed`). |491| 1.0.1 (2) | 2026-11-18 | Même application, reconstruite sur le Core commité (`b06b1ed`) dont le moteur de synchronisation a reçu vingt correctifs, plusieurs touchant à la sûreté des données : **la 1.0.1 remplace la 1.0.0**. |492| 1.0.0 (1) | 2026-11-18 | Première version (DMG de 9,4 Mo). |493494Les trois versions sont signées Developer ID, notarisées par Apple (application et image disque : *Accepted*, ticket495agrafé) et étiquetées `v1.0.0`, `v1.0.1`, `v1.0.2`. Empreintes SHA-256 des DMG, numéros de soumission et correctifs496détaillés : [`docs/RELEASE_NOTES.md`](docs/RELEASE_NOTES.md).497498**Mises à jour** : aucune mise à jour automatique n'est livrée ; une nouvelle version s'installe en remplaçant499l'application par celle d'un nouveau DMG, les données (conteneur, trousseau) sont conservées. La clé500`SPNotesUpdateFeedURL` (vide) est réservée dans `Info.plist`. Conception retenue pour la suite (flux signé, Sparkle 2) :501[`docs/UPDATES.md`](docs/UPDATES.md).502503## 💿 Installation504505Configuration requise : macOS 15 ou plus récent, Mac Apple Silicon ou Intel.5065071. Ouvrir `SPNotes-1.0.2.dmg`.5082. Glisser **SP Notes** dans **Applications**.5093. Lancer SP Notes depuis `/Applications`.510511Vérification manuelle : `spctl -a -vv "/Applications/SP Notes.app"` doit répondre512`accepted · source=Notarized Developer ID`.513514- **Sans compte** : rien à faire. Les notes sont enregistrées sur le Mac.515- **Avec synchronisation** : au premier lancement, « Se connecter avec ma clé d'accès » (ou, plus tard, l'état en bas de516 la barre latérale). macOS propose la clé d'accès de `note.spboucher.ai` (Touch ID, trousseau iCloud, ou un appareil517 proche). Les notes du serveur arrivent, celles créées sans compte sont envoyées.518- **Pas encore de clé d'accès sur ce Mac ?** Une clé synchronisée par le trousseau iCloud fonctionne telle quelle ;519 sinon, une fois connecté, « Ajouter une clé d'accès sur ce Mac ». La toute première clé d'un compte se crée depuis le520 serveur (`pnpm auth:open-enrollment` sur le nœud, voir521 [note-spboucher-ai](https://git.spboucher.ai/note-spboucher-ai)).522- **Désinstaller** : mettre l'application à la corbeille. Pour effacer aussi les données locales : Compte → Se523 déconnecter → « effacer la copie locale », ou supprimer le dossier du conteneur.524525Détail : [`docs/INSTALL.md`](docs/INSTALL.md).526527## 🧯 Dépannage et pièges528529| Symptôme ou piège | Explication |530|---|---|531| macOS refuse la clé d'accès | Lancer l'application depuis `/Applications` : macOS associe l'application au domaine d'après son emplacement enregistré ; une copie lancée depuis le Bureau peut être refusée. La 1.0.2 affiche un avertissement dans ce cas. |532| Une copie de développement masque l'application installée | Le build Debug a un identifiant distinct (`ai.spboucher.spnotes.debug`) précisément pour cela : macOS résout l'association de domaine des clés d'accès par identifiant d'application. |533| Le build Debug ne peut pas se connecter par clé d'accès | Il est signé localement sans profil, donc sans le droit Associated Domains. Utiliser `Scripts/run-dev.sh` (session de développement, sans Touch ID). |534| Les tests d'interface perturbent le Mac | `Scripts/build.sh ui-test` envoie de vraies frappes : Mac inoccupé. |535| Le lot de tests d'interface ne se charge pas | Il est signé ad hoc : le runtime durci est désactivé pour cette cible (la validation des bibliothèques le refuserait). |536| `Scripts/make-icon.sh` échoue | Il lui faut `rsvg-convert` (`brew install librsvg`) et les sources vectorielles de l'icône (`Resources/icon/*.svg`), qui ne sont pas suivies dans ce dépôt. |537| `Scripts/notarize.sh` échoue d'emblée | Le profil `notarytool` du trousseau doit exister (`NOTARY_PROFILE`) ; le script ne crée aucun identifiant. « notarized » n'est affiché que si Apple a répondu *Accepted*. |538| `Scripts/release.sh` échoue d'emblée | Aucune identité Developer ID Application dans le trousseau : le script n'en crée pas. |539| Pièces jointes peu lisibles en fenêtre sombre sur un système clair | Corrigé : les pièces jointes suivent l'apparence de la vue de texte (révélé par le rendu hors écran). |540| Une session expirée | Rien n'est effacé : les notes restent lisibles et modifiables, l'envoi reprend après reconnexion. |541| Le compilateur ne trouve pas `SPNotesCore` | Le dépôt [`sp-notes-core`](https://git.spboucher.ai/sp-notes-core) doit être cloné à côté sous le nom `SPNotesCore`. |542543## 🚧 Limites connues544545Tirées de [`docs/RELEASE_NOTES.md`](docs/RELEASE_NOTES.md), [`docs/FEATURE_MATRIX.md`](docs/FEATURE_MATRIX.md) et546[`docs/TEST_REPORT.md`](docs/TEST_REPORT.md).547548- Pas de poignée de glisser-déposer par bloc (déplacement au clavier : ⌃⌘↑ / ⌃⌘↓).549- Titres limités aux niveaux 1 à 3 (limite du schéma du site).550- Une cellule de tableau modifiée perd sa mise en forme interne ; les autres la gardent.551- Deux modifications simultanées dans une même liste, sur deux appareils, donnent un conflit à trancher (la fusion552 travaille par bloc de premier niveau).553- Bases de données, graphe, espace recherche, agents, tableau de bord, recherche sémantique : sur le site uniquement ;554 les pages concernées sont synchronisées sans être altérées et affichées en lecture seule.555- Tâches et rappels : le Core partagé les synchronise ; pas d'écran natif sur Mac dans cette version.556- Import DOCX / PDF / Notion : reste sur le site.557- Indice / exposant, notes de bas de page, blocs repliables, blocs IA, vidéos : affichés et conservés, pas de commande558 native pour en créer.559- Pas de mise à jour automatique, pas de chiffrement de bout en bout, pas de notifications.560- Le site n'affiche pas encore les favoris ni la marque « dossier » posés par les apps natives (ils sont conservés).561- La feuille Touch ID de l'application signée reste à valider par le propriétaire ; aucun parcours VoiceOver n'a été562 fait ; aucun autre Mac n'a été essayé.563564Écarts du serveur relevés pendant les tests et laissés tels quels : `GET /api/tags` compte mal les pages par tag ; un565identifiant mal formé rend une erreur 500 au lieu de 400 ; la suppression définitive d'une page détache ses pièces566jointes sans les supprimer.567568## 📚 Documentation569570- [`docs/AUDIT.md`](docs/AUDIT.md) — ce qui existe réellement sur le site, et les ajouts au backend.571- [`docs/FEATURE_MATRIX.md`](docs/FEATURE_MATRIX.md) — parité fonction par fonction, avec l'état vérifié / non vérifié.572- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — éditeur, persistance, synchronisation, conflits.573- [`docs/SECURITY.md`](docs/SECURITY.md) · [`docs/INSTALL.md`](docs/INSTALL.md) · [`docs/UPDATES.md`](docs/UPDATES.md)574- [`docs/TEST_REPORT.md`](docs/TEST_REPORT.md) — ce qui a été exécuté, avec les résultats, et ce qui ne l'a pas été.575- [`docs/RELEASE_NOTES.md`](docs/RELEASE_NOTES.md) — notes de version 1.0.0, 1.0.1 et 1.0.2.576577## 👤 Auteur578579<div align="center">580581<img src="docs/brand/icon.png" width="64" height="64" alt="">582583**Simon-Pierre Boucher** — conception, développement, exploitation584585[www.spboucher.ai](https://www.spboucher.ai) · [git.spboucher.ai](https://git.spboucher.ai) · contact@spboucher.ai586587</div>588589## 📄 Licence590591© 2026 Simon-Pierre Boucher. Logiciel privé. Tous droits réservés.592