SPB Git

Repository Public

20 entries at the root
History

Latest commit docs: final lot — hosted screens opened on screen, captures in the server inbox, universal links, final counts (393 unit, 33 UI per device, 3 live + 3 live UI per device) 83ef1c3

NameLast commitUpdated
App Hosted SPNotesFeatures screens opened on screen: live UI tests on the integration server (DEBUG...
Components Signature motions of the shell: Fluid Navigation (zoom from the row), Living Pages (rows),...
Core Final Core: captures reach the server inbox (CaptureLedger removed), Core's ink width law and...
Design SP Notes iOS / iPadOS 1.0.0 (1): native offline-first notes app for note.spboucher.ai
docs docs: final lot — hosted screens opened on screen, captures in the server inbox, universal...
Editor Final Core: captures reach the server inbox (CaptureLedger removed), Core's ink width law and...
Features Hosted SPNotesFeatures screens opened on screen: live UI tests on the integration server (DEBUG...
Resources Final Core: captures reach the server inbox (CaptureLedger removed), Core's ink width law and...
Scripts Hosted SPNotesFeatures screens opened on screen: live UI tests on the integration server (DEBUG...
Shared Shell 2.0: typed routes with block ids, route coordinator, tabs, sidebar sections, menus,...
ShareExtension SP Notes iOS / iPadOS 1.0.0 (1): native offline-first notes app for note.spboucher.ai
SPNotes.xcodeproj Hosted SPNotesFeatures screens opened on screen: live UI tests on the integration server (DEBUG...
Tests Hosted SPNotesFeatures screens opened on screen: live UI tests on the integration server (DEBUG...
UITests Hosted SPNotesFeatures screens opened on screen: live UI tests on the integration server (DEBUG...
Widgets System: widgets respect the app lock (mirrored flag, redacted state, locked note picker); «...
WidgetShared System: widgets respect the app lock (mirrored flag, redacted state, locked note picker); «...
.gitignore Core 2.0 adoption: typed store open with a blocking failure screen, v1→v2 migration tests in a...
CLAUDE.md docs: final lot — hosted screens opened on screen, captures in the server inbox, universal...
project.yml Host SPNotesFeatures: ten hosted sections gated on server features, FeatureRouter over the shell...
README.md docs: implementation status, parity matrix, README and project guide for 2.0.0 (2)
README.md View source
SP Notes logo



SP Notes icon

# 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

note.spboucher.ai version platform TestFlight license author

Swift SwiftUI UIKit SPNotesCore SwiftMath SQLite WidgetKit App Intents PencilKit Vision Core Spotlight Passkeys XcodeGen web views

commits last commit activity language languages size branches tags clones

Swift files Swift lines feature folders targets unit tests UI tests widgets app intents languages

bundle extensions signing App Store Connect build deployment target devices Xcode


# 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

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. SPNotesDocument reads 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: AppModel writes every change to SPNotesStore (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. See SYNC_ENGINE.md in 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 SharedItem into 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).

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

sh
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, no SFSafariViewController): 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
  1. 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é.
  2. The complete offline scenario with airplane mode and a device restart.
  3. Software keyboard with the formatting bar on a real phone; hardware keyboard shortcuts on iPad; rotation while editing.
  4. Camera, document scanner, Apple Pencil drawing (tool picker, zoom), drag and drop from other apps.
  5. Widgets on the Home and Lock Screens, Siri phrases, Shortcuts actions, Spotlight results, the share sheet from Safari / Photos / Files.
  6. Background refresh and processing tasks, reminder notifications (banner, tap opens the note).
  7. App lock with Face ID after the grace period; privacy cover in the app switcher.
  8. VoiceOver through sign-in, lists and the editor toolbar; largest Dynamic Type sizes.
  9. Instruments (time profiler, allocations, energy) on a device: no profiling session was run.
  10. 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

www.spboucher.ai · git.spboucher.ai · contact@spboucher.ai

# 📄 License

All rights reserved © 2026 Simon-Pierre Boucher.

Clone sp-notes-ios

Anonymous clone and fetch. Pushing requires the owner's personal access token.

Snapshot of main

Files main
Menu

Theme