SPB Git

Repository Public

README.md 37.6 KB 584 lines markdown

1<!--2SP Notes iOS3File: README.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7<div align="center">89<img src="docs/brand/logo.svg" alt="SP Notes logo" width="560">1011<br><br>1213<img src="docs/brand/icon.png" alt="SP Notes icon" width="112" height="112">1415# SP Notes — iOS / iPadOS1617**Native notes app for iPhone and iPad, client of note.spboucher.ai. Offline first: every note lives in a local SQLite database and syncs with the server when the network is there. A custom TextKit 2 editor, Apple Pencil drawings, widgets, Siri and Shortcuts, Spotlight, a share extension — and no web view.**1819**Author: [Simon-Pierre Boucher](https://www.spboucher.ai)**2021[![note.spboucher.ai](https://img.shields.io/website?url=https%3A%2F%2Fnote.spboucher.ai%2Fapi%2Fhealth&label=backend%20note.spboucher.ai&style=for-the-badge&up_message=online&down_message=offline)](https://note.spboucher.ai)22![version](https://img.shields.io/badge/version-1.0.0%20%281%29-F5820B?style=for-the-badge)23![platform](https://img.shields.io/badge/iOS%20%C2%B7%20iPadOS-18%2B-000000?style=for-the-badge&logo=apple&logoColor=white)24![TestFlight](https://img.shields.io/badge/TestFlight-internal%20testing-0D96F6?style=for-the-badge&logo=apple&logoColor=white)25![license](https://img.shields.io/badge/license-all%20rights%20reserved-lightgrey?style=for-the-badge)26![author](https://img.shields.io/badge/author-Simon--Pierre%20Boucher-0A66C2?style=for-the-badge)2728![Swift](https://img.shields.io/badge/Swift-6.0%20%C2%B7%20strict%20concurrency-F05138?style=flat-square&logo=swift&logoColor=white)29![SwiftUI](https://img.shields.io/badge/SwiftUI-screens-0D96F6?style=flat-square&logo=swift&logoColor=white)30![UIKit](https://img.shields.io/badge/UIKit-TextKit%202%20editor-555?style=flat-square&logo=apple&logoColor=white)31![SPNotesCore](https://img.shields.io/badge/SPNotesCore-shared%20local%20package-F5820B?style=flat-square)32![SwiftMath](https://img.shields.io/badge/SwiftMath-1.7.3-informational?style=flat-square)33![SQLite](https://img.shields.io/badge/SQLite-WAL%20%C2%B7%20FTS5-003B57?style=flat-square&logo=sqlite&logoColor=white)34![WidgetKit](https://img.shields.io/badge/WidgetKit-4%20widgets-informational?style=flat-square)35![App Intents](https://img.shields.io/badge/App%20Intents-Siri%20%C2%B7%20Shortcuts-informational?style=flat-square)36![PencilKit](https://img.shields.io/badge/PencilKit-drawings-informational?style=flat-square)37![Vision](https://img.shields.io/badge/Vision-on--device%20text%20recognition-informational?style=flat-square)38![Core Spotlight](https://img.shields.io/badge/Core%20Spotlight-system%20search-informational?style=flat-square)39![Passkeys](https://img.shields.io/badge/passkeys-AuthenticationServices-3423A6?style=flat-square&logo=webauthn&logoColor=white)40![XcodeGen](https://img.shields.io/badge/XcodeGen-project.yml-informational?style=flat-square)41![web views](https://img.shields.io/badge/web%20views-none-brightgreen?style=flat-square)4243[![commits](https://git.spboucher.ai/badge/sp-notes-ios/commits.svg?style=flat-square)](https://git.spboucher.ai/sp-notes-ios/commits)44[![last commit](https://git.spboucher.ai/badge/sp-notes-ios/last-commit.svg?style=flat-square)](https://git.spboucher.ai/sp-notes-ios/commits)45[![activity](https://git.spboucher.ai/badge/sp-notes-ios/activity.svg?style=flat-square)](https://git.spboucher.ai/sp-notes-ios/insights)46[![language](https://git.spboucher.ai/badge/sp-notes-ios/language.svg?style=flat-square)](https://git.spboucher.ai/sp-notes-ios)47[![languages](https://git.spboucher.ai/badge/sp-notes-ios/languages.svg?style=flat-square)](https://git.spboucher.ai/sp-notes-ios/insights)48[![size](https://git.spboucher.ai/badge/sp-notes-ios/size.svg?style=flat-square)](https://git.spboucher.ai/sp-notes-ios)49[![branches](https://git.spboucher.ai/badge/sp-notes-ios/branches.svg?style=flat-square)](https://git.spboucher.ai/sp-notes-ios/branches)50[![tags](https://git.spboucher.ai/badge/sp-notes-ios/tags.svg?style=flat-square)](https://git.spboucher.ai/sp-notes-ios/tags)51[![clones](https://git.spboucher.ai/badge/sp-notes-ios/clones.svg?style=flat-square)](https://git.spboucher.ai/sp-notes-ios)5253![Swift files](https://img.shields.io/badge/Swift%20files-98-blue?style=flat-square)54![Swift lines](https://img.shields.io/badge/Swift%20lines-18%20667-blue?style=flat-square)55![feature folders](https://img.shields.io/badge/feature%20folders-17-blue?style=flat-square)56![targets](https://img.shields.io/badge/targets-app%20%2B%20widgets%20%2B%20share%20extension-blue?style=flat-square)57![unit tests](https://img.shields.io/badge/unit%20tests-128%20in%2027%20suites-brightgreen?style=flat-square)58![UI tests](https://img.shields.io/badge/UI%20tests-12%20%C3%97%20iPhone%20and%20iPad-brightgreen?style=flat-square)59![widgets](https://img.shields.io/badge/widgets-4-informational?style=flat-square)60![app intents](https://img.shields.io/badge/app%20intents-6-informational?style=flat-square)61![languages](https://img.shields.io/badge/languages-fr%20%28source%29%20%C2%B7%20en-informational?style=flat-square)6263![bundle](https://img.shields.io/badge/bundle-ai.spboucher.spnotes.ios-000000?style=flat-square&logo=apple&logoColor=white)64![extensions](https://img.shields.io/badge/extensions-.widgets%20%C2%B7%20.share-000000?style=flat-square)65![signing](https://img.shields.io/badge/signing-Apple%20Distribution%20%C2%B7%20automatic-brightgreen?style=flat-square)66![App Store Connect](https://img.shields.io/badge/App%20Store%20Connect-6836504456-0D96F6?style=flat-square&logo=appstore&logoColor=white)67![build](https://img.shields.io/badge/build%201.0.0%20%281%29-VALID%20%C2%B7%20in%20beta%20testing-brightgreen?style=flat-square)68![deployment target](https://img.shields.io/badge/deployment%20target-iOS%2018.0-informational?style=flat-square)69![devices](https://img.shields.io/badge/devices-iPhone%20%C2%B7%20iPad-informational?style=flat-square)70![Xcode](https://img.shields.io/badge/built%20with-Xcode%2027.2%20%C2%B7%20iOS%20SDK%2027.2-147EFB?style=flat-square&logo=xcode&logoColor=white)7172</div>7374---7576## 2.0.0 « SP Note Next Generation » (branch `next`, not released)7778Version 2.0.0 (2) is an upgrade of 1.0.0 on the shared core 2.0 (`../SPNotesCore`, products `SPNotesCore`, `SPNotesDesign`,79`SPNotesFeatures`). What changed, what ran and what was only compiled: [`docs/IMPLEMENTATION_STATUS.md`](docs/IMPLEMENTATION_STATUS.md);80parity: [`docs/PARITY_MATRIX.md`](docs/PARITY_MATRIX.md). In short: typed store open with a blocking failure screen and the v1 → v281migration; scoped invalidation; Note Visual System 2.0 (ultramarine, serif titles, signature motions); the 3.0 blocks in the TextKit 282editor with slash menu and Markdown shortcuts; PencilKit drawing blocks, smart shapes, handwriting of a region, PDF annotation; tab83structure on iPhone, sections / menus / ⌘K palette / note windows on iPad; tasks, inbox triage, backlinks; Quick Capture and voice84notes; locked and interactive widgets, quick actions, intents, task notifications; the shared feature screens hosted when the server85offers them. The sections below describe 1.0 and are still valid unless the status document says otherwise.8687## Table of contents8889- [Overview](#-overview)90- [Features](#-features)91- [Architecture](#-architecture)92- [Stack](#-stack)93- [Repository layout](#-repository-layout)94- [Getting started](#-getting-started)95- [Configuration](#-configuration)96- [Screens](#-screens)97- [System integration](#-system-integration)98- [Data model and conventions](#-data-model-and-conventions)99- [Security and privacy](#-security-and-privacy)100- [Testing](#-testing)101- [Release and TestFlight](#-release-and-testflight)102- [Troubleshooting and gotchas](#-troubleshooting-and-gotchas)103- [Known limitations](#-known-limitations)104- [Documentation](#-documentation)105- [Author](#-author)106- [License](#-license)107108---109110## 🎯 Overview111112Native notes app for iPhone and iPad (Swift 6, SwiftUI, UIKit/TextKit 2), client of **https://note.spboucher.ai**113(MacLustr). Offline first: every note lives in a local SQLite database and syncs with the server when the network is114there. No web view.115116| | |117|---|---|118| Bundle | `ai.spboucher.spnotes.ios` (+ `.widgets`, `.share`), team `3YM54G49SN`, iOS 18+ |119| Repositories | spbgit `sp-notes-ios.git` (this project) and `sp-notes-core.git` (the shared core, to clone next to it as `SPNotesCore`) |120| Shared core | `../SPNotesCore` (Swift package, also used by SP Notes macOS): `SPNotesDocument`, `SPNotesStore`, `SPNotesAPI`, `SPNotesSync` |121| Dependencies | SwiftMath 1.7.3 (LaTeX typesetting in Core Text) — nothing else |122| Project | generated by XcodeGen from `project.yml` |123124### Family125126| Repository | Role | Platform |127|---|---|---|128| [note-spboucher-ai](https://git.spboucher.ai/note-spboucher-ai) | Web app, API, database, sync feed | Web / PWA — note.spboucher.ai |129| [sp-notes-core](https://git.spboucher.ai/sp-notes-core) | Shared Swift package: document model, local store, API client, sync engine | Swift |130| [sp-notes-macos](https://git.spboucher.ai/sp-notes-macos) | SP Notes for Mac | macOS |131| **[sp-notes-ios](https://git.spboucher.ai/sp-notes-ios)** (this one) | SP Notes for iPhone and iPad | iOS / iPadOS 18+ |132133## ✨ Features134135Feature by feature against the web and macOS apps: [`docs/PARITY_MATRIX.md`](docs/PARITY_MATRIX.md).136137| Area | What the app does |138|---|---|139| **Editor** | Native TextKit 2 editor on the ProseMirror document, without loss: headings 1–3, bold, italic, underline, strike, code, highlight, sub/superscript, links; bullet, numbered and task lists (nested); quotes, callouts, code blocks, rules; tables (shown natively, edited in a native sheet); images, files, PDF; LaTeX equations typeset natively (SwiftMath) with a live-preview editor; mentions between notes with stable ids |140| **Capture** | Photos, camera, document scanner, Files; Apple Pencil drawings (PencilKit, editable source kept as a companion attachment); on-device text recognition (Vision) |141| **Organisation** | Folders (pages with sub-pages), sections, tags, pinned and favourites, archive, trash, restore; capture inbox (file, archive or delete) |142| **Search** | Local SQLite FTS5, offline, with filters (section, folder, tags, dates, favourites, pinned, archives) |143| **Offline and sync** | Saved in the local database about 0.6 s after the last keystroke and when the app leaves the foreground; change feed, persistent queue, resumable; automatic merge by blocks when safe, otherwise both copies kept and a choice |144| **History** | Local snapshots and server history; restore |145| **AI** | 15 actions on a selection plus a free instruction, preview before applying; grounded questions about the notes with sources (online only) |146| **Reminders** | Local notifications; synced to the server as tasks |147| **Export** | Markdown, text, HTML, PDF, RTF, ZIP |148| **Account** | Passkey sign-in through the system sheet (Face ID / Touch ID); passkey and session management (list, add, rename, delete passkeys; revoke sessions); optional local app lock |149| **System** | 4 widgets (Home and Lock Screen), Siri and Shortcuts, Spotlight, share extension, `spnotes://` links, multiple windows, keyboard shortcuts and drag and drop on iPad, background refresh |150151<details>152<summary><b>Functional parity — Web · macOS · iOS / iPadOS (from <code>docs/PARITY_MATRIX.md</code>, 2026-11-18)</b></summary>153154✅ available · ◐ partial · — not available · n/a not applicable.155156| Feature | Web | macOS | iOS / iPadOS | Note for iOS |157|---|---|---|---|---|158| Notes: create, edit, autosave | ✅ | ✅ | ✅ | Saved locally ~0.6 s after the last keystroke |159| Works fully offline | ◐ one draft per open page | ✅ | ✅ | Local SQLite database; validated by the scenario test |160| Native rich-text editor | Tiptap (web) | TextKit 2 | ✅ TextKit 2 | No web view |161| Tables | ✅ in place | ✅ | ◐ | Edited in a native table sheet |162| Equations (LaTeX) | ✅ KaTeX | ✅ | ✅ | Typeset natively (SwiftMath) |163| Toggles, footnotes, YouTube, AI blocks | ✅ | ◐ | ◐ | Kept untouched and shown; cannot be created here |164| Markdown shortcuts while typing | ✅ | — | — | Markdown is supported for import, export and assistant results |165| Drawings (Apple Pencil) | — | shows the image | ✅ | PencilKit |166| Handwriting / document text recognition | — | — | ✅ | Vision, on device |167| Pinned · favourites | pinned only | ✅ | ✅ | Favourite = `properties.favorite` |168| Capture inbox | ✅ | — | ◐ | Other triage actions on the web |169| Search | hybrid, online | local | ✅ local FTS5 | No semantic search |170| Questions about the notes (grounded, with sources) | ✅ | — | ✅ | Online only |171| AI agents, model comparison, routing dashboard, budgets | ✅ | — | — | Web only |172| Databases (tables, boards, calendars) | ✅ | — | — | Listed read-only with "open on the web" |173| Research workspace | ✅ | — | — | Research pages are editable as notes |174| Knowledge graph, backlinks explorer | ✅ | — | — | |175| Tasks page | ✅ | — | ◐ | Reminders on a note create tasks; no global task list |176| Reminders with notifications | — | — | ✅ | Device → server only |177| Import (Markdown, ZIP, Notion, DOCX, PDF) | ✅ | ◐ | ◐ | Share extension and file attachments; no bulk importer |178| App lock (biometrics) | n/a | — | ✅ | Local only |179| Passkey and session management | ✅ | ◐ | ✅ | |180| First passkey enrollment / recovery | CLI on the node + web | — | — | By design of the server |181| Widgets, Siri / Shortcuts, Spotlight, share sheet | n/a | — | ✅ | |182183</details>184185## 🏗 Architecture186187```mermaid188flowchart TB189    subgraph EXT["Extensions"]190        W["SPNotesWidgets<br/>WidgetKit · read-only store"]191        SH["SPNotesShare<br/>writes one SharedItem"]192    end193    subgraph APP["SPNotes.app"]194        F["Features/<br/>17 SwiftUI feature folders"]195        M["AppModel<br/>the only writer"]196        ED["Editor/<br/>TextKit 2 engine"]197        I["App Intents · Spotlight · BackgroundSync"]198        F --> M199        ED --> M200        I --> M201    end202    subgraph CORE["SPNotesCore (../SPNotesCore, shared with macOS)"]203        D["SPNotesDocument"]204        ST["SPNotesStore"]205        A["SPNotesAPI"]206        SY["SPNotesSync"]207    end208    G[("App Group container<br/>SQLite · attachments · share hand-off")]209    M --> ST210    M --> SY211    ED --> D212    SY --> ST213    SY --> A214    ST --> G215    W --> G216    SH --> G217    A -- HTTPS --> SRV["https://note.spboucher.ai"]218    A --> KC["Keychain<br/>session token"]219```220221- **Document**: the server stores notes as ProseMirror JSON. `SPNotesDocument` reads it into flat lines with their222  container paths and writes it back without loss (unknown nodes included). The editor's text storage carries that223  model in attributes (`Editor/EditorAttributes.swift`); it is converted back at each save. Only edited paragraphs are224  restyled while typing.225- **Local first**: `AppModel` writes every change to `SPNotesStore` (SQLite, WAL, `synchronous=FULL`, FTS5 search) and226  schedules a sync. No screen waits for the network to save.227- **Sync** (`SPNotesSync`): pushes creations, edits (with the server version they were based on), tags, files and228  queued actions; reads the server change feed; merges concurrent edits block by block; records a conflict — both229  copies kept — when a merge is unsafe. See230  [`SYNC_ENGINE.md` in sp-notes-core](https://git.spboucher.ai/sp-notes-core).231- **Sign-in**: passkeys through the system sheet (Face ID / Touch ID); the session token is kept in the Keychain;232  optional local app lock.233- **Extensions**: the widget extension reads the shared database; the share extension only writes one `SharedItem`234  into the App Group container — it never opens the database nor the network, and the app turns the item into a note235  at its next activation.236237### The mandatory offline scenario238239```mermaid240sequenceDiagram241    autonumber242    participant U as User243    participant A as AppModel244    participant S as Local store245    participant E as SyncEngine246    participant B as Backend247    A->>E: sync248    E->>B: push / pull — two notes in step249    Note over A,B: network lost250    U->>A: edit two notes, tag, pin, create a note, attach a local picture251    A->>S: every change written at once252    Note over A,S: app closed, reopened without network253    A->>S: everything present · offline search finds it254    Note over A,B: network back255    A->>E: sync256    E->>B: creations, uploads, edits with baseVersion, queued actions257    B-->>E: change feed258    Note over B: server holds everything · picture byte-identical · a second device receives it all259```260261This is `Tests/OfflineScenarioTests.swift`, run through the app model against the development server.262263## 🧱 Stack264265| Layer | Technology | Version | Role |266|---|---|---|---|267| Language | Swift, complete strict concurrency | 6.0 (`SWIFT_VERSION`) | — |268| Interface | SwiftUI, UIKit where needed | — | every screen; no web view of any kind |269| Editor | `UITextView` on TextKit 2 | — | custom layout fragments, codec document ⇄ text storage |270| Shared core | [`SPNotesCore`](https://git.spboucher.ai/sp-notes-core) (local package `../SPNotesCore`) | commit `b06b1ed` | document model, local store, API client, sync engine |271| Math | [SwiftMath](https://github.com/mgriebling/SwiftMath) | 1.7.3 (exact) | LaTeX typesetting in Core Text |272| Storage | system SQLite | — | WAL, `synchronous=FULL`, FTS5 |273| Widgets | WidgetKit, App Intents | — | 4 widgets, configurable note widget |274| Siri and Shortcuts | App Intents | — | 6 intents, `AppShortcutsProvider` |275| System search | Core Spotlight | — | incremental index from the store's change stream |276| Drawing | PencilKit | — | Apple Pencil |277| Recognition | Vision | — | on-device text recognition |278| Sign-in | AuthenticationServices | — | passkeys of `note.spboucher.ai` |279| App lock | LocalAuthentication | — | Face ID / Touch ID, device passcode as the system fallback |280| Background | BackgroundTasks | — | app refresh and processing tasks |281| Project | XcodeGen (`project.yml`) | — | generates `SPNotes.xcodeproj` |282| Deployment target | iOS / iPadOS | 18.0 | iPhone and iPad (`TARGETED_DEVICE_FAMILY` 1,2); no Mac Catalyst, no "Designed for iPad" on Mac or visionOS |283284## 🗂 Repository layout285286161 tracked files, including 98 Swift files (18 667 lines).287288```289sp-notes-ios/290├── App/            # 12 files · entry point, application model (AppModel), configuration, intents, background sync, sample data291│   └── Intents/    # App Intents, shortcuts, quick-note actions, Spotlight indexer, routing292├── Core/           # 4 files · attachment files, app lock (Face ID / Touch ID), network monitor, reminders293├── Editor/         # 9 files · the native editor engine (TextKit 2): codec document ⇄ text storage, styler, layout fragment, toolbar294├── Features/       # 48 files · screens295│   ├── Root/  Home/  Notes/  Folders/  Tags/  Search/  Organize/296│   ├── Editor/  AI/  History/  Conflicts/  Reminders/297│   └── Attachments/  Drawing/  Export/  Settings/  Account/298├── Components/     # 4 files · shared views and theme299├── Shared/         # 3 files · code shared with the extensions (App Group, deep links, share hand-off)300├── WidgetShared/   # 3 files · widget views and data provider (app + widget extension)301├── Widgets/        # WidgetKit extension302├── ShareExtension/ # share extension303├── Design/         # vector sources of the icon (default, dark, tinted) and of the mark304├── Resources/      # Info.plist, entitlements, privacy manifest, asset catalog, string catalogs305├── Tests/          # 7 files · 128 unit tests306├── UITests/        # 3 files · 12 UI tests307├── Scripts/        # build, test, release, App Store Connect client308├── docs/           # audit, parity, status, distribution, UI conventions (+ brand/)309├── project.yml     # XcodeGen definition: app, widget extension, share extension, unit and UI tests310└── SPNotes.xcodeproj311```312313## 🚀 Getting started314315Prerequisites: clone [`sp-notes-core`](https://git.spboucher.ai/sp-notes-core) **next to this repository as316`SPNotesCore`**, and install XcodeGen.317318```sh319Scripts/build.sh generate          # regenerate the Xcode project (after adding files)320Scripts/build.sh debug | test | uitest          # SPNOTES_SIM="iPad Pro 13-inch (M5)" for the iPad321Scripts/build.sh core              # the shared core's tests on the host322Scripts/test-live.sh               # offline scenario against the development server323Scripts/release.sh all             # signed archive + IPA;  Scripts/release.sh upload → TestFlight324```325326| Script | Usage |327|---|---|328| `Scripts/build.sh` | `generate \| debug \| release \| test [xcodebuild args] \| uitest [xcodebuild args] \| core` — filtered xcodebuild output, full log in `build/logs` |329| `Scripts/test-live.sh` | opens the SSH tunnel, creates a development session and runs the live suites on the simulator against the **development** server (never production) |330| `Scripts/release.sh` | `archive \| export \| upload \| all` — Release archive, IPA export, optional TestFlight upload |331| `Scripts/asc.py` | minimal App Store Connect API client: `asc.py GET /v1/apps?filter[bundleId]=…` |332333`Scripts/build.sh generate` also writes `Resources/Info-Debug.plist` (the release `Info.plist` plus local networking,334for the development server reached through a tunnel); that file is not tracked.335336## ⚙️ Configuration337338No secret lives in the repository or in the binary: the session token is in the Keychain, and the release scripts339reuse the signing identities and the App Store Connect API key already on the Mac.340341| Variable | Scope | Purpose |342|---|---|---|343| `SPNOTES_SIM` | `Scripts/build.sh` | simulator name (default `iPhone 17 Pro`) |344| `SPNOTES_STORE` | Debug launch | `memory`: throw-away database |345| `SPNOTES_SESSION` | Debug launch | `local`: use the app without a server |346| `SPNOTES_SEED` | Debug launch | `1`: sample notes from `App/SampleData.swift` |347| `SPNOTES_BASE_URL`, `SPNOTES_TOKEN` | Debug launch | development server through an SSH tunnel; never production |348| `SPNOTES_DATA_DIR` | Debug launch | data directory override |349| `SPNOTES_LIVE_URL`, `SPNOTES_LIVE_TOKEN` | live tests | set by `Scripts/test-live.sh` |350351| Setting | Value |352|---|---|353| `MARKETING_VERSION` · `CURRENT_PROJECT_VERSION` | `1.0.0` · `1` |354| Bundle identifiers | `ai.spboucher.spnotes.ios`, `…ios.widgets`, `…ios.share` |355| App Group | `group.ai.spboucher.spnotes.ios` (shared database, attachments, share hand-off) |356| Associated domain | `webcredentials:note.spboucher.ai` |357| Base URL (`SPNotesBaseURL`) | `https://note.spboucher.ai` |358| App Transport Security | arbitrary loads and local networking both disabled in the release `Info.plist` |359| Background modes | `fetch`, `processing` (task identifiers `…ios.refresh`, `…ios.sync`) |360| Localizations | `fr` (development language), `en` |361| Usage descriptions | camera (scan a document or attach a photo), Face ID (unlock the notes on this device) |362363## 📱 Screens364365| Feature folder | Screens |366|---|---|367| `Root` | root view, main interface (iPhone and iPad layouts), sidebar, lock screen |368| `Account` | welcome and passkey sign-in, sign-in failures |369| `Home` | home screen, new-note button |370| `Notes` | note lists, note actions, note link picker |371| `Folders` · `Tags` | folder tree and folders screen · tags screen |372| `Organize` | move-note sheet, tag editor |373| `Search` | search screen with criteria |374| `Editor` | note editor screen, native document view, keyboard avoider, drop handler; link, math and table sheets |375| `AI` | assistant sheet and chat |376| `History` · `Conflicts` | note history · conflict sheet |377| `Reminders` | reminders of a note |378| `Attachments` | attachment list and preview, media pickers, document scanner |379| `Drawing` | PencilKit drawing screen |380| `Export` | exporter, share sheet, ZIP writer |381| `Settings` | settings and security screens (passkeys, sessions, app lock) |382383Conventions for everyone writing screens — French interface text (informal "tu"), colours by asset name, Dynamic Type,384hit targets ≥ 44 pt, VoiceOver labels, light and dark, iPhone and iPad: [`docs/UI_CONVENTIONS.md`](docs/UI_CONVENTIONS.md).385386## 🧩 System integration387388| Integration | Detail |389|---|---|390| **Widgets** | *Recent notes* (small, medium, large, Lock Screen rectangular) · *Pinned notes* (medium, large) · *New note* (small, medium, Lock Screen circular) · *Single note* (small, medium, large; note chosen in the widget configuration) |391| **App Intents** | « Créer une note », « Ajouter à une note », « Chercher des notes », « Ouvrir la recherche », « Ouvrir une note », « Nouvelle note »; `SPNotesShortcuts` exposes four of them as app shortcuts (create, append, search, open a note) |392| **Spotlight** | Title and an excerpt of each local note, updated incrementally from the store's change stream; notes that go to the trash, are archived or disappear are removed; erasing the device's data empties the index |393| **Share extension** | Receives content from other apps and hands it to the app through the App Group |394| **Deep links** | `spnotes://note/<id>`, `spnotes://new[?kind=tasks][&text=…]`, `spnotes://search?q=…` — parsing is strict: an unknown or malformed link is refused rather than guessed |395| **Background** | App refresh and processing tasks (`BackgroundSync`) |396| **Notifications** | Local reminder notifications |397| **iPad** | Multiple scenes, indirect input, all four orientations, Split View and Stage Manager widths |398| **Exported type** | `ai.spboucher.spnotes.note-reference` (« Référence de note SP Notes ») |399400## 🗃 Data model and conventions401402The local database, the dirty flags, the queue and the search index are those of403[`sp-notes-core`](https://git.spboucher.ai/sp-notes-core) (`SPNotesStore`). App-level conventions, shared with the404macOS app:405406| Concept | Representation |407|---|---|408| Note | a page |409| Folder | a page flagged `properties.folder = true` (a plain page with sub-pages on the web) |410| Favourite | `properties.favorite = true` (ignored by the web interface); favourite ≠ pinned |411| Sections | `notes`, `documents`, `projects`, `research` (+ `databases`, read-only here) |412| Reminder | a task `{ pageId, dueAt }` |413| PencilKit drawing | an image (visible everywhere) + a companion `.pkdrawing` attachment (editable source) |414| Smart lists | all · recent · pinned · favorites · inbox · archived · trash |415416Reads go through the store (an actor); **writes go only through `AppModel`**, which schedules the synchronisation and417updates the widgets.418419## 🔒 Security and privacy420421- **No web view** (no `WKWebView`, no `SFSafariViewController`): external links open in the system browser.422- **Passkeys only**, through the system sheet and the associated domain `webcredentials:note.spboucher.ai`; nothing423  biometric ever leaves the device.424- The session token is kept in the Keychain; no secret in the repository or in the binary.425- **App lock** is purely local (Face ID / Touch ID, device passcode as the system fallback); the server session is not426  involved.427- Permanent deletion is confirmed with the passkey (server rule).428- App Transport Security: no arbitrary loads; local networking is only allowed in the Debug `Info-Debug.plist`.429- The share extension never opens the database nor the network.430- **Privacy manifest** ([`Resources/PrivacyInfo.xcprivacy`](Resources/PrivacyInfo.xcprivacy)): no tracking, no tracking431  domains; collected data = user content and photos, linked to the account, for app functionality only; required-reason432  APIs = UserDefaults and file timestamps.433- No end-to-end encryption: notes are stored on the device (file protection until first unlock) and on the owner's434  server over HTTPS.435436## 🧪 Testing437438| Suite | Tests | What it covers |439|---|---|---|440| `Tests/NoteFeatureTests.swift` | 33 | assistant actions and questions (fake provider), history, reminders, export menu, note screen |441| `Tests/MediaExportTests.swift` | 27 | note exporter, ZIP writer, table editor model, link and math models, media |442| `Tests/ShellTests.swift` | 24 | list ordering, folder tree and moves, tag editing, search criteria, shell |443| `Tests/SystemIntegrationTests.swift` | 23 | deep links, share hand-off import, quick-note actions, sample data, widget data and snapshots, Spotlight indexer, bundle integration |444| `Tests/EditorTests.swift` | 19 | typing, Enter, Backspace, lists, checkboxes, code, atoms, marks, links, undo/redo |445| `Tests/EditorRenderingTests.swift` | 1 | rendering of every block, light and dark |446| `Tests/OfflineScenarioTests.swift` | 1 | the mandatory offline scenario, against the development server |447| **Unit tests** | **128** | Swift Testing, 27 suites |448| `UITests/ShellUITests.swift` | 5 | phone flow, phone dark and landscape, welcome screen, iPad split view, iPad dark |449| `UITests/SystemUITests.swift` | 4 | `spnotes://` links: new note, open a seeded note, task-list link, malformed and unknown links ignored |450| `UITests/EditorUITests.swift` | 3 | write, format and reopen; assistant sheet; dark appearance |451| **UI tests** | **12** | XCUITest, run on iPhone 17 Pro and iPad Pro 13-inch (M5) |452453Status of 1.0.0 (1), 2026-11-18 ([`docs/IMPLEMENTATION_STATUS.md`](docs/IMPLEMENTATION_STATUS.md)):454455| What | Evidence |456|---|---|457| Shared core `SPNotesCore` (commit `b06b1ed`) | 283 tests on the host: Document 81, Store 49, API 88, Sync 65 |458| Document fidelity | 204/204 documents validated `identical` by the web editor's real ProseMirror schema; plain text, word count and Markdown byte-identical to the server's on 605 documents |459| Native editor engine | 19 tests; 3 000 paragraphs load in ~0.1 s |460| UI tests | 12 on iPhone 17 Pro and 12 on iPad Pro 13-inch (M5), 0 failures (device-specific tests skipped on the other device) |461| Mandatory offline scenario | passed |462| Signing and packaging | Release archive, IPA signed Apple Distribution with associated domain and App Group, both extensions embedded; uploaded to App Store Connect |463464<details>465<summary><b>Not verifiable in the simulator — to check on a real iPhone / iPad</b></summary>4664671. **Passkey sign-in** with Face ID / Touch ID (system sheet, associated domain; first time on this device), step-up468   for permanent deletion, adding an iPhone passkey from Settings → Sécurité.4692. The complete offline scenario with **airplane mode and a device restart**.4703. Software keyboard with the formatting bar on a real phone; hardware keyboard shortcuts on iPad; rotation while471   editing.4724. Camera, document scanner, Apple Pencil drawing (tool picker, zoom), drag and drop from other apps.4735. Widgets on the Home and Lock Screens, Siri phrases, Shortcuts actions, Spotlight results, the share sheet from474   Safari / Photos / Files.4756. Background refresh and processing tasks, reminder notifications (banner, tap opens the note).4767. App lock with Face ID after the grace period; privacy cover in the app switcher.4778. VoiceOver through sign-in, lists and the editor toolbar; largest Dynamic Type sizes.4789. Instruments (time profiler, allocations, energy) on a device: no profiling session was run.47910. Assistant streaming and server history against production (covered by a fake provider and by the API module's480    live tests of the error paths; no real generation was triggered to avoid cost).481482</details>483484## 🚢 Release and TestFlight485486```mermaid487flowchart LR488    V["project.yml<br/>bump CURRENT_PROJECT_VERSION"] --> T["Scripts/build.sh test · uitest"]489    T --> A["release.sh archive<br/>signed with the Xcode account"]490    A --> E["release.sh export<br/>IPA · API key"]491    E --> U["release.sh upload<br/>App Store Connect"]492    U --> TF["TestFlight<br/>internal group « Test »"]493```494495| Item | Value |496|---|---|497| App Store Connect record | **SP Notes**, app `6836504456`, SKU `spnotes-ios-001`, primary language fr-CA |498| App identifiers | `ai.spboucher.spnotes.ios` (Associated Domains, App Groups), `…ios.widgets` (App Groups), `…ios.share` (App Groups) |499| Signing | automatic; Apple Distribution managed by Xcode |500| Build 1.0.0 (1) | IPA 13 MB, signature verified (`codesign --verify --deep --strict`), upload accepted, processed `VALID`, internal state `IN_BETA_TESTING` (2026-11-18) |501| TestFlight | internal group « Test » (access to all builds), the account holder invited |502| Notarisation | does not apply to an App Store / TestFlight distribution of an iOS app |503| Toolchain at release | Xcode 27.2 (27B52), iOS SDK 27.2, simulators iOS 26.5 |504505For a new version: increment `CURRENT_PROJECT_VERSION` (and `MARKETING_VERSION` when needed) in `project.yml`, run the506tests, then `Scripts/release.sh all && Scripts/release.sh upload`.507508**Before an App Store submission** (not done; TestFlight internal testing needs none of this): screenshots (the UI509tests produce them in `build/shots*`), description, keywords, support and privacy-policy URLs, the privacy510questionnaire (consistent with `PrivacyInfo.xcprivacy`), age rating, and a demonstration account for review (the511service has a single owner: without a test account Apple's review cannot sign in).512513Details: [`docs/DISTRIBUTION.md`](docs/DISTRIBUTION.md).514515## 🧯 Troubleshooting and gotchas516517| Trap | Explanation |518|---|---|519| "Authentication failed" while provisioning | App Groups cannot be provisioned with an App Store Connect API key. The **archive** is signed with the Apple ID account configured in Xcode (`-allowProvisioningUpdates` alone); the API key is used for the export and the upload. `Scripts/release.sh` does this. |520| Creating the App Store Connect record | The public API cannot create an app record: it was created through the owner's signed-in Safari session. |521| A file was added and Xcode does not see it | The project is generated: `Scripts/build.sh generate`. |522| The compiler does not find `SPNotesCore` | [`sp-notes-core`](https://git.spboucher.ai/sp-notes-core) must be cloned next to this repository as `SPNotesCore`. |523| Editor paragraphs | Every paragraph of the text storage ends with a `\n` that carries its identity (`.spnLine`), the last one included; the caret never goes past that terminator. Internal line breaks (code, hard break) are U+2028. Two neighbouring paragraphs sharing the same `LineBox` instance = a paragraph created by a line break (the engine gives it a new id / a new list item). |524| `NSTextStorageDelegate` and Swift 6 | It is not annotated `MainActor`: `nonisolated(unsafe)` + `MainActor.assumeIsolated`. |525| Ambiguous `SearchHit` / `Tombstone` | `SPNotesStore` and `SPNotesAPI` both define them: qualify (`SPNotesStore.SearchHit`). |526| "Application failed preflight checks" | Several test runs on the same simulator get in each other's way: one dedicated simulator per UI suite, and a private derived-data path per builder. |527| `XCUIApplication.open(url)` | It relaunches the app; with an in-memory database the link arrives before the sample data. |528| Server behaviour | Purging a page deletes one row only (one `purge` op per page of a folder); `PATCH` answers 404 on a trashed page; an idempotent replay does not return `x-existing`. |529| Shared core | `SPNotesCore` is shared with SP Notes macOS: a change to the Store or Sync modules must be signalled to that project (it rebuilds); do not break the public API without coordination. |530| Backend | `note-spboucher-ai` is modified on its own node; the native additions (`/api/sync`, client ids, apple-app-site-association) are in production since 2026-11-18. |531| Development server | Reached through `ssh -N -L 8482:localhost:8482 M4M64c`; never production. |532533## 🚧 Known limitations534535From [`docs/IMPLEMENTATION_STATUS.md`](docs/IMPLEMENTATION_STATUS.md).536537- Tables are edited in a sheet (cell text), not in place; code blocks have no syntax colouring in the editor.538- Details/toggles, footnotes, YouTube embeds and AI blocks made on the web are kept and shown but cannot be created539  here.540- The merge of concurrent edits works per top-level block: two devices editing the same list at the same time produce541  a conflict (both copies kept, the user chooses).542- Reminders sync to the server as tasks; a task changed on the web does not come back to the device (the server has no543  change feed for tasks).544- An untitled note is stored as "Untitled" (the server's convention): searching « Sans titre » does not find it.545- No end-to-end encryption.546- English translations exist for the system-integration strings; the other screens are French only.547- Attachment uploads need about one extra file size of free space and are not resumable; no ZIP64 (archives over548  4 GiB).549- RTF export: pictures and block equations are embedded in a form Apple's own RTF reader ignores.550- Web-only features (databases, research references, graph, agents, AI administration, bulk import) are listed in551  `PARITY_MATRIX.md`.552- Build 1.0.0 (1) has not been validated on a physical device (see the list above).553554Backend defects observed (pre-existing, not blocking): `GET /api/tags` counts 0 pages; purging a page leaves its555attachments alive; malformed ids answer 500; no cycle check on `parentId`; `/api/files/<id>` still serves a556soft-deleted file.557558## 📚 Documentation559560| Document | Content |561|---|---|562| [`docs/AUDIT.md`](docs/AUDIT.md) | audit of the existing backend, what had to be added to it, decisions that follow |563| [`docs/PARITY_MATRIX.md`](docs/PARITY_MATRIX.md) | functional parity Web · macOS · iOS / iPadOS |564| [`docs/IMPLEMENTATION_STATUS.md`](docs/IMPLEMENTATION_STATUS.md) | what was verified by tests that ran, what must be checked on a device, known limits |565| [`docs/DISTRIBUTION.md`](docs/DISTRIBUTION.md) | signing, App Store Connect, TestFlight |566| [`docs/UI_CONVENTIONS.md`](docs/UI_CONVENTIONS.md) | conventions for everyone writing screens |567| [`CLAUDE.md`](CLAUDE.md) | project rules, recipes and traps (French) |568569## 👤 Author570571<div align="center">572573<img src="docs/brand/icon.png" width="64" height="64" alt="">574575**Simon-Pierre Boucher** — design, development, operations576577[www.spboucher.ai](https://www.spboucher.ai) · [git.spboucher.ai](https://git.spboucher.ai) · contact@spboucher.ai578579</div>580581## 📄 License582583All rights reserved © 2026 Simon-Pierre Boucher.584
Files main
Menu

Theme