SP Note Next Generation — code audit of SPNotesCore and SP Notes (macOS)
Audit date: 2026-11-19. Read-only: nothing was edited, built or launched.
Sources read: ~/Desktop/Cluster/apple/SPNotesCore (git main @ 267a673, clean, origin gitsrv:srv/git/sp-notes-core.git)
and ~/Desktop/Cluster/apple/SPNotes (git main @ bc6ea93, clean, origin gitsrv:srv/git/sp-notes-macos.git).
The production server route list was read over SSH on M4M64c:~/apps/note-spboucher-ai (HEAD 77ef5f0) with find.
Legend: [code] = read in the source; [doc] = taken from the project's own docs and not re-checked line by line; [not verified] = not checked. No test was run during this audit: every test count below is a count of declarations or a number reported by the projects' docs.
A. SPNotesCore
A.6 Package.swift (first, because it frames the rest) [code]
swift-tools-version: 6.0, every target.swiftLanguageMode(.v6).- Platforms:
.iOS(.v18),.macOS(.v15).defaultLocalization: "fr". - No external dependency. Only the system
sqlite3(linker setting onSPNotesStore). - Products: libraries
SPNotesDocument,SPNotesStore,SPNotesAPI,SPNotesSync, plus umbrellaSPNotesCore(Sources/SPNotesCore/SPNotesCore.swift= four@_exported import). - Dependencies between modules: Document, Store, API are independent of each other. Sync depends on the three.
SPNotesStoredoes not importSPNotesDocument: content is opaqueData, the caller supplies plain text, word count, preview. SPN_ONLY=Document|Store|API|Sync(read from the environment insidePackage.swift) declares a single module and its tests;SPN_ONLY=Syncalso declares the three it depends on. The umbrella product exists only whenSPN_ONLYis unset.- Size: 44 source files / about 12 500 lines, 27 test files / about 9 000 lines.
- Stale scratch directories are present in the tree:
.build-api,.build-doc,.build-main,.build-store,.build-synctest.
Name clashes to know before importing the umbrella: SearchHit, PurgeResult and Tombstone exist in both SPNotesAPI
and SPNotesStore (the sync engine already writes SPNotesStore.Tombstone). JSONValue exists twice: public in
SPNotesDocument/Model.swift:14, internal in SPNotesAPI/JSONSupport.swift:72 (the API exposes RawJSON instead).
A.1 SPNotesDocument [code]
Files (Sources/SPNotesDocument/): Model.swift 406, Schema.swift 271, Commands.swift 609, InlineCommands.swift 135,
Inline.swift 181, MarkdownImport.swift 605, MarkdownExport.swift 89, HTMLExport.swift 179, Text.swift 245,
Merge.swift 138, SchemaValidation.swift 96, Tables.swift 120, BlockIds.swift 64, JSONValue.swift 329.
Model types (Model.swift)
| Type | Role |
|---|---|
JSONValue (l.14) |
null, bool, int(Int64), double, string, array, object; integers stay integers |
PMMark (l.61) |
type: String, attrs: [String: JSONValue]? |
PMNode (l.99) |
type, attrs?, content?, text?, marks?, extra — the raw ProseMirror node |
NoteDocument (l.232) |
lines: [Line] + internal root: PMNode (the doc shell) + nextKey |
Line (l.209) |
path: [Container], type: String, attrs, content: LineContent, internal preserved |
Container (l.177) |
key: Int (local, not persisted), type, attrs, internal preserved |
LineContent (l.200) |
.inline([InlineRun]) or .blockAtom(PMNode) |
InlineRun (l.192) |
.text(String, marks: [PMMark]) or .atom(PMNode) |
MergeResult (l.226) |
.merged(NoteDocument) or .conflict |
There is no per-node Swift type. A node type is a String; "typed support" means: a constant in enum NodeType,
membership in the Schema sets, default attributes, a factory, and a case in each exporter. Classification happens in
one function, NoteDocument.shape(of:) (Model.swift:320-327):
- a node with
text→ atom; - type in
Schema.textBlocks→ text line; - type in
Schema.blockAtoms→ block atom line; - no children → atom;
- type in
Schema.containers→ container frame; - otherwise: any child that is text or in
Schema.inlineTypes→ text line, else container.
Known node types (Schema.swift:11-42, 30 constants, identical to docs/reference/web-editor-schema.txt, recorded from
backend commit 2c18f85):
| Class | Types |
|---|---|
text blocks (Schema.textBlocks, l.85) |
paragraph, heading, codeBlock, footnote, detailsSummary |
block atoms (Schema.blockAtoms, l.86) |
table (whole subtree raw), image, fileBlock, blockMath, horizontalRule, youtube |
containers (Schema.containers, l.87) |
bulletList, orderedList, taskList, listItem, taskItem, blockquote, callout, aiBlock, details, detailsContent |
inline (Schema.inlineTypes, l.89) |
text, hardBreak, mention, inlineMath, footnoteRef, and the legacy name "math" |
| structural only | doc, tableRow, tableHeader, tableCell |
Marks: Schema.markOrder (l.107) = link, bold, code, italic, strike, underline, highlight, subscript, superscript.
MarkKind (l.45) is the toggleable set (all but link); code excludes the others.
None of mermaid, drawing, chart, citation, pdf, blockRef, aiResult, queryView, runnableCode exists
anywhere in Core or in the reference schema file. A grep for these names returns only "mermaid" as a code block
language in the macOS syntax highlighter (mapped to "no grammar").
Unknown content: how it survives the round trip
- Unknown node type: falls through
shape(of:)rules 4-6. A leaf becomes.blockAtom(node)(block level) or.atom(node)(inline), kept as the rawPMNode. A node with block children becomes aContainerframe of that type; a node with inline children becomes a text line of that type. - Unknown attributes:
attrsis a dictionary, nothing is filtered. - Unknown keys on a node:
PMNode.extra(Model.swift:106), also used for a known key with an unexpected shape (attrs: null, malformedmarks). For lines and containers the same data is carried byPreserved(Model.swift:166:emptyAttrs,emptyContent,marks,extra). - Unknown marks:
PMMark.typeis a string; marks are kept in document order on the run.PMMark(json:)refuses a mark with keys other thantype/attrs(l.74), in which case the wholemarksarray stays inextra. - Text nodes the model could not give back identically (adjacent same-mark text nodes, empty text,
marks: [], text withattrsor extra keys) are kept as raw.atomruns of typetext(Model.swift:366-374). - Absent vs empty
attrs/contentis preserved. - Stated guarantee [doc,
DOCUMENT_API.md]: unmodified document →jsonData()semantically identical, key order aside. Output is canonical JSON with sorted keys.
Consequence for the upgrade: a new leaf node type already round-trips with zero change in Core. A new node type that has
children is where behaviour depends on the Schema sets (see "adding a type" below).
Block ids
BlockID.generate()(Schema.swift:147): 10 characters of the 64-character nanoid alphabet.Schema.idTypes(l.91) = the server'sID_TYPES:paragraph, heading, blockquote, codeBlock, bulletList, orderedList, taskList, table, callout, details, aiBlock, blockMath, image, fileBlock. Not in the list:horizontalRule,youtube,footnote,listItem,taskItem, table rows and cells.NoteDocument.ensureBlockIds()→assignBlockIds()(BlockIds.swift:12): pre-order walk, assigns an id when missing or when it duplicates an earlier one. Described as equivalent to the server'sensureBlockIds.- New nodes get an id at creation through
Schema.attrs(_:_:)(Schema.swift:138).
Exports and text (all switch n.type with a default that recurses into children)
| Function | File | Unknown node |
|---|---|---|
markdown() |
MarkdownExport.swift:45 (block) and :11 (inline) |
children concatenated, a leaf yields nothing |
html(title:), htmlBody() |
HTMLExport.swift:73 (block) and :42 (inline) |
default: at l.127 [branch body not read] |
plainText(), wordCount, preview(maxLength:) |
Text.swift:141-170 |
text of descendants |
pageReferences() |
Text.swift:179 |
mention ids (not kind: "user") and link hrefs containing /p/<uuid> |
attachmentReferences() |
Text.swift:192 |
any node attrs.src with /api/files/<uuid>, plus fileBlock.attachmentId |
taskItems() |
Text.swift:204 |
— |
init(markdown:) |
MarkdownImport.swift |
port of the server's marked-based import |
plainText, wordCount and markdown are stated to match the server byte for byte [doc]. That contract is the reason
every new node type needs the same case on the server (text.ts, html.ts) and here, in the same commit.
attachmentReferences() already picks up any new node type that stores a file in attrs.src.
Three-way merge (Merge.swift, 138 lines)
- Granularity: top-level blocks of
doc, each compared as a whole canonical JSON string. An entire list, quote, callout or table is one block: two edits inside the same list conflict. - Identity: the block id; a block without an id is identified by its content plus occurrence rank (l.19-36).
- Order: diff3 over the identity sequences using an LCS (
mergeOrder, l.63). .conflictwhen: same block changed differently on both sides; changed on one side and deleted on the other; both sides inserted or reordered differently at the same place; thedocshell changed on both sides; the result would be empty; duplicate ids (top level before, any nested id after the merge).- No intra-block text merge, no CRDT, no operational transform.
- Title and properties are merged outside this module, in
SyncEngine.merge(SyncEngine.swift:946) andmergeObjects(l.968): title "one side changed", properties key by key.
Schema validation (SchemaValidation.swift): SchemaChecker.known (l.31) is a closed set; check reports
unknown node type for anything else and strict mode compares attribute key sets with Schema.nodeDefaults. Used by tests
and debug assertions.
Commands (Commands.swift, InlineCommands.swift, Tables.swift): setLineType, toggleList, indentListItems,
outdentListItems, toggleBlockquote, toggleCallout, setTaskChecked, splitLine, mergeWithPrevious,
insertBlockAtom, replaceBlockAtom, deleteLine, replaceText, insertInlineAtom, toggleMark, setLink,
removeLink, queries (listKind, listDepth, isListItemHead, isTaskChecked, listItemNumber), and table helpers on
PMNode (tableGrid, setTableCellText, insert/deleteTableRow, insert/deleteTableColumn, toggleTableHeaderRow).
Table helpers do not resolve colspan/rowspan geometry [doc]. Headings are clamped to levels 1-3.
What it takes to add typed support for a new node type — exact places:
| # | Place | What to add |
|---|---|---|
| 1 | Schema.swift:11 enum NodeType |
a public static let |
| 2 | Schema.swift:85-89 |
the type in exactly one of textBlocks, blockAtoms, containers, inlineTypes |
| 3 | Schema.swift:95 blockGroup or :99 inlineGroup |
group membership (drives the validator) |
| 4 | Schema.swift:91 idTypes |
only if the server's ID_TYPES gains it too |
| 5 | Schema.swift:111 nodeDefaults |
the full default attribute set, as the web editor serializes it |
| 6 | Schema.swift:178+ extension PMNode |
a factory (PMNode.mermaid(source:), …) |
| 7 | SchemaValidation.swift:29 leaves, :31 known, :44 switch n.type |
leaf or content rule |
| 8 | MarkdownExport.swift:45 and :27 |
a case identical to the server's toMarkdown |
| 9 | HTMLExport.swift:73 and :62 |
a case identical to the server's print view |
| 10 | Text.swift:141 nodeText |
only if the plain text is not "text of descendants" |
| 11 | MarkdownImport.swift |
only if Markdown should produce the node (e.g. a ```mermaid fence) |
| 12 | docs/reference/web-editor-schema.txt and Tests/SPNotesDocumentTests/Fixtures/*.json |
re-record from the web app |
| 13 | Merge.swift |
nothing: whole-block comparison |
Suggested class for each requested type (my reading of the model, to be confirmed against the web schema once it exists):
| Type | Class | Note |
|---|---|---|
mermaid, chart, pdf, drawing, queryView, blockRef (block embed) |
block atom, attrs only | zero structural risk; round-trips today as an unknown leaf |
citation, inline blockRef |
inline atom | add to inlineTypes and inlineGroup; counts as 1 UTF-16 unit |
aiResult |
container of blocks, like aiBlock |
also add to Schema.wrappers (l.103) and blockParents (l.105) if blocks may be lifted out |
runnableCode |
text block like codeBlock, or block atom |
as a text block it must join every codeBlock special case: grep NodeType.codeBlock in Commands.swift, Inline.swift, SchemaValidation.swift:49; and ParaStyle.isCode in both native editors |
Hazard: a node type that holds text and is not registered falls to rule 6 and is flattened into an editable text line of an unknown type. The codec keeps it, but an editor that does not know the type will let the user type into it.
A.2 SPNotesStore [code]
Files: Schema.swift 204, SQLite.swift 254, NotesStore.swift 341, +Pages 434, +Queries 242, +Sync 445,
+Queue 276, +History 216, Models.swift 554. public actor NotesStore.
Connection: SQLITE_OPEN_FULLMUTEX, journal_mode=WAL, synchronous=FULL, foreign_keys=ON, busy_timeout 8 s,
write transactions BEGIN IMMEDIATE [doc, STORE_API.md §1]. One file may be opened by several processes; a read-only
store never creates or migrates.
Migrations (Schema.swift:9-38): PRAGMA user_version; Schema.migrations: [Migration] = [v1]; currentVersion =
array count; each step runs in one transaction with its version bump; a file newer than the build is refused
(StoreError.schema). To add tables: append a v2 closure to the array (l.13). Never edit v1. The current schema
version is 1, so the first schema change of the upgrade is the first migration this code has ever run on real user files.
Schema v1 — 10 tables + 1 FTS5 virtual table:
| Table | Columns |
|---|---|
pages |
rid INTEGER PK AUTOINCREMENT, id TEXT UNIQUE, parent_id, database_id, type ('page'), section ('notes'), title, icon, cover, content BLOB, properties BLOB, position REAL, pinned, archived, server_version, word_count, created_at, updated_at, last_opened_at, deleted_at, inbox_at, capture_kind, rev, needs_create, dirty_content, dirty_meta TEXT, tags_dirty, edit_seq, sync_state ('synced'), sync_error, plain_text, preview, favorite, is_folder, local_updated_at |
page_bases |
page_id PK, title, content, properties, version |
tags |
name PK, color |
page_tags |
(page_rid → pages.rid ON DELETE CASCADE, name) PK |
pages_fts |
FTS5 (title, body, tags), tokenize='unicode61 remove_diacritics 2', rowid = pages.rid |
attachments |
id PK, page_id, filename, mime, size, sha256, page_count, created_at, deleted_at, rev, state ('remote'), local_path, keep_offline, uploaded, upload_attempts, last_error, last_accessed_at |
ops |
seq PK AUTOINCREMENT, kind, target_id, payload BLOB, idem_key UNIQUE, created_at, attempts, next_attempt_at, leased_until, handed_out, coalescable, last_error |
conflicts |
page_id PK, version, title, content, properties, updated_at, detected_at |
local_versions |
seq PK AUTOINCREMENT, id UNIQUE, page_id, created_at, title, content, word_count, reason, plain_text, preview |
reminders |
id PK, page_id, title, due_at, done, server_task_id, dirty, deleted, edit_seq, created_at, updated_at |
meta |
key PK, value |
Indexes on pages: pages_parent, pages_live_updated, pages_live_recent, pages_pinned, pages_favorite,
pages_inbox, pages_archived, pages_trash, pages_folders, pages_section_root, pages_dirty (partial, on
Schema.dirtyPredicate, which must stay textually identical to the index), pages_unsynced_state. Others:
page_tags_name, attachments_page, attachments_not_uploaded, attachments_local, ops_target, local_versions_page,
reminders_page, reminders_due, reminders_dirty.
Only page_tags has a declared foreign key; every other relation is by page id in code. Timestamps are integer
milliseconds. Ids are lowercase UUID strings.
Entity kinds stored: pages (which also stand for folders = properties.folder, and can hold database pages and rows
through type / database_id), base copies, tags, attachments metadata, queued ops, conflict copies, local versions,
reminders, key/value meta. Not stored: tasks as the server models them (only "reminders"), database schemas / views /
properties, graph edges or backlinks, embeddings, AI conversations, research references, agents, saved searches,
comments, canvases, user settings.
Public API surface [doc STORE_API.md, signatures spot-checked]:
- Engine:
init(url:readOnly:),inMemory(),close(),integrityCheck(),checkpoint(),rebuildSearchIndex(),wipeAll(). - Pages, local mutations (one transaction each):
createPage,createPages,updateContent,setProperties,setFavorite,setFolder,setPinned,setArchived,setIcon,setCover,setInbox,move,setTags,trash,restore,purge,duplicate,markOpened. - Queries:
page,summary,pageCount,summaries(list:)withSmartList(all, recent, pinned, favorites, inbox, archived, trash),children(of:),folderTree,ancestors,summaries(tag:),tags(),counts(). - Search:
search(query:filters:limit:), bm25 weights title 10 / tags 4 / body 1, last term as prefix, input always quoted. - Sync primitives:
syncCursor/setSyncCursor,pagesNeedingPush,pendingPushCount,pageBase,markPushed,markPushFailed,applyRemote(pages:attachments:tombstones:tags:cursor:),resetSyncState,removeSyncedPages(notIn:),resolveConflictUsingCopy,resolveConflictKeepingLocal. - Conflicts:
recordConflict,conflict,conflicts,clearConflict. - Ops queue:
enqueueOp(kind:targetId:payload:),nextOps(leases, per-target ordering),completeOp,failOp(backoff 5 s doubling to 900 s),releaseOp,releaseAllOpLeases,queuedOps,opCount. - Attachments:
addLocalAttachment,attachment,attachments(pageId:),pendingUploads, themarkAttachment…family,setAttachmentKeepOffline,touchAttachment,evictionCandidates,attachmentsWantedOffline,resetTransientAttachmentStates. - Local versions:
snapshot,localVersions,localVersion,restoreVersion; 100 per page. - Reminders:
createReminder,updateReminder,deleteReminder,reminder,reminders(pageId:),upcomingReminders,dirtyReminders,markReminderSynced. - Meta:
meta,setMeta,allMeta. - Change stream:
changes() -> AsyncStream<StoreChange>withpages(Set<String>), tags, attachments(Set<String>), queue, conflicts, reminders, meta(String), reset;noteExternalChange()for another process's writes.
A.3 SPNotesAPI [code]
Files: NotesAPI.swift 432, HTTPClient.swift 546, APIError.swift 201, AuthService.swift 80,
PasskeyAuthorizer.swift 137, PasskeyCeremony.swift 335, SessionTokenStore.swift 117, SSEParser.swift 111,
AIModels.swift 161, PageModels.swift 412, ServiceModels.swift 377, JSONSupport.swift 321, MultipartForm.swift 113,
APIConfiguration.swift 136.
Every endpoint method (NotesAPI.swift, line of the method):
| Method (line) | Verb and path |
|---|---|
sync(since:limit:) (32) |
GET /api/sync?since=&limit= |
createPage (45) |
POST /api/pages |
page(id:open:) (52) |
GET /api/pages/{id}[?open=1] |
pageHead (57) |
GET /api/pages/{id}?head=1 |
patchPage (63) |
PATCH /api/pages/{id} |
resolveConflict (75) |
POST /api/pages/{id}/resolve |
trashPage (82) |
DELETE /api/pages/{id} |
purgePage (88) |
DELETE /api/pages/{id}?purge=1 |
emptyTrash (95) |
DELETE /api/trash[?olderThanDays=] |
restorePage (102) |
POST /api/pages/{id}?action=restore |
duplicatePage (107) |
POST /api/pages/{id}?action=duplicate |
pageVersions (114) |
GET /api/pages/{id}/versions |
pageVersion (119) |
GET /api/pages/{id}/versions?v= |
restorePageVersion (126) |
POST /api/pages/{id}/versions |
pageTags (133) / setPageTags (141) |
GET / PUT /api/pages/{id}/tags |
tags (146) |
GET /api/tags |
uploadAttachment (159) |
POST /api/attachments (multipart, streamed from a file, progress callback) |
attachments(pageID:) (174) |
GET /api/attachments[?pageId=] |
deleteAttachment (181) |
DELETE /api/attachments?id= |
downloadFile (187) |
GET /api/files/{id} (to a file, progress callback) |
loginOptions (237) / loginVerify (242) |
POST /api/auth/login/options / …/verify |
reauthOptions (247) / reauthVerify (252) |
POST /api/auth/reauth/options / …/verify |
authState (257) |
GET /api/auth/state |
logout (264) |
POST /api/auth/logout |
sessions (269), revokeSession (276), revokeAllSessions (285) |
GET /api/auth/sessions, DELETE …/{id}, DELETE /api/auth/sessions |
passkeys (290) |
GET /api/auth/passkeys |
passkeyRegistrationOptions (295) / …Verify (301) |
POST /api/auth/passkeys/options / …/verify |
renamePasskey (310) / deletePasskey (315) |
PATCH / DELETE /api/auth/passkeys/{id} |
aiAction (327) |
POST /api/ai/action (SSE) |
aiChat (333) |
POST /api/ai/chat (SSE) |
search (366) |
GET /api/search (`mode=quick |
tasks (380), createTask (385), updateTask (390), deleteTask (396) |
GET / POST / PATCH / DELETE /api/tasks |
inbox (403), triageInboxItem (408), undoInboxAction (416) |
GET /api/inbox, POST /api/inbox/{id}, POST /api/inbox/undo |
capture (422) |
POST /api/capture |
health (429) |
GET /api/health |
Helpers: NotesAPI.newID(), newIdempotencyKey(), filePath(id:), fileID(fromSource:).
Auth and session (HTTPClient.swift, an actor):
- The backend authenticates with an HttpOnly cookie, not a bearer header. The client uses an ephemeral
URLSessionwith cookie storage, cookie handling, credential storage and URL cache switched off (l.189-197), reads the token fromSet-Cookieitself (absorb, l.381-402) and sendsCookie: __Host-note_session=<token>by hand (l.365-371). - Mutating requests (everything but GET) carry
Origin: <configuration.origin>and, when given,Idempotency-Key(l.360-363). User-Agent: SPNotes/<x.y.z> (iPhone|iPad|Macintosh; <os>) native(APIConfiguration.userAgent); the server labels the session from it.- Redirects are refused (session delegate, l.494). TLS ≥ 1.2 [doc].
- Token rotation: a
Set-Cookiewith a new value replaces the token and is saved to theSessionTokenStore; a cleared cookie or a 401 ends the session;sessionEvents()yieldssignedIn,tokenRotated,signedOut(reason). - WebAuthn ceremony state travels in a second cookie
__Host-note_wa: captured on anoptionscall (HTTPRequest.Ceremony.begin(key)), replayed once on the matchingverify(.complete(key)), keyslogin | reauth | register. SessionTokenStoreprotocol;KeychainTokenStore(SessionTokenStore.swift:33): generic password, serviceai.spboucher.spnotes.sessionby default, account = the backend origin,kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly, not synchronizable, optional access group, data-protection keychain on macOS by default.InMemoryTokenStorefor tests.AuthService(AuthService.swift):signIn(),stepUp(),addPasskey(label:stepUpIfNeeded:),withFreshSession { }(one automatic step-up on403 reauth_required),signOut().SystemPasskeyAuthorizer(PasskeyAuthorizer.swift:24):ASAuthorizationControllerfor assertion and registration;PasskeyCeremonydoes the JSON/base64url work;PasskeyError=cancelled, noCredentials, alreadyRegistered, notInteractive, inProgress, notAssociated, invalidOptions, failed(code:message:).- There is no client for first enrolment (
/api/auth/enroll/*): the first passkey is created on the web.
Streaming: HTTPClient.openStream (l.313) uses URLSession.bytes(for:) with Accept: text/event-stream and
streamIdleTimeout (120 s). SSEParser is a byte-fed parser. NotesAPI.events(from:) (l.343) turns it into
AsyncThrowingStream<AIEvent, Error>, ends at data: [DONE], and cancels the reader when the stream is dropped.
AIEvent (AIModels.swift:128) = meta, text, done, error, needsConfirmation, other(type:raw:). The other case means
new server event types (tool calls, citations, agent steps) do not break old clients, but they are untyped: sources of
grounded chat answers arrive today as .other or inside AIMeta.raw and nothing decodes them.
SSE is used for the two AI routes only. There is no general event channel (no WebSocket, no SSE feed for sync or presence).
Error model (APIError.swift:30): offline, transport(URLError.Code), timeout, cancelled, invalidResponse, decoding(String), file(String), http(status:code:message:body:), conflict(server: PageConflict, message:), confirmExpensive(plan: RawJSON, message:). Stable codes in APIError.Code. Helpers: isRetryable (offline, transport,
timeout, 429, 408, 5xx, 409 in_progress; not not_configured/no_model), isConflict, needsReauth,
isUnauthenticated, isRateLimited, isOffline, isNotFound, serverCopy, plan. Descriptions never include request data.
HTTPClient does not retry by itself; retry policy lives in SyncEngine.
Server areas with no client — production route tree (M4M64c:~/apps/note-spboucher-ai/src/app/api) versus NotesAPI:
| Area | Routes on the server with no method in NotesAPI |
|---|---|
| Databases | /api/databases, /api/databases/templates, /api/databases/[id], …/properties, …/views, …/rows, …/rows/restore, …/query, …/import, …/duplicate, …/apply-template, …/ai |
| Graph | /api/graph, /api/graph/backlinks, /api/graph/neighbors, /api/graph/suggestions |
| Research | /api/research/overview, …/papers, …/references (+ [id], [id]/extracts, [id]/links, doi, import-bibtex, export.bib), …/experiments (+ [id]), …/tasks (+ [id]), …/ai |
| Agents and jobs | /api/agents, /api/agents/[id], /api/jobs |
| AI beyond action/chat | /api/ai/models, /api/ai/conversations, /api/ai/usage, /api/ai/chat/plan, /api/ai/compare, /api/ai/compare/vote |
| Search extras | /api/search/duplicates, /api/search/index-state |
| Dashboard | /api/dashboard, /api/dashboard/summary |
| Import / export | /api/import, /api/export |
| Settings | /api/settings, /api/settings/audit |
| Tree | /api/tree |
| Pages | /api/pages/[id]/beacon; list GET /api/pages |
| Auth | /api/auth/enroll/options, /api/auth/enroll/verify |
Covered by a client method but used by no macOS code: search, tasks/createTask/updateTask/deleteTask (the engine
uses the last three for reminders), inbox/triageInboxItem/undoInboxAction (engine only, for queued triage),
capture, tags, pageTags, attachments, duplicatePage, emptyTrash, authState, health, renamePasskey,
deletePasskey, revokeAllSessions.
The dev worktree M4M64c:~/dev/note-v2 additionally has /api/backups and has no /api/sync and no
apple-app-site-association route; production has both. The request and response shapes of the uncovered routes were
not read. [not verified]
A.4 SPNotesSync [code + doc]
One file, SyncEngine.swift (1 014 lines): public actor SyncEngine, SyncOptions (autoDownloadLimit 25 MiB,
includeDatabaseRows = false, feedPageSize = 200), SyncStatus, SyncOutcome, ConflictResolution,
AttachmentFileLocating, ContentDigest, QueuedTriage.
There is no general op journal. State-based sync with two mechanisms:
- Dirty flags on the page row for page state:
needs_create,dirty_content(title / content / properties, the version-guarded fields),dirty_meta(a set amongparentId, section, position, pinned, archived, icon, cover, inboxAt),tags_dirty, plusedit_seqincremented by every local change to push. The base copy inpage_basesis the last state common with the server. - The
opstable for actions that are not state:OpKind(Models.swift:395) =trash, restore, purge, deleteAttachment, createTask, updateTask, deleteTask, triage. A row isseq,kind(free string),target_id,payload(opaque BLOB; JSONQueuedTriagefor triage),idem_key(32 hex characters generated once),attempts,next_attempt_at,leased_until. The dispatch is theswitch op.kindatSyncEngine.swift:574-589; onlytrash, restore, purge, deleteAttachment, triageare handled. An unknown kind falls todefault: breakand is then completed, i.e. silently dropped (l.587-590).createTask/updateTask/deleteTaskare declared but not dispatched: reminders go throughpushReminders()(l.608) from thereminderstable.
Cycle (cycle(), l.179): up to 4 rounds of push then pull, then downloads.
- Push (
push(), l.263): creations, parents first (POST /api/pageswith the local id, then one unguarded PATCH andPUT tags); uploads (uploadPending, l.529); edits of known pages (sendChanges, l.385): unguarded fields and tags, then title/content/properties withbaseVersion; queue (runQueue, l.563); reminders (pushReminders, l.608). - Pull (
pull(), l.651):GET /api/sync?since=<cursor>untilmoreis false; each answer applied bystore.applyRemotein one transaction with its cursor. - Downloads (
downloadWanted, l.814): up to 40 files [doc].
Cursor: meta["sync.cursor"], an Int64 equal to the server rev, a single sequence bumped by database triggers on
every write. since=0 = full copy. reset: true → resetSyncState() and a full re-download, at most twice per cycle.
The feed must strictly advance while more.
Conflicts (reconcile, l.485): server copy equal to local → adopted; equal to what this device sent before a lost
answer (sync.sent.<pageId> fingerprint) → base moved; server older than the base → local sent again with a snapshot;
otherwise three-way merge (title, NoteDocument.merge, properties key by key); otherwise a conflicts row, local text
untouched, the page leaves the push list until resolveConflict(pageId:choice:) (keepMine | keepTheirs | keepBoth).
Flags, tags, moves, icon, cover, position are last-writer-wins.
Idempotency: page creation and upload rely on the client-chosen id and deliberately send no key; guarded PATCH on
baseVersion; ops on their stored key; task creation on spn-task-<reminder id>; resolution on a key built from page,
server version, choice and a fingerprint of the local text.
Entity kinds that flow
| Kind | Push | Pull |
|---|---|---|
| pages (notes, folders) | yes | yes |
| tags (per page, and the workspace tag list with colours) | yes | yes |
| attachments (metadata + bytes) | yes | yes |
tombstones (page, attachment) |
— | yes |
| trash / restore / purge / attachment deletion / inbox triage | yes (ops) | effects arrive as page changes |
| reminders → server tasks | yes | no — tasks created or changed on the web never come back |
| database row pages | no | filtered out at SyncEngine.swift:680 unless includeDatabaseRows |
| workspace name, user display name | — | yes, into meta |
| databases (schema, views, properties), graph edges, research, agents, AI conversations, settings | no | no |
The feed (SyncPage, PageModels.swift:24) carries pages, attachments, tombstones, tags only. Tombstone.kind is a
string; the engine maps it with SPNotesStore.Tombstone.Kind(rawValue:) and drops unknown kinds (l.682-685).
How to extend the engine to new entity kinds (database rows, tasks, graph edges, canvases)
The engine has no entity abstraction: no protocol, no registry. Each kind is hand-written across four layers. Per new kind:
- Server: add the kind to the
GET /api/syncpayload and to therevtriggers, with tombstones. SPNotesAPI/PageModels.swift:24SyncPage: a new optional array (decoding must tolerate its absence so old servers still work) and the DTO; endpoint methods inNotesAPI.SPNotesStore/Schema.swift:13: migrationv2(table withrev, dirty flags,edit_seq, optional base copy);Models.swift: record types, a newTombstone.Kind, a newStoreChangecase;NotesStore+Sync.swift: extendapplyRemote(…)andApplySummary, add…NeedingPush/mark…Pushed.SyncEngine.swift: a push phase inpush()(l.263), mapping inpull()(l.680-687), acaseinrunQueue()(l.574) for any new op kind, and the tombstone mapping (l.682).
Cheaper routes that avoid a new kind:
- Database rows are already pages (
database_id,type). SettingincludeDatabaseRows = truebrings rows into the existing page pipeline, with versionedpropertiesand the key-by-key merge. What is still missing is the database definition (properties, views), which has no feed entry and no table.NoteSession.isEditablein the macOS app currently makes such pages read-only. - Canvases, drawings, charts stored as page content (a node type) or as a page of a new
typeneed no engine change; only the 3-way merge granularity (whole top-level block) limits concurrent editing. - Graph edges are derivable from content (
pageReferences()exists); a locallinkstable filled by the store at write time would give offline backlinks without syncing anything. The store does not importSPNotesDocument, so the caller would have to supply the references, as it does for plain text. - Tasks: two models exist on the server — task items inside documents (
taskItemnodes, counted bytaskItems()) and/api/tasksrows. The store'sreminderstable is a push-only shadow of the second. Bidirectional tasks need the feed entry and an "apply remote reminder".
Known limits listed by the project [doc SYNC_ENGINE.md §6]: reminders push-only; moves are last-writer-wins and the
server does not check cycles; no compare-and-set on the conflict helpers; a restored server whose head has passed the
cursor is undetectable; 500 pages per round, 4 rounds per cycle; ops refused for good are retried forever; stop() reads
as .offline.
Doc inconsistency: SYNC_ENGINE.md §6 says a purged folder queues one op for the root only; STORE_API.md §2.2 and the
macOS 1.0.1 release notes say one op per page of the subtree. The second is the later text. [not verified in code]
A.5 Tests [declarations counted; nothing run]
| Target | Framework | Suites → declared tests |
|---|---|---|
SPNotesDocumentTests |
Swift Testing | Command 35, Model 22, Text 16, Merge 7, Dump 1 = 81 |
SPNotesStoreTests |
Swift Testing | Sync 15, Page 12, Engine 11, Search 6, QueueHistory 5 = 49 |
SPNotesAPITests |
XCTest | HTTPClient 22, ErrorAndModel 17, PasskeyAndAuth 15, RoutesAndMultipart 12, SSEAndAI 11, LiveBackend 11 = 88 |
SPNotesSyncTests |
Swift Testing | Fault 26, MergeConflict 16, TrashAttachmentQueue 14, SyncEngine 7, RandomConvergence 1, LiveSmoke 1 = 65 |
Total 283, matching the README. Fixtures: Tests/SPNotesDocumentTests/Fixtures/{rich,unknown,expected,md-samples, md-server,random-server}.json. Tests/SPNotesSyncTests/FakeBackend.swift (1 072 lines) is an in-memory backend written
from the server's route handlers; it will need every new route and feed field.
How they are run:
swift test # everything
SPN_ONLY=Document swift test --scratch-path .build-document
SPN_ONLY=Store swift test --scratch-path .build-store
SPN_ONLY=API swift test --scratch-path .build-api
SPN_ONLY=Sync swift test --scratch-path .build-syncEnvironment variables: SPN_ONLY; SPN_LIVE_URL + SPN_LIVE_TOKEN (live tests, skipped with XCTSkip when unset, and
any *.spboucher.ai host is refused); SPN_LIVE_TOKEN_DISPOSABLE, SPN_LIVE_TOKEN_DISPOSABLE2; SPN_RANDOM_SEEDS,
SPN_RANDOM_ONLY; SPN_DUMP. Live server = SSH tunnel to M4M64c:8482 (~/dev/note-native, database
note_native_dev), token minted by scripts/dev-session.ts on the node. swift test writes every emitted document to
/tmp/spn-docs.json for validation against the real web schema on M4M64c:~/dev/note-v2.
Flakiness: no test is marked flaky and no known-flaky note exists in the docs. Time- or environment-dependent items:
the live tests' "fresh" window (a dev token is fresh for 5 minutes; after that the purge and revocation tests assert
reauth_required instead), and the keychain test, which skips when no usable keychain exists. /tmp/spn-dev-token.txt
exists on this laptop from an earlier session (not opened).
B. macOS app (SP Notes 1.0.2, build 3)
44 Swift files, about 6 600 lines. project.yml (XcodeGen) + a local SwiftPM package for the editor.
B.1 Structure — every file
App/
| File | Lines | Role |
|---|---|---|
SPNotesApp.swift |
44 | @main; scenes: WindowGroup("SP Notes", id: "main"), WindowGroup("Note", id: "note", for: String.self), Settings, MenuBarExtra |
AppEnvironment.swift |
170 | LaunchOptions, Connectivity (NWPathMonitor), AttachmentFiles, AppEnvironment (the dependency container: HTTP, API, auth, store, sync, preferences, account, library, sync monitor, lock, note sessions) |
MainWindow.swift |
140 | WindowModel (per-window state), MainWindow (3-column NavigationSplitView), LockScreen, AppEnvironment.start() |
AppCommands.swift |
102 | the menu bar: File, Edit additions, Format, Insérer, Note, View additions, Synchronisation |
AppDelegate.swift |
206 | DeepLink, AppDelegate (URL open, Service, terminate flush), GlobalHotKey (Carbon), QuickNotePanel, QuickNoteModel, QuickNoteView |
SyncMonitor.swift |
133 | SyncMonitor (drives SyncEngine, 75 s timer), ToastCenter, ImageCache |
AppLock.swift |
40 | optional local lock through LocalAuthentication |
Preferences.swift |
64 | AppearanceMode, NoteSort, Preferences (16 UserDefaults keys) |
Components/
| File | Lines | Role |
|---|---|---|
DesignSystem.swift |
91 | Palette, Format, SyncDot, ToastOverlay, EmptyState, HighlightedText, onChangeAsync |
EditorController.swift |
62 | owns one NoteTextView + scroll view, implements NoteTextViewDelegate and AtomResources; NoteEditorView (NSViewRepresentable) |
Features/
| File | Lines | Role |
|---|---|---|
Account/AccountModel.swift |
101 | phases `local |
Account/AccountSheet.swift |
113 | sign-in, passkey list, session list, sync box, reauth button |
Account/WelcomeView.swift |
37 | first-launch screen |
AI/AssistantPanel.swift |
155 | AssistantModel + side panel |
Attachments/AttachmentService.swift |
133 | import and validation of files and images, Quick Look, save copy, disk usage, eviction |
History/HistoryAndConflicts.swift |
147 | HistorySheet (local + server versions), ConflictBanner, ConflictSheet |
Home/LibraryModel.swift |
191 | SidebarItem, FolderNode, LibraryModel (lists, folders, tags, search, all organisational actions) |
Home/SidebarView.swift |
119 | sidebar + SyncStatusBar |
Notes/NoteSession.swift |
156 | one open note: editor, title, autosave, snapshots, merge of remote changes |
Notes/NoteDetailView.swift |
287 | NoteDetailView, NoteEditorPane, Banner, FormatBar, StatusBar |
Notes/AtomEditors.swift |
220 | AtomEditorSheet, TableEditor, MathEditor, ImageDetails, FileDetails, UnknownBlock, LinkEditorSheet |
Notes/InspectorPanel.swift |
104 | tags, organisation, info, attachments, links; FlowLayout |
Notes/NoteListView.swift |
168 | middle column, NoteRow, SearchFilterBar |
Notes/Exporter.swift |
171 | export Markdown / text / HTML / RTF / PDF / ZIP, print, import |
Search/CommandPalette.swift |
114 | palette (⇧⌘P) and quick open (⌘O), AppActions |
Settings/SettingsView.swift |
116 | General, Editor, Sync, Security, Storage tabs |
Editor/ (SwiftPM target SPNotesEditor, AppKit only, depends on SPNotesDocument and SwiftMath 1.7.3)
| File | Lines | Role |
|---|---|---|
NoteTextView.swift |
642 | the NSTextView subclass on TextKit 2: load, serialize, applyRemote, incremental styling, the replace primitive, Return / Tab / Backspace, Markdown shortcuts, mouse handling |
EditorCommands.swift |
341 | BlockKind, SelectionState, block and mark commands, atom insertion, Markdown insertion |
DocumentCodec.swift |
151 | NoteDocument ⇄ NSAttributedString |
EditorAttributes.swift |
162 | .spPara, .spMarks, .spDecoration, ParaStyle, MarkSet, ParaDecoration, EditorTheme, KeyAllocator |
Styler.swift |
185 | fonts, colours, indents, decorations for the touched paragraphs |
BlockLayoutFragment.swift |
100 | NSTextLayoutFragment subclass drawing markers, quote bars, panels |
AtomAttachment.swift |
267 | NodeBox, AtomResources, AtomAttachment, AtomRenderer |
Completion.swift |
215 | "/" and "@" menus, CompletionPanel, EditorImages |
NoteFragment.swift |
158 | pasteboard: private structured type, RTF, plain text, foreign rich text |
SyntaxHighlighter.swift |
119 | hand-written tokenizer, about 20 language families |
ExportComposer.swift |
96 | attributed string for RTF / PDF / print |
MathRenderer.swift |
46 | SwiftMath typesetting with a cache |
Tests/: EditorTests/EditorTests.swift (288, SwiftPM), EditorTests/SnapshotSupport.swift, AppTests/EndToEndTests.swift
(305, hosted), UITests/SPNotesUITests.swift (45).
B.2 Editor architecture [code]
Storage ⇄ model mapping. The text view's NSTextStorage is the live model; NoteDocument exists only at load and at
save. Conventions (DocumentCodec.swift:7-12):
- every line ends with
\n, the last included; the newline carries the paragraph attributes; .spPara→ aParaStyleobject (EditorAttributes.swift:18) = theLinewithout its content (template), so unknown node keys survive; the paragraphs of one code block share the same instance (identity is the block);.spMarks→ aMarkSetof rawPMMark, unknown marks included;- a block atom = a paragraph made of one
U+FFFCattachment character carrying anAtomAttachment; - an inline atom = one attachment character; a
hardBreak=U+2028tagged.spInlineNodewith aNodeBox; .spDecoration→ParaDecoration, derived, never serialized.
DocumentCodec.attributedString(from:) (l.23) and DocumentCodec.lines(from:in:) (l.70) are the two directions. Save:
NoteSession.saveNow → editor.document() → jsonData() → ContentDigest → store.updateContent. So every autosave
(350 ms after the last keystroke) re-serializes the whole document; measured 32 ms for 4 000 blocks [doc TEST_REPORT.md].
Styling. NSTextStorageDelegate.textStorage(_:didProcessEditing:…) (NoteTextView.swift:202) calls
Styler.affectedRange then Styler.style, which restyles the edited paragraphs widened to their top-level structure.
Styler.apply (Styler.swift:73) walks ParaStyle.path and switches on the container type (l.79-110).
How each block type is rendered
| Node | Rendering | Where |
|---|---|---|
| paragraph, heading 1-3, footnote | fonts / sizes from EditorTheme |
Styler.swift:134-154 |
| marks bold, italic, underline, strike, code, highlight, sub, superscript, link | attributes | Styler.swift:135-153 |
| codeBlock | monospaced font, panel, token colours | Styler.swift:114-117, highlightCode l.158, panel in BlockLayoutFragment.draw |
| bulletList / orderedList / taskList | indent + marker (bullet(level), number, checkbox) drawn by the layout fragment |
Styler.swift:86-108, BlockLayoutFragment.swift:70-90 |
| blockquote | bars | Styler.swift:80, fragment |
| callout | tinted panel + icon | Styler.swift:81, fragment |
| aiBlock | tinted panel | Styler.swift:83, fragment |
| details | disclosure marker on the summary, content indented; no collapse — open is ignored |
Styler.swift:85, 113 |
| table | bitmap of the grid | AtomRenderer.table, AtomAttachment.swift:246 |
| image | bitmap, max width 720; placeholder card when the file is not local | picture, l.143 |
| blockMath / inlineMath | SwiftMath bitmap; fallback = source text | l.158, l.173 |
| fileBlock, youtube | a generic "card" bitmap (symbol + title + subtitle) | l.106-107 |
| mention, footnoteRef | "pill" bitmap | l.108, l.110 |
| horizontalRule | 1-pt line bitmap | l.137 |
| unknown block | card "Bloc « type » — Conservé tel quel — modifiable sur le site web" | l.112 |
| unknown inline | pill ⟨type⟩ |
l.113 |
Atoms are static images. AtomAttachment is an NSTextAttachment whose image is produced by AtomRenderer into a
2× NSBitmapImageRep and cached per (width, dark). There is no NSTextAttachmentViewProvider, no live subview, no
in-place interaction: a table cannot be edited in the text, an image cannot be resized, a video does not play. Interaction
is double-click → noteDelegate.noteTextView(_:activate:at:) → EditorController.activeAtom → a SwiftUI sheet
(AtomEditorSheet, AtomEditors.swift:22 switch atom.node.type). The bitmap scale is hard-coded to 2 (l.120).
Commands and toolbar. Everything goes through NoteTextView.replace(_:with:select:actionName:)
(NoteTextView.swift:239) or restyleParagraphs (l.256): one undo step each, with the view's own UndoManager.
EditorCommands.swift: setBlock(_:toggle:) (l.51) over BlockKind (paragraph, heading(Int), code, bullet, ordered(start:), task, quote, callout), indent, outdent, moveBlock(up:), toggleMark, clearFormatting,
setLink, insertBlockAtom (l.239), insertInlineAtom (l.258), replaceAtom (l.267), insertRule, insertTable,
insertBlockMath, insertInlineMath, insertMention, insertImage, insertFile, insert(_ doc:), insertMarkdown,
selectedMarkdown. The SwiftUI FormatBar (NoteDetailView.swift:196) and AppCommands call these directly and read
EditorController.selection: SelectionState. The same command list is written three times: AppCommands.swift,
FormatBar, and the palette in CommandPalette.swift.
Slash and mention menus. Completion.swift: builtinSlashItems() (l.17) returns 14 static entries (text, h1-h3,
bullet, ordered, todo, quote, callout, divider, code, table, math, inline math); the app appends its own through
NoteTextViewDelegate.noteTextView(_:completionsFor:query:) — NoteEditorPane.slashItems() (NoteDetailView.swift:128:
image, file, link to a note, new sub-note, ask the assistant) and mentionItems(_:) (l.139: local FTS quickFind, plus
"create the note"). The menu is a borderless non-key NSPanel (CompletionPanel, l.102) with AppKit rows.
Markdown shortcuts at the start of a line: NoteTextView.applyMarkdownShortcut (l.396).
Exactly where to add rendering for a new atom or block type
For a new atom (block or inline) — the minimum, three places:
Editor/AtomAttachment.swift:100AtomRenderer.image(for:isBlock:width:)— acase "<type>":returning an image (reusecard,pill, or write a drawer liketable).Features/Notes/AtomEditors.swift:22AtomEditorSheet.content— acase "<type>":with its SwiftUI editor.- Insertion: a method next to
EditorCommands.swift:282-290built oninsertBlockAtom/insertInlineAtom; an entry inCompletion.swift:19(built-in) orNoteDetailView.swift:129(needs app services); menu items inAppCommands.swift:68andFormatBar(NoteDetailView.swift:232); the palette.
Plus, when relevant: NoteTextView.idTypes (NoteTextView.swift:346) if the node takes an id; ExportComposer.swift:52
(switch for RTF / PDF / print text fallbacks); AtomAttachment.rendered l.50 (the "do not cache a placeholder" rule is
written for image only — any atom whose rendering depends on an asynchronous resource needs the same);
AtomRenderer.inlineDescent (l.95) for inline atoms with a baseline.
For a new container (e.g. aiResult): Styler.swift:79 switch c.type (indent + deco.panel),
EditorAttributes.swift:80 ParaDecoration.Panel (new case), BlockLayoutFragment.swift:44 (panel colour switch),
EditorTheme (colour), EditorCommands.swift:124 toggleWrapper, BlockKind (l.7) and selectionState (l.27),
NoteTextView.lifted (l.549) for leaving the container.
For a new text block like runnableCode: ParaStyle.isCode (EditorAttributes.swift:39) is tested throughout
NoteTextView (Return, Tab, Backspace, codeBlockRange), DocumentCodec (line joining, l.89), Styler and
Completion. A second code-like type means generalising isCode.
For anything interactive in place (a chart that responds, a query view that scrolls, a drawing, a PDF page, a Mermaid
diagram that re-renders, a runnable cell with output): the bitmap model is the wall. It needs
NSTextAttachmentViewProvider (hosting an NSView / NSHostingView) or overlay views positioned from layout fragments.
Neither exists in the codebase; AtomAttachment overrides the image and bounds methods only.
B.3 Design [code]
Tokens that exist
Components/DesignSystem.swift:7enum Palette:amber = Color("AccentColor"),subtle = Color.primary.opacity(0.06),tag(_:)mapping seven colour names to system colours. That is the whole SwiftUI palette.Resources/Assets.xcassets/AccentColor.colorset: light sRGB (0.890, 0.520, 0.040), dark (1.000, 0.690, 0.200). The catalog holdsAccentColorandAppIcononly.Editor/EditorAttributes.swift:99EditorTheme:fontSize15,fontDesign(system | serif | rounded | monospaced),lineSpacing3,indentWidth26; heading scale 1.75 / 1.4 / 1.18; code font 0.9×; static dynamicNSColorsaccent(a second, slightly different amber: light (0.80, 0.45, 0.02)),link,codeBackground,inlineCodeBackground,highlight,quoteBar,calloutBackground,aiBackground;tokenColor(_:)for syntax.Preferences:fontSize(12-22 through the menu),fontDesign,columnWidth780.
What does not exist: no spacing scale, no radius scale, no typography scale for the chrome, no elevation or material
tokens, no semantic colour roles, no shared button / field / card styles. Spacing and radii are literals in the views
(padding(12), padding(18), cornerRadius: 5/6/7/8/9, widths 270 / 330 / 560). Fonts are SwiftUI text styles or
literals (.system(size: 26, weight: .bold) for the title). Editor metrics are literals in Styler (18, 38, 12) and in
BlockLayoutFragment.
Appearance: AppearanceMode (system | light | dark) applied with .preferredColorScheme on the main window and
Settings. Editor colours are dynamic NSColor(name:) providers. NoteTextView.viewDidChangeEffectiveAppearance (l.191)
→ refreshAtoms() invalidates the atom bitmaps. .tint(Palette.amber). Materials used: .ultraThinMaterial (lock),
.regularMaterial (welcome, quick note, toast), .bar (status bar), NSVisualEffectView.material = .menu (completion).
No increase-contrast or differentiate-without-colour handling (grep: no hit).
Animations (complete list, by grep): .transition(.opacity) on the welcome view, the palette and the filter bar;
toast .transition(.move(edge: .bottom).combined(with: .opacity)) with .animation(.spring(duration: 0.3));
$showFilters.animation(); .symbolEffect(.pulse) on the sync icon. Nothing else: no withAnimation, no
matchedGeometryEffect, no animated panel open/close (assistant and inspector appear by if).
Reduced motion: not handled. No accessibilityReduceMotion, no NSWorkspace.accessibilityDisplayShouldReduceMotion.
Language: every user-facing string is a French literal in the Swift source. developmentLanguage: fr; no string catalog
or .strings file is present in Resources/.
B.4 Navigation and windows [code]
- Scenes (
SPNotesApp.swift): mainWindowGroup(default 1180×760), a secondWindowGroupkeyed by note id (980×720) that reuses the sameMainWindowview,Settings,MenuBarExtra(off by default; three items: quick note, open, quit). MainWindow: oneNavigationSplitViewwith three columns —SidebarView(190-320),NoteListView(240-460),NoteDetailView. The navigation model isLibraryModel.selection: SidebarItem(list(SmartList) | section(String) | folder(String) | tag(String) | unsynced) plusWindowModel.selectedNotes. The detail column can only show a note editor or an empty state: there is no router and no notion of a non-note destination (database, graph, tasks, home, search results page).LibraryModel.selectionlives in the sharedLibraryModel, so the sidebar selection is shared by every window, while the note selection is per window.- Sidebar sections: Bibliothèque (all, recent, favourites, pinned, inbox when not empty, unsynced when not empty),
Espaces (
notes, documents, projects, research— the server'sdatabasessection is not listed), Dossiers (OutlineGroup), Tags, then archives and trash;SyncStatusBarat the bottom. - Inspector and assistant: not the SwiftUI
.inspectormodifier. Both are fixed-width columns (270 and 330) appended in anHStackinside the detail pane (NoteDetailView.swift:46-47), not resizable. - Sheets: account, atom editors, link editor, history, conflict. Overlays in a
ZStack: lock screen, welcome, command palette, toasts. - Quick note:
QuickNotePanel, a floating non-activatingNSPanelhosting SwiftUI with a plainTextEditor(not the note editor); first line = title; global hot key ⌃⌥⌘N registered through CarbonRegisterEventHotKey(no permission needed), on by default. - Commands: see B.1; shortcuts include ⌘N, ⇧⌘N, ⌥⌘N, ⌘O, ⇧⌘P, ⌘S (snapshot), ⇧⌘I (import), ⌘P, ⌥⌘F, ⌘K, ⌥⌘0-3, ⇧⌘7/8/9, ⌘]/[, ⌃⌘↑/↓, ⌥⌘I (inspector), ⇧⌘A (assistant), ⌘R (sync), ⌃⌘L (lock), ⌘+/−.
- Deep links (
AppDelegate.swift:10):spnotes://note/<uuid>(or/p/),spnotes://new?text=…. Nothing else. No universal links (the entitlement haswebcredentials:only, noapplinks:). - Services: one, "Nouvelle note SP Notes avec la sélection" (
NSServicesinInfo.plist,newNoteFromSelection). - File open:
application(_:open:)imports file URLs throughExporter.importFiles. No document types are declared inInfo.plist, so the Finder does not offer the app for any file type. - Window tabbing allowed; secure restorable state on; a 900 ms launch guard reopens a main window when restoration brought none.
- Quit:
applicationShouldTerminateflushes every session and checkpoints the database before replying.
B.5 AI features [code]
- Endpoints used:
POST /api/ai/actionandPOST /api/ai/chatonly (AssistantPanel.swift:31, 39). - UI: one side panel (
AssistantPanel, 330 pt, ⇧⌘A or the toolbar sparkle, hidden whenpreferences.aiEnabledis off). Quick action buttons (a static list ofAIActionKindvalues: summarize, rewrite, fix, shorten, …), a Translate menu with six languages, a free instruction field (.custom), then a question field with a three-way scope picker mapped toAIChatMode: "Cette note" →.summarise, "Toutes mes notes" →.notes, "Général" →.general. - Input is the selection or the whole note converted to Markdown (
selectedMarkdown()), cut to 120 000 characters. - Output: streamed plain
Text(Markdown is not rendered in the panel), with model name and cost. Actions on the result: replace the selection, insert after / into the note (insertMarkdown, one undo step), copy, new note, ignore. Nothing is written without a click. confirm_expensivehandled both as a thrown error and as a stream event.- Absent: conversation history (each question is a single turn;
conversationIdis never sent, only a freshclientId), model picker (AIActionRequest.model/AIChatRequest.modelnever set;/api/ai/modelshas no client), citations and sources display, usage view, compare, chat plan, agents, AI over a database, research AI, inline AI in the text (no "continue writing" at the caret, no AI block insertion —aiBlockis rendered but nothing native creates one).
B.6 Account and passkeys [code]
- Flow:
WelcomeView(first launch) orAccountSheet→AccountModel.signIn()→AuthService.signIn()→loginOptions→ system passkey sheet (ASAuthorizationController) →loginVerify→ the session cookie value is stored byHTTPClientin the keychain. Phases:local(fully usable without an account),signedIn,expired(a session ended by the server never erases anything). Store meta keys:account.everSignedIn,account.displayName. - Keychain (
AppEnvironment.swift:119):KeychainTokenStore(configuration:, service: (bundleIdentifier ?? "ai.spboucher.spnotes") + ".session", useDataProtectionKeychain: false), account = the server origin, no access group passed. So the session token lives in the legacy file-based login keychain, not the data-protection keychain, and thekeychain-access-groupsentitlement is unused. A share extension or widget could not read the token as things stand. In-memory store for tests, UI tests and injected dev sessions. - Entitlements, Release (
Resources/SPNotes.entitlements): app sandbox,network.client,files.user-selected.read-write,print,com.apple.developer.associated-domains=webcredentials:note.spboucher.ai, application identifier3YM54G49SN.ai.spboucher.spnotes, team3YM54G49SN, keychain access group3YM54G49SN.ai.spboucher.spnotes. Debug (SPNotes-Debug.entitlements): sandbox, network client, user-selected files, print — no associated domain, so passkeys cannot work in a Debug build; Debug uses a session minted on the dev server. - Not in the entitlements: app groups, iCloud, push (
aps-environment), camera, microphone, calendars,applinks. - The server's AASA lists
3YM54G49SN.ai.spboucher.spnotes(macOS) and…spnotes.ios[docBACKEND_CONTRACT.md]. The Debug bundle idai.spboucher.spnotes.debugis deliberately different so a dev copy never shadows the installed app. WelcomeView.isInstalledwarns when the app does not run from/Applications/.- Device management UI (
AccountSheet): list of passkeys (label, "synchronisée"), "add a passkey on this Mac" (auth.addPasskey(label: "Mac · SP Notes")), list of sessions with "Déconnecter" per other session (withFreshSession { revokeSession }), "confirm with my passkey" when a purge waits (stepUp), sign-out with the choice to keep or erase the local copy. Rename and delete of a passkey, and "revoke all sessions", have API methods but no UI (the passkey row shows label, "synchronisée" and last use only). - Local lock (
AppLock): Touch ID or the Mac password, on launch and/or after N minutes; a screen lock, not encryption.
B.7 Build, release, tests [code + doc]
project.yml
- Deployment target macOS 15.0;
SWIFT_VERSION6.0;SWIFT_STRICT_CONCURRENCY: complete; hardened runtime; team3YM54G49SN. MARKETING_VERSION1.0.2,CURRENT_PROJECT_VERSION3.- App target
SPNotes: sourcesApp,Features,Components,Resources; product name "SP Notes"; moduleSPNotes; bundle idai.spboucher.spnotes(Debug:ai.spboucher.spnotes.debug);SWIFT_DEFAULT_ACTOR_ISOLATION: MainActorandSWIFT_APPROACHABLE_CONCURRENCY: YES(app target only). - Release: manual signing, identity "Developer ID Application", profile specifier "SP Notes Developer ID",
--timestamp, whole-module, universal. Debug: ad hoc (-), automatic. SPNotesTests(hosted unit tests,Tests/AppTests, bundle id…spnotes.tests),SPNotesUITests(Tests/UITests,…spnotes.uitests, hardened runtime off).- Schemes
SPNotes(build, test =SPNotesTests, archive = Release) andSPNotesUITests. - Packages:
../SPNotesCore(productSPNotesCore) and.(productSPNotesEditor); the editor package pins SwiftMathexact: "1.7.3"from GitHub — the only third-party dependency.
Scripts/
| Script | What it does | Needs |
|---|---|---|
| `build.sh generate | debug | core-test |
integration-test.sh [--server] |
hosted tests; with --server also the end-to-end sync tests |
--server: SSH to M4M64c; passes TEST_RUNNER_SPNOTES_IT_SERVER / TEST_RUNNER_SPNOTES_IT_TOKEN |
dev-session.sh |
opens the tunnel to the dev backend and mints a session; prints export SPNOTES_SERVER=… SPNOTES_SESSION_TOKEN=… |
DEV_NODE (M4M64c), DEV_DIR (dev/note-native), DEV_PORT (8482) |
run-dev.sh [--local] [--shot …] |
launches the Debug build against the dev backend in the background; uses pkill -f on the Debug app path and open |
a Debug build; APP optional |
shot.sh, window-shot.swift |
captures the app window to a PNG | — |
release.sh |
finds the "Developer ID Application" identity in the keychain, installs Build/SPNotes_Developer_ID.provisionprofile, xcodegen, archive Release, copies dist/SP Notes.app |
the identity; the profile file |
verify-release.sh [app] |
checks signature, hardened runtime, timestamp, sandbox, associated domain, no debug entitlement, embedded profile, no WebKit / JavaScriptCore linked, no HTML / JS / CSS resource, no secret patterns | — |
notarize.sh |
notarizes and staples the app, builds / signs / notarizes / staples the DMG, writes the SHA-256 | NOTARY_PROFILE (default MacLustr-Notarize) |
provision.py, asc.py |
registers the bundle id, the Associated Domains capability and the Developer ID profile through the App Store Connect API | ASC_KEY_ID, ASC_ISSUER_ID, ASC_KEY_PATH (falls back to values read from maclustr-ios-v2/app/scripts/testflight-archive-upload.sh) |
make-icon.sh |
SVG → AppIcon set, light and dark | rsvg-convert |
check-headers.sh |
fails when a source file lacks the author header | git |
verify-release.sh fails the release if a web engine is linked or any HTML/JS/CSS file is in the bundle. Rendering
Mermaid, charts or other content through WKWebView breaks this gate; the choice is native renderers or a deliberate
change of that policy.
release.sh mixes build/ and Build/ paths (the same directory on a case-insensitive volume).
Distribution: DMGs in dist/ (1.0.0, 1.0.1, 1.0.2). No auto-update: SPNotesUpdateFeedURL is empty; Sparkle 2 is the
stated plan [doc UPDATES.md].
Tests [declarations counted; none run]
| Suite | Count | How |
|---|---|---|
Editor (Tests/EditorTests, SwiftPM) |
30 declared (docs say 31 including the offscreen render) | swift test / Scripts/build.sh core-test |
App, hosted (Tests/AppTests/EndToEndTests.swift) |
13 (7 without server, 6 with) | Scripts/integration-test.sh [--server]; env SPNOTES_IT_SERVER, SPNOTES_IT_TOKEN |
UI (Tests/UITests) |
2 | Scripts/build.sh ui-test |
Launch arguments honoured by the app: -SPNotesDataDir, -SPNotesInMemory; DEBUG only: -SPNotesServer /
SPNOTES_SERVER (loopback hosts only), SPNOTES_SESSION_TOKEN, -SPNotesUITest, -SPNotesOffline, -SPNotesOpen,
-SPNotesRoute (assistant | inspector | palette | account), -SPNotesNoActivate.
TEST_REPORT.md (1.0.2, 2026-11-18) — verified [doc]: editor codec round trip on all schema types, typing,
commands, undo, remote apply, pasteboard, completion; a 4 000-block document (load 95 ms, 3.3 ms per keystroke,
serialize 32 ms); hosted tests: autosave, crash safety, organisation, local history, exports, two windows on one note,
5 000-note library (lists 2-3 ms, FTS 4-5 ms); with the dev server: the offline scenario end to end, remote change into
an open editor, merge and conflict on two devices, image upload, trash both ways, "Résumer" streamed; release checks and
notarization (Accepted for app and DMG).
TEST_REPORT.md — NOT verified [doc]: passkey sign-in in the signed app (Touch ID sheet, domain association);
a real reboot and a physical network cut; the XCUITests were written and compiled but never executed; all mouse
interactions (checkbox click, double-click on a table, file drag and drop); window restoration, full screen, multiple
windows on screen; quick note hot key, the Service, spnotes:// links, the menu bar extra, Quick Look, printing, the
share sheet, the Touch ID lock; assistant actions other than "Résumer" and all questions; server history in the app;
passkey and device lists; a purge pushed to the server; VoiceOver; any other Mac, Intel, macOS 15 or 26 (the x86_64 slice
never ran); Instruments.
So the passkey sign-in — the only way into sync in a release build — has never been confirmed in the shipped app by the project's own account.
B.8 Absent natively vs the web — confirmed against code
| Capability | In the macOS code? | Evidence |
|---|---|---|
| Databases (tables, views, properties, rows) | No. Database pages show a read-only banner | NoteSession.swift:37, NoteDetailView.swift:90; rows filtered by the engine; databases section not in the sidebar; no API client |
| Graph view, graph API | No | no client; no view |
| Backlinks | No. The inspector lists outgoing links only, computed locally from document().pageReferences() (first 12), although its file header says "to and from" |
InspectorPanel.swift:83; no backlink in the app; PageDetail.backlinks from GET /api/pages/{id} is never requested |
| Tasks view | No. Task lists render and toggle inside a note; no cross-note task list | no use of api.tasks; no reminder call in the app |
| Reminders | No UI. The store table and the engine push exist; the app never creates one | grep reminder in App / Features / Components: no hit |
| Inbox triage | No. The inbox is a smart list shown when non-empty; no keep / task / archive actions, no undo | SidebarView.swift:22; no triage / enqueueOp in the app |
Capture (/api/capture) |
No | quick note creates an ordinary page |
| Research (references, papers, experiments, BibTeX) | No | "Recherche" is only a page section |
| Semantic / hybrid search | No. Local FTS5 only | api.search never called |
| AI: model choice, conversations, usage, compare, agents, jobs | No | B.5 |
| Dashboard / home | No | — |
| Canvas / whiteboard | No | — |
| Drawing | No native drawing. A PencilKit drawing from iOS is an image node + .pkdrawing attachment and shows as a picture |
data convention in BACKEND_CONTRACT.md |
| Voice notes, dictation capture, audio | No | no AVFoundation / Speech import; no microphone entitlement |
| PDF viewing in place, PDF annotation | No. PDFs are file cards opened in Quick Look | no PDFKit import |
| Mermaid, charts, runnable code, citations, block references, query views | No | A.1; shown as unknown-block cards if the web produced them |
| Spotlight indexing | No | no CoreSpotlight import |
| Notifications | No | no UserNotifications import, no push entitlement |
| App Intents / Shortcuts, widgets, share extension | No | no AppIntents / WidgetKit import; no extension target in project.yml |
Handoff / NSUserActivity |
No | grep |
| Universal links | No | webcredentials only |
| Auto-update | No | UPDATES.md |
| In-place table editing, image resize, video playback, collapsible details | No | B.2 |
| Drag handle per block | No (keyboard move ⌃⌘↑/↓ only) | ARCHITECTURE.md §5 |
| Real-time collaboration / presence | No | no socket; 75 s polling + 2 s debounce |
| Localisation other than French | No | B.3 |
| Server-side import/export, settings, audit | No | export and import are local (Exporter.swift) |
What it does have that is worth keeping: full offline use with no account, durable autosave, local + server history, conflict UI, attachments with keep-offline and eviction, six export formats and print, command palette, quick note, local lock, multi-window with shared sessions.
B.9 Code smells and risks for a large upgrade
Architecture
- Three implementations of the editing logic. Core has
Commands.swift+InlineCommands.swift(744 lines, tested by 35 command tests). The macOS editor does not call them:Editor/EditorCommands.swiftandNoteTextView.swiftre-implement lists, indent, split, merge, marks and links directly onNSTextStorage. The iOS app (../SPNotes-iOS/Editor/, 9 files, 2 237 lines:AttributedCodec,EditorStyler,EditorLayoutFragment,AtomRenderer,StructureCommands, …) is a separate editor that does call Core's commands (grep hits inStructureCommands.swift,NoteTextView.swift,NoteEditorModel.swift). Every new block type must therefore be implemented in Core, in the macOS editor and in the iOS editor, with three renderers.Package.swiftof the editor declaresplatforms: [.macOS(.v15)]and imports AppKit throughout, so it cannot be shared as it is. - Duplicated schema knowledge in the macOS editor:
NoteTextView.idTypesandidAlphabet/newBlockID()(l.344-346) copySchema.idTypesandBlockID.generate()becauseSchemaisinternalto Core;Styler.listTypes/itemTypescopySchema.lists/items; node type names are string literals everywhere inEditor/andFeatures/instead ofNodeType.*. A type added to the server'sID_TYPESmust be changed in two Swift places. - Atoms are bitmaps (B.2). This is the largest single constraint on mermaid / chart / pdf / drawing / queryView / runnable code.
verify-release.shforbids web engines (B.7), which removes the cheapest way around item 3.- Navigation cannot express non-note destinations (B.4), and the sidebar selection is global across windows.
- The sync engine has no extension seam (A.4): one 1 014-line actor, hand-written per kind; unknown op kinds are dropped as completed and unknown tombstone kinds are ignored, so a client older than the server loses those silently.
- Store schema is at version 1: the migration path has one step and has never been exercised on shipped data.
A newer file is refused by an older build, so a downgrade after the upgrade means the old app will not open the store
(
AppEnvironment.swift:130-131then falls back to an in-memory store and recordsstoreOpenError).storeOpenErroris read by no view (grep: declared and assigned only; the failure goes toNSLog). The user would see an empty library, and anything typed would be lost at quit. This path needs a blocking error screen before any schema migration ships. - Whole-document serialization on every autosave and whole-block merge granularity: fine for prose, costly and conflict-prone for large structured blocks (a big table or a canvas is one block and one JSON value).
- No design system (B.3): a redesign starts from literals in about 20 view files, plus a separate set of colours and metrics inside the editor package.
Concurrency (Swift 6, strict)
- The app target compiles with
SWIFT_DEFAULT_ACTOR_ISOLATION: MainActor; the editor package does not and is annotated by hand (@MainActoronDocumentCodec,Styler,AtomRenderer, …). Code moved between the two changes isolation silently.Editor/types referenceSPNotesDocumentvalue types only, which keeps this manageable. - Escape hatches, counted over App / Features / Components / Editor:
nonisolated(unsafe)15,@unchecked Sendable6 (ParaStyle,MarkSet,ParaDecoration,NodeBox,AtomAttachment,KeyAllocator),MainActor.assumeIsolated9. They cluster where AppKit calls back fromnonisolatedrequirements: the fourNSTextAttachmentoverrides (AtomAttachment.swift:54-86),textStorage(_:didProcessEditing:)andtextLayoutManager(_:textLayoutFragmentFor:)(NoteTextView.swift:202, 224), the Quick Look data source, the Carbon hot key.assumeIsolatedtraps if TextKit ever calls these off the main thread (background layout, printing, or a view provider on another queue). Moving to view-based attachments adds more of these callbacks. AppDelegate.environmentis a static mutable set fromSPNotesApp.init;MainWindowOpener.openandOpenNoteWindow.openare static closures captured from whichever window appeared last;ImageCache.sharedandQuickLook.sharedare singletons holding an environment-dependent state. Fragile with several windows and in tests.GlobalHotKey.actionsis anonisolated(unsafe)static dictionary mutated frominitand from aDispatchQueue.main.asyncindeinit.- Unstructured tasks: 110
Task {occurrences, most fire-and-forget from button closures with no cancellation or ordering;NoteSession.saveNowhandles re-entrancy with a 30 ms sleep-and-retry (NoteSession.swift:83-85). NoteSession.storeChanged()runs on store change events whilesaveNowmay be in flight; correctness rests onlastSavedContentcomparisons and theisApplyingflag rather than on a serial queue.
Error handling and robustness
- 99
try?in the app code: store and network failures in the library, inspector, account and settings paths are dropped without a message (e.g.loadSecurity()shows empty lists on any error). AppEnvironment.initusestry! NotesStore.inMemory()as the fallback when the on-disk store cannot be opened.ASPresentationAnchorFallback.windowcreates a bareNSWindowas the passkey anchor when no window is visible.Scripts/run-dev.shusespkill -f(it targets the local Debug app path on the laptop; still worth knowing given the standing rule againstpkill -fon shared nodes).
Code shape
- No file is large (the biggest are
NoteTextView.swift642 andEditorCommands.swift341), but the code is horizontally dense: 208 lines longer than 200 characters, the longest 769; many functions are a single line with several statements separated by;. Worst files:NoteDetailView.swift(19 such lines),AssistantPanel.swift(17),AccountSheet.swift(15),SyntaxHighlighter.swift(15),NoteTextView.swift(13). Diffs and reviews on these are harder than the line counts suggest. NoteDetailView.swiftholds five views (pane, banner, format bar, status bar, plus an extension onNoteTextView);AppDelegate.swiftholds six types;SyncMonitor.swiftalso holdsToastCenterandImageCache.- Duplicates inside the app:
activateAtomBeforeCaret()(Completion.swift:38) andactivateInsertedAtom()(NoteDetailView.swift:281) are the same function; the "Untitled → Sans titre" rule is repeated in at least six places; the command list exists in three places (B.2). ParaDecoration.isEqual(l.91) ignoresstruck, andhashuses onlymarkerXandquoteBars.count.- Dead or odd code noticed:
insertBlockAtomhaslet path = style.isCode ? style.path : style.path;TableEditorends with.disabled(!editable && false);textStorage(_:didProcessEditing:)contains an emptyifbody where the "last paragraph is terminated" invariant was meant to be enforced. - Tests do not cover the UI layer: 2 UI tests, never executed; no snapshot tests of the SwiftUI chrome (only the editor has an offscreen render).
Product and ops
- Min OS macOS 15 while development and all testing happened on macOS 27 only; iOS 18 for Core.
- One language, hard-coded.
- No telemetry, crash reporting or structured logging: grep for Sentry, Crashlytics, MetricKit,
OSLog,Logger(returns nothing; the only log call seen is oneNSLog. Fine for privacy, but there is no field signal after a risky migration. - Documentation drift inside Core (A.4) and a stale hard-coded user agent in
Scripts/dev-session.sh(SPNotes/1.0.0).
Appendix — things I did not verify
- No build, no test run, no app launch. All performance numbers and "green" statements are the projects' own.
- Request / response shapes of the server routes that have no native client (only the route tree was listed).
HTMLExport.swiftdefault branch body;MarkdownImport.swiftin full;Commands.swiftin full (signatures only);NotesStore+*.swiftbodies (schema and docs read, method bodies spot-checked);SyncEngine.swiftl.179-560 and l.740-1014 (outlined, withrunQueue,pushRemindersandpullread in full).- In the app: the tails of lines longer than 230 characters were cut in my reading (the three that mattered were re-read:
AppEnvironment.swift:119,AccountSheet.swift:60,InspectorPanel.swift:83).InspectorPanel,NoteListView,Exporter,SettingsView,HistoryAndConflicts,CommandPalette,AttachmentService,LibraryModelwere read as outlines (declarations and key lines), not line by line. docs/AUDIT.md,SECURITY.md,INSTALL.mdof the macOS app were not read.FEATURE_MATRIX.mdwas skipped as you have it.- The iOS project was only listed and grepped, to establish the editor duplication.