SP Notes — iOS / iPadOS
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.
Author: Simon-Pierre Boucher
2.0.0 « SP Note Next Generation » (branch next, not released)
Version 2.0.0 (2) is an upgrade of 1.0.0 on the shared core 2.0 (../SPNotesCore, products SPNotesCore, SPNotesDesign,
SPNotesFeatures). What changed, what ran and what was only compiled: docs/IMPLEMENTATION_STATUS.md;
parity: docs/PARITY_MATRIX.md. In short: typed store open with a blocking failure screen and the v1 → v2
migration; scoped invalidation; Note Visual System 2.0 (ultramarine, serif titles, signature motions); the 3.0 blocks in the TextKit 2
editor with slash menu and Markdown shortcuts; PencilKit drawing blocks, smart shapes, handwriting of a region, PDF annotation; tab
structure on iPhone, sections / menus / ⌘K palette / note windows on iPad; tasks, inbox triage, backlinks; Quick Capture and voice
notes; locked and interactive widgets, quick actions, intents, task notifications; the shared feature screens hosted when the server
offers them. The sections below describe 1.0 and are still valid unless the status document says otherwise.
Table of contents
- Overview
- Features
- Architecture
- Stack
- Repository layout
- Getting started
- Configuration
- Screens
- System integration
- Data model and conventions
- Security and privacy
- Testing
- Release and TestFlight
- Troubleshooting and gotchas
- Known limitations
- Documentation
- Author
- License
🎯 Overview
Native notes app for iPhone and iPad (Swift 6, SwiftUI, UIKit/TextKit 2), client of https://note.spboucher.ai (MacLustr). Offline first: every note lives in a local SQLite database and syncs with the server when the network is there. No web view.
| Bundle | ai.spboucher.spnotes.ios (+ .widgets, .share), team 3YM54G49SN, iOS 18+ |
| Repositories | spbgit sp-notes-ios.git (this project) and sp-notes-core.git (the shared core, to clone next to it as SPNotesCore) |
| Shared core | ../SPNotesCore (Swift package, also used by SP Notes macOS): SPNotesDocument, SPNotesStore, SPNotesAPI, SPNotesSync |
| Dependencies | SwiftMath 1.7.3 (LaTeX typesetting in Core Text) — nothing else |
| Project | generated by XcodeGen from project.yml |
Family
| Repository | Role | Platform |
|---|---|---|
| note-spboucher-ai | Web app, API, database, sync feed | Web / PWA — note.spboucher.ai |
| sp-notes-core | Shared Swift package: document model, local store, API client, sync engine | Swift |
| sp-notes-macos | SP Notes for Mac | macOS |
| sp-notes-ios (this one) | SP Notes for iPhone and iPad | iOS / iPadOS 18+ |
✨ Features
Feature by feature against the web and macOS apps: docs/PARITY_MATRIX.md.
| Area | What the app does |
|---|---|
| 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 |
| Capture | Photos, camera, document scanner, Files; Apple Pencil drawings (PencilKit, editable source kept as a companion attachment); on-device text recognition (Vision) |
| Organisation | Folders (pages with sub-pages), sections, tags, pinned and favourites, archive, trash, restore; capture inbox (file, archive or delete) |
| Search | Local SQLite FTS5, offline, with filters (section, folder, tags, dates, favourites, pinned, archives) |
| 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 |
| History | Local snapshots and server history; restore |
| AI | 15 actions on a selection plus a free instruction, preview before applying; grounded questions about the notes with sources (online only) |
| Reminders | Local notifications; synced to the server as tasks |
| Export | Markdown, text, HTML, PDF, RTF, ZIP |
| 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 |
| 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 |
Functional parity — Web · macOS · iOS / iPadOS (from docs/PARITY_MATRIX.md, 2026-11-18)
✅ available · ◐ partial · — not available · n/a not applicable.
| Feature | Web | macOS | iOS / iPadOS | Note for iOS |
|---|---|---|---|---|
| Notes: create, edit, autosave | ✅ | ✅ | ✅ | Saved locally ~0.6 s after the last keystroke |
| Works fully offline | ◐ one draft per open page | ✅ | ✅ | Local SQLite database; validated by the scenario test |
| Native rich-text editor | Tiptap (web) | TextKit 2 | ✅ TextKit 2 | No web view |
| Tables | ✅ in place | ✅ | ◐ | Edited in a native table sheet |
| Equations (LaTeX) | ✅ KaTeX | ✅ | ✅ | Typeset natively (SwiftMath) |
| Toggles, footnotes, YouTube, AI blocks | ✅ | ◐ | ◐ | Kept untouched and shown; cannot be created here |
| Markdown shortcuts while typing | ✅ | — | — | Markdown is supported for import, export and assistant results |
| Drawings (Apple Pencil) | — | shows the image | ✅ | PencilKit |
| Handwriting / document text recognition | — | — | ✅ | Vision, on device |
| Pinned · favourites | pinned only | ✅ | ✅ | Favourite = properties.favorite |
| Capture inbox | ✅ | — | ◐ | Other triage actions on the web |
| Search | hybrid, online | local | ✅ local FTS5 | No semantic search |
| Questions about the notes (grounded, with sources) | ✅ | — | ✅ | Online only |
| AI agents, model comparison, routing dashboard, budgets | ✅ | — | — | Web only |
| Databases (tables, boards, calendars) | ✅ | — | — | Listed read-only with "open on the web" |
| Research workspace | ✅ | — | — | Research pages are editable as notes |
| Knowledge graph, backlinks explorer | ✅ | — | — | |
| Tasks page | ✅ | — | ◐ | Reminders on a note create tasks; no global task list |
| Reminders with notifications | — | — | ✅ | Device → server only |
| Import (Markdown, ZIP, Notion, DOCX, PDF) | ✅ | ◐ | ◐ | Share extension and file attachments; no bulk importer |
| App lock (biometrics) | n/a | — | ✅ | Local only |
| Passkey and session management | ✅ | ◐ | ✅ | |
| First passkey enrollment / recovery | CLI on the node + web | — | — | By design of the server |
| Widgets, Siri / Shortcuts, Spotlight, share sheet | n/a | — | ✅ |
🏗 Architecture
flowchart TB
subgraph EXT["Extensions"]
W["SPNotesWidgets<br/>WidgetKit · read-only store"]
SH["SPNotesShare<br/>writes one SharedItem"]
end
subgraph APP["SPNotes.app"]
F["Features/<br/>17 SwiftUI feature folders"]
M["AppModel<br/>the only writer"]
ED["Editor/<br/>TextKit 2 engine"]
I["App Intents · Spotlight · BackgroundSync"]
F --> M
ED --> M
I --> M
end
subgraph CORE["SPNotesCore (../SPNotesCore, shared with macOS)"]
D["SPNotesDocument"]
ST["SPNotesStore"]
A["SPNotesAPI"]
SY["SPNotesSync"]
end
G[("App Group container<br/>SQLite · attachments · share hand-off")]
M --> ST
M --> SY
ED --> D
SY --> ST
SY --> A
ST --> G
W --> G
SH --> G
A -- HTTPS --> SRV["https://note.spboucher.ai"]
A --> KC["Keychain<br/>session token"]
- Document: the server stores notes as ProseMirror JSON.
SPNotesDocumentreads it into flat lines with their container paths and writes it back without loss (unknown nodes included). The editor's text storage carries that model in attributes (Editor/EditorAttributes.swift); it is converted back at each save. Only edited paragraphs are restyled while typing. - Local first:
AppModelwrites every change toSPNotesStore(SQLite, WAL,synchronous=FULL, FTS5 search) and schedules a sync. No screen waits for the network to save. - Sync (
SPNotesSync): pushes creations, edits (with the server version they were based on), tags, files and queued actions; reads the server change feed; merges concurrent edits block by block; records a conflict — both copies kept — when a merge is unsafe. SeeSYNC_ENGINE.mdin sp-notes-core. - Sign-in: passkeys through the system sheet (Face ID / Touch ID); the session token is kept in the Keychain; optional local app lock.
- Extensions: the widget extension reads the shared database; the share extension only writes one
SharedIteminto the App Group container — it never opens the database nor the network, and the app turns the item into a note at its next activation.
The mandatory offline scenario
sequenceDiagram
autonumber
participant U as User
participant A as AppModel
participant S as Local store
participant E as SyncEngine
participant B as Backend
A->>E: sync
E->>B: push / pull — two notes in step
Note over A,B: network lost
U->>A: edit two notes, tag, pin, create a note, attach a local picture
A->>S: every change written at once
Note over A,S: app closed, reopened without network
A->>S: everything present · offline search finds it
Note over A,B: network back
A->>E: sync
E->>B: creations, uploads, edits with baseVersion, queued actions
B-->>E: change feed
Note over B: server holds everything · picture byte-identical · a second device receives it all
This is Tests/OfflineScenarioTests.swift, run through the app model against the development server.
🧱 Stack
| Layer | Technology | Version | Role |
|---|---|---|---|
| Language | Swift, complete strict concurrency | 6.0 (SWIFT_VERSION) |
— |
| Interface | SwiftUI, UIKit where needed | — | every screen; no web view of any kind |
| Editor | UITextView on TextKit 2 |
— | custom layout fragments, codec document ⇄ text storage |
| Shared core | SPNotesCore (local package ../SPNotesCore) |
commit b06b1ed |
document model, local store, API client, sync engine |
| Math | SwiftMath | 1.7.3 (exact) | LaTeX typesetting in Core Text |
| Storage | system SQLite | — | WAL, synchronous=FULL, FTS5 |
| Widgets | WidgetKit, App Intents | — | 4 widgets, configurable note widget |
| Siri and Shortcuts | App Intents | — | 6 intents, AppShortcutsProvider |
| System search | Core Spotlight | — | incremental index from the store's change stream |
| Drawing | PencilKit | — | Apple Pencil |
| Recognition | Vision | — | on-device text recognition |
| Sign-in | AuthenticationServices | — | passkeys of note.spboucher.ai |
| App lock | LocalAuthentication | — | Face ID / Touch ID, device passcode as the system fallback |
| Background | BackgroundTasks | — | app refresh and processing tasks |
| Project | XcodeGen (project.yml) |
— | generates SPNotes.xcodeproj |
| 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 |
🗂 Repository layout
161 tracked files, including 98 Swift files (18 667 lines).
sp-notes-ios/
├── App/ # 12 files · entry point, application model (AppModel), configuration, intents, background sync, sample data
│ └── Intents/ # App Intents, shortcuts, quick-note actions, Spotlight indexer, routing
├── Core/ # 4 files · attachment files, app lock (Face ID / Touch ID), network monitor, reminders
├── Editor/ # 9 files · the native editor engine (TextKit 2): codec document ⇄ text storage, styler, layout fragment, toolbar
├── Features/ # 48 files · screens
│ ├── Root/ Home/ Notes/ Folders/ Tags/ Search/ Organize/
│ ├── Editor/ AI/ History/ Conflicts/ Reminders/
│ └── Attachments/ Drawing/ Export/ Settings/ Account/
├── Components/ # 4 files · shared views and theme
├── Shared/ # 3 files · code shared with the extensions (App Group, deep links, share hand-off)
├── WidgetShared/ # 3 files · widget views and data provider (app + widget extension)
├── Widgets/ # WidgetKit extension
├── ShareExtension/ # share extension
├── Design/ # vector sources of the icon (default, dark, tinted) and of the mark
├── Resources/ # Info.plist, entitlements, privacy manifest, asset catalog, string catalogs
├── Tests/ # 7 files · 128 unit tests
├── UITests/ # 3 files · 12 UI tests
├── Scripts/ # build, test, release, App Store Connect client
├── docs/ # audit, parity, status, distribution, UI conventions (+ brand/)
├── project.yml # XcodeGen definition: app, widget extension, share extension, unit and UI tests
└── SPNotes.xcodeproj🚀 Getting started
Prerequisites: clone sp-notes-core next to this repository as
SPNotesCore, and install XcodeGen.
Scripts/build.sh generate # regenerate the Xcode project (after adding files)
Scripts/build.sh debug | test | uitest # SPNOTES_SIM="iPad Pro 13-inch (M5)" for the iPad
Scripts/build.sh core # the shared core's tests on the host
Scripts/test-live.sh # offline scenario against the development server
Scripts/release.sh all # signed archive + IPA; Scripts/release.sh upload → TestFlight| Script | Usage |
|---|---|
Scripts/build.sh |
generate | debug | release | test [xcodebuild args] | uitest [xcodebuild args] | core — filtered xcodebuild output, full log in build/logs |
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) |
Scripts/release.sh |
archive | export | upload | all — Release archive, IPA export, optional TestFlight upload |
Scripts/asc.py |
minimal App Store Connect API client: asc.py GET /v1/apps?filter[bundleId]=… |
Scripts/build.sh generate also writes Resources/Info-Debug.plist (the release Info.plist plus local networking,
for the development server reached through a tunnel); that file is not tracked.
⚙️ Configuration
No secret lives in the repository or in the binary: the session token is in the Keychain, and the release scripts reuse the signing identities and the App Store Connect API key already on the Mac.
| Variable | Scope | Purpose |
|---|---|---|
SPNOTES_SIM |
Scripts/build.sh |
simulator name (default iPhone 17 Pro) |
SPNOTES_STORE |
Debug launch | memory: throw-away database |
SPNOTES_SESSION |
Debug launch | local: use the app without a server |
SPNOTES_SEED |
Debug launch | 1: sample notes from App/SampleData.swift |
SPNOTES_BASE_URL, SPNOTES_TOKEN |
Debug launch | development server through an SSH tunnel; never production |
SPNOTES_DATA_DIR |
Debug launch | data directory override |
SPNOTES_LIVE_URL, SPNOTES_LIVE_TOKEN |
live tests | set by Scripts/test-live.sh |
| Setting | Value |
|---|---|
MARKETING_VERSION · CURRENT_PROJECT_VERSION |
1.0.0 · 1 |
| Bundle identifiers | ai.spboucher.spnotes.ios, …ios.widgets, …ios.share |
| App Group | group.ai.spboucher.spnotes.ios (shared database, attachments, share hand-off) |
| Associated domain | webcredentials:note.spboucher.ai |
Base URL (SPNotesBaseURL) |
https://note.spboucher.ai |
| App Transport Security | arbitrary loads and local networking both disabled in the release Info.plist |
| Background modes | fetch, processing (task identifiers …ios.refresh, …ios.sync) |
| Localizations | fr (development language), en |
| Usage descriptions | camera (scan a document or attach a photo), Face ID (unlock the notes on this device) |
📱 Screens
| Feature folder | Screens |
|---|---|
Root |
root view, main interface (iPhone and iPad layouts), sidebar, lock screen |
Account |
welcome and passkey sign-in, sign-in failures |
Home |
home screen, new-note button |
Notes |
note lists, note actions, note link picker |
Folders · Tags |
folder tree and folders screen · tags screen |
Organize |
move-note sheet, tag editor |
Search |
search screen with criteria |
Editor |
note editor screen, native document view, keyboard avoider, drop handler; link, math and table sheets |
AI |
assistant sheet and chat |
History · Conflicts |
note history · conflict sheet |
Reminders |
reminders of a note |
Attachments |
attachment list and preview, media pickers, document scanner |
Drawing |
PencilKit drawing screen |
Export |
exporter, share sheet, ZIP writer |
Settings |
settings and security screens (passkeys, sessions, app lock) |
Conventions for everyone writing screens — French interface text (informal "tu"), colours by asset name, Dynamic Type,
hit targets ≥ 44 pt, VoiceOver labels, light and dark, iPhone and iPad: docs/UI_CONVENTIONS.md.
🧩 System integration
| Integration | Detail |
|---|---|
| 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) |
| 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) |
| 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 |
| Share extension | Receives content from other apps and hands it to the app through the App Group |
| 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 |
| Background | App refresh and processing tasks (BackgroundSync) |
| Notifications | Local reminder notifications |
| iPad | Multiple scenes, indirect input, all four orientations, Split View and Stage Manager widths |
| Exported type | ai.spboucher.spnotes.note-reference (« Référence de note SP Notes ») |
🗃 Data model and conventions
The local database, the dirty flags, the queue and the search index are those of
sp-notes-core (SPNotesStore). App-level conventions, shared with the
macOS app:
| Concept | Representation |
|---|---|
| Note | a page |
| Folder | a page flagged properties.folder = true (a plain page with sub-pages on the web) |
| Favourite | properties.favorite = true (ignored by the web interface); favourite ≠ pinned |
| Sections | notes, documents, projects, research (+ databases, read-only here) |
| Reminder | a task { pageId, dueAt } |
| PencilKit drawing | an image (visible everywhere) + a companion .pkdrawing attachment (editable source) |
| Smart lists | all · recent · pinned · favorites · inbox · archived · trash |
Reads go through the store (an actor); writes go only through AppModel, which schedules the synchronisation and
updates the widgets.
🔒 Security and privacy
- No web view (no
WKWebView, noSFSafariViewController): external links open in the system browser. - Passkeys only, through the system sheet and the associated domain
webcredentials:note.spboucher.ai; nothing biometric ever leaves the device. - The session token is kept in the Keychain; no secret in the repository or in the binary.
- App lock is purely local (Face ID / Touch ID, device passcode as the system fallback); the server session is not involved.
- Permanent deletion is confirmed with the passkey (server rule).
- App Transport Security: no arbitrary loads; local networking is only allowed in the Debug
Info-Debug.plist. - The share extension never opens the database nor the network.
- Privacy manifest (
Resources/PrivacyInfo.xcprivacy): no tracking, no tracking domains; collected data = user content and photos, linked to the account, for app functionality only; required-reason APIs = UserDefaults and file timestamps. - No end-to-end encryption: notes are stored on the device (file protection until first unlock) and on the owner's server over HTTPS.
🧪 Testing
| Suite | Tests | What it covers |
|---|---|---|
Tests/NoteFeatureTests.swift |
33 | assistant actions and questions (fake provider), history, reminders, export menu, note screen |
Tests/MediaExportTests.swift |
27 | note exporter, ZIP writer, table editor model, link and math models, media |
Tests/ShellTests.swift |
24 | list ordering, folder tree and moves, tag editing, search criteria, shell |
Tests/SystemIntegrationTests.swift |
23 | deep links, share hand-off import, quick-note actions, sample data, widget data and snapshots, Spotlight indexer, bundle integration |
Tests/EditorTests.swift |
19 | typing, Enter, Backspace, lists, checkboxes, code, atoms, marks, links, undo/redo |
Tests/EditorRenderingTests.swift |
1 | rendering of every block, light and dark |
Tests/OfflineScenarioTests.swift |
1 | the mandatory offline scenario, against the development server |
| Unit tests | 128 | Swift Testing, 27 suites |
UITests/ShellUITests.swift |
5 | phone flow, phone dark and landscape, welcome screen, iPad split view, iPad dark |
UITests/SystemUITests.swift |
4 | spnotes:// links: new note, open a seeded note, task-list link, malformed and unknown links ignored |
UITests/EditorUITests.swift |
3 | write, format and reopen; assistant sheet; dark appearance |
| UI tests | 12 | XCUITest, run on iPhone 17 Pro and iPad Pro 13-inch (M5) |
Status of 1.0.0 (1), 2026-11-18 (docs/IMPLEMENTATION_STATUS.md):
| What | Evidence |
|---|---|
Shared core SPNotesCore (commit b06b1ed) |
283 tests on the host: Document 81, Store 49, API 88, Sync 65 |
| 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 |
| Native editor engine | 19 tests; 3 000 paragraphs load in ~0.1 s |
| 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) |
| Mandatory offline scenario | passed |
| Signing and packaging | Release archive, IPA signed Apple Distribution with associated domain and App Group, both extensions embedded; uploaded to App Store Connect |
Not verifiable in the simulator — to check on a real iPhone / iPad
- Passkey sign-in with Face ID / Touch ID (system sheet, associated domain; first time on this device), step-up for permanent deletion, adding an iPhone passkey from Settings → Sécurité.
- The complete offline scenario with airplane mode and a device restart.
- Software keyboard with the formatting bar on a real phone; hardware keyboard shortcuts on iPad; rotation while editing.
- Camera, document scanner, Apple Pencil drawing (tool picker, zoom), drag and drop from other apps.
- Widgets on the Home and Lock Screens, Siri phrases, Shortcuts actions, Spotlight results, the share sheet from Safari / Photos / Files.
- Background refresh and processing tasks, reminder notifications (banner, tap opens the note).
- App lock with Face ID after the grace period; privacy cover in the app switcher.
- VoiceOver through sign-in, lists and the editor toolbar; largest Dynamic Type sizes.
- Instruments (time profiler, allocations, energy) on a device: no profiling session was run.
- Assistant streaming and server history against production (covered by a fake provider and by the API module's live tests of the error paths; no real generation was triggered to avoid cost).
🚢 Release and TestFlight
flowchart LR
V["project.yml<br/>bump CURRENT_PROJECT_VERSION"] --> T["Scripts/build.sh test · uitest"]
T --> A["release.sh archive<br/>signed with the Xcode account"]
A --> E["release.sh export<br/>IPA · API key"]
E --> U["release.sh upload<br/>App Store Connect"]
U --> TF["TestFlight<br/>internal group « Test »"]
| Item | Value |
|---|---|
| App Store Connect record | SP Notes, app 6836504456, SKU spnotes-ios-001, primary language fr-CA |
| App identifiers | ai.spboucher.spnotes.ios (Associated Domains, App Groups), …ios.widgets (App Groups), …ios.share (App Groups) |
| Signing | automatic; Apple Distribution managed by Xcode |
| 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) |
| TestFlight | internal group « Test » (access to all builds), the account holder invited |
| Notarisation | does not apply to an App Store / TestFlight distribution of an iOS app |
| Toolchain at release | Xcode 27.2 (27B52), iOS SDK 27.2, simulators iOS 26.5 |
For a new version: increment CURRENT_PROJECT_VERSION (and MARKETING_VERSION when needed) in project.yml, run the
tests, then Scripts/release.sh all && Scripts/release.sh upload.
Before an App Store submission (not done; TestFlight internal testing needs none of this): screenshots (the UI
tests produce them in build/shots*), description, keywords, support and privacy-policy URLs, the privacy
questionnaire (consistent with PrivacyInfo.xcprivacy), age rating, and a demonstration account for review (the
service has a single owner: without a test account Apple's review cannot sign in).
Details: docs/DISTRIBUTION.md.
🧯 Troubleshooting and gotchas
| Trap | Explanation |
|---|---|
| "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. |
| 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. |
| A file was added and Xcode does not see it | The project is generated: Scripts/build.sh generate. |
The compiler does not find SPNotesCore |
sp-notes-core must be cloned next to this repository as SPNotesCore. |
| 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). |
NSTextStorageDelegate and Swift 6 |
It is not annotated MainActor: nonisolated(unsafe) + MainActor.assumeIsolated. |
Ambiguous SearchHit / Tombstone |
SPNotesStore and SPNotesAPI both define them: qualify (SPNotesStore.SearchHit). |
| "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. |
XCUIApplication.open(url) |
It relaunches the app; with an in-memory database the link arrives before the sample data. |
| 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. |
| 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. |
| 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. |
| Development server | Reached through ssh -N -L 8482:localhost:8482 M4M64c; never production. |
🚧 Known limitations
From docs/IMPLEMENTATION_STATUS.md.
- Tables are edited in a sheet (cell text), not in place; code blocks have no syntax colouring in the editor.
- Details/toggles, footnotes, YouTube embeds and AI blocks made on the web are kept and shown but cannot be created here.
- The merge of concurrent edits works per top-level block: two devices editing the same list at the same time produce a conflict (both copies kept, the user chooses).
- Reminders sync to the server as tasks; a task changed on the web does not come back to the device (the server has no change feed for tasks).
- An untitled note is stored as "Untitled" (the server's convention): searching « Sans titre » does not find it.
- No end-to-end encryption.
- English translations exist for the system-integration strings; the other screens are French only.
- Attachment uploads need about one extra file size of free space and are not resumable; no ZIP64 (archives over 4 GiB).
- RTF export: pictures and block equations are embedded in a form Apple's own RTF reader ignores.
- Web-only features (databases, research references, graph, agents, AI administration, bulk import) are listed in
PARITY_MATRIX.md. - Build 1.0.0 (1) has not been validated on a physical device (see the list above).
Backend defects observed (pre-existing, not blocking): GET /api/tags counts 0 pages; purging a page leaves its
attachments alive; malformed ids answer 500; no cycle check on parentId; /api/files/<id> still serves a
soft-deleted file.
📚 Documentation
| Document | Content |
|---|---|
docs/AUDIT.md |
audit of the existing backend, what had to be added to it, decisions that follow |
docs/PARITY_MATRIX.md |
functional parity Web · macOS · iOS / iPadOS |
docs/IMPLEMENTATION_STATUS.md |
what was verified by tests that ran, what must be checked on a device, known limits |
docs/DISTRIBUTION.md |
signing, App Store Connect, TestFlight |
docs/UI_CONVENTIONS.md |
conventions for everyone writing screens |
CLAUDE.md |
project rules, recipes and traps (French) |
👤 Author
Simon-Pierre Boucher — design, development, operations
📄 License
All rights reserved © 2026 Simon-Pierre Boucher.