SPNotesFeatures — hosting the feature screens
SPNotesFeatures is the SwiftUI library of the SP Note Next Generation screens shared by SP Notes macOS (15+) and
iOS / iPadOS (18+). It depends on SPNotesDesign, SPNotesSync (repositories), SPNotesStore, SPNotesAPI,
SPNotesDocument; it uses SwiftUI, Swift Charts, PDFKit, AVFoundation and CryptoKit — no WebKit, no JavaScriptCore
(a test greps the sources). It is not re-exported by the SPNotesCore umbrella.
| Product | Link it in | Contains |
|---|---|---|
SPNotesFeatures |
the app targets | every screen, view model and block view below |
SPNotesFeaturesCatalog |
debug / test targets only (it links the fake backend) | FeatureCatalogView, FeatureWorld, FeatureSamples |
import SPNotesFeatures
TasksScreen(repositories: repos, router: router) // the screen creates and owns its model
TasksScreen(model: tasksModel) // or the app owns the model (state restoration, tests)1. The contract with the host
1.1 FeatureRouter
@MainActor public protocol FeatureRouter: AnyObject {
func openPage(id: String, blockId: String?) // scroll to and flash the node whose `id` attr is blockId
func openDatabase(id: String) // database id or host page id
func openCanvas(pageId: String)
func openURL(_ url: URL)
func presentError(_ error: Error) // rare: the screens show their own banners
}The models hold the router weakly: the app keeps it alive (one per window / scene). FeatureRouterRecorder is a
recording implementation for previews and tests. A screen never navigates outside its own surface by itself.
1.2 Layout
Every screen has two real designs. iOS follows the horizontal size class; macOS switches to compact under 560 pt of
width. Force one with .featureSizeClass(.compact | .regular). On compact, details open as sheets: host the
screen where a sheet can be presented. On regular they are side inspectors. Screens draw their own title row; put
them in your navigation container without a second large title.
1.3 Loading, offline, errors
Each model exposes phase: LoadPhase, freshness: Freshness? and actionFailure: FeatureFailure?, and starts
loading in .task when phase == .idle. A cached read model is shown with « Copie de l'appareil · Mis à jour … »;
offline is a calm banner, never an endless spinner; an online-only write that fails changes nothing locally and
nothing is queued (as the repositories do). Tasks and canvases are editable offline.
1.4 AI
Anything produced by a model is inside FeatureAICard / next to NVAIBadge. Nothing paid is requested without a
user action (ask, brief summary, synopsis, Smart Inbox suggestions, AI insights, semantic search, transcription),
and nothing is applied without one.
1.5 Strings
French is the source (L("…"), the key is the text). English: Localization/en/*.json, compiled into
Sources/SPNotesFeatures/Resources/Localizable.xcstrings by python3 Scripts/build-string-catalog.py (--check in
the tests). SPN_FEATURES_LANG=fr|en forces a language; test runners default to French.
2. Screens
| Screen | Entry point | Host supplies / notes |
|---|---|---|
TasksScreen |
(repositories:router:pageId:) |
pageId = tasks of one page. Public TaskDetailView. Offline-first. |
InboxScreen |
(repositories:router:) |
Public InboxDetailView. Smart Inbox suggestions are an explicit, paid request. |
DatabaseScreen |
(repositories:databaseId:router:) |
Database id or host page id. Public DatabaseRowEditor, DatabaseBuilderView. |
UnifiedSearchScreen |
(repositories:router:) |
Semantic search only on the explicit toggle + submit. |
GraphScreen |
(repositories:router:view:pageId:) |
view = a GraphView constant; local / project need pageId. iOS: the relation form is a sheet. |
ConstellationScreen |
(repositories:router:) |
Server projection when /api/meta lists constellation, else a labelled local layout. |
TimelineScreen |
(repositories:router:scope:) |
`scope: .workspace |
KnowledgeHealthScreen |
(repositories:router:) |
|
DailyBriefScreen |
(repositories:router:) |
A summary the server already stored is shown (AI card); a new one only on tap. |
SemanticZoomControl + PageOutlineView |
SemanticZoomControl(level:onChange:), PageOutlineView(model:) { editor } |
Level 3 is the host's editor view; the host keeps the scroll anchor. |
AskScreen |
(repositories:router:context:) |
AskContext(pageId:pageTitle:projectId:projectTitle:selection:selectionBlockId:) enables the page / project / selection scopes. |
ModelPickerView |
(repositories:selectedId:onSelect:) |
Write onSelect: explicitly (the init ends with defaulted closures). "Auto" = nil. |
ResearchScreen |
(repositories:router:scope:) |
`.library |
CanvasScreen |
(repositories:pageId:router:attachments:drawingEditor:) |
See §3 for the loader and the PencilKit hook. |
CommandCenterView |
(registry:onDismiss:) |
See §4. |
Block detail views (atom sheets / inspectors of both editors). Each takes the typed block of SPNotesDocument and
returns the edited block through a callback; the editor writes the node and saves the page — the views never do.
| View | Entry point | Notes |
|---|---|---|
MermaidBlockView |
(block:imageLoader:onChange:) |
Preview shown only when previewHash == sha256(code); otherwise the source and « rendu à mettre à jour depuis le Web ». |
DrawingBlockViewer, InkEditorView |
see MediaBlocks/InkViews.swift |
Mouse / trackpad / touch editor producing spn-ink-1; InkDrawingExport.store uploads ink + preview and clears pk. iOS apps plug PencilKit instead. |
ChartBlockView |
(block:repositories:onChange:) |
Live data when source is set and repositories is given; the node's snapshot is rewritten only on « Mettre à jour l'instantané ». |
QueryViewBlockView |
(repositories:router:block:hostPageId:) |
Resolved through POST /api/query; cached result offline. |
BlockRefView |
(repositories:router:block:) |
Rendered from the local copy of the source page; « Référence introuvable » when missing. |
CitationPickerView |
(repositories:pageId:current:onPick:) |
Returns CitationChoice(refId, label, locator) → attrs of the citation node. |
BibliographyView |
(repositories:router:citedIds:style:title:) |
Pass document.citedReferences(). APA only; another style is shown in APA with a notice. |
PDFBlockView |
see MediaBlocks/PDFBlockView.swift |
PDFKit. Annotations ⇄ normalised rects (PDFPageGeometry, tested on rotated pages). page is committed on disappear. |
RunCodeBlockView |
(block:onChange:) |
Code + last output; says that execution happens on the web. |
AudioBlockView |
AudioBlockView(model: AudioBlockModel(repositories:block:pageId:files:…)) |
See §5. |
3. Attachments and the PencilKit hook
Files belong to the host (sync engine + file locator). Give the views a loader:
let loader = FeatureAttachmentLoader.standard(repositories: repos, files: appFileLocator)
CanvasScreen(repositories: repos, pageId: id, router: router, attachments: loader, drawingEditor: pencilEditor)
PDFBlockView(…).featureAttachmentLoader(loader) // also DrawingBlockViewerMermaidBlockView takes a BlockImageLoader closure (attachment id → Data) and the audio view an
AudioFileProvider (attachment id → local file URL): wrap the same locator. Uploads are online-only.
drawingEditor: CanvasDrawingEditorProvider? — a closure receiving a CanvasDrawingEditRequest (node, ink
attachment, current InkDocument, size) and returning a CanvasDrawingEditResult?. The iOS app presents its
PencilKit editor there and returns the new ink; without it the built-in InkEditorView opens.
4. Command center
let registry = CommandRegistry() // one per app
let token = registry.register(owner: "editor", [FeatureCommand(id: "page.new", title: "Nouvelle page", section: "Pages", action: { … })])
registry.unregister(token) // or unregister(owner:)
CommandCenterView(registry: registry, onDismiss: { showPalette = false })The app owns the shortcut (⌘K) and the presentation (overlay / sheet / panel). The matcher is a port of the web
palette's scoring, diacritic-insensitive. FeatureCommands.standard(router:…) registers only what Features can do
by itself; recents persist through UserDefaultsCommandRecents.
5. Info.plist usage strings and entitlements
| Needed by | Key | Platforms |
|---|---|---|
AudioBlockView recording |
NSMicrophoneUsageDescription |
iOS, macOS |
AudioBlockView recording |
entitlement com.apple.security.device.audio-input (App Sandbox / Hardened Runtime) |
macOS |
Nothing else: the Speech framework is not used (transcription is the server's, through AudioRepository), no
background-audio mode is requested (recording stops with the view), PDFKit / Charts need no key. The audio view
shows an explained state when the permission is denied.
6. Tests and the gallery
swift test --filter SPNotesFeaturesTests— view-model tests of every screen overFakeBackend(FeatureWorld), geometry tests, and hosted renders written to/tmp/spnote-next/shots-native/<screen>-<light|dark>-<compact|regular>.png(SPN_SHOTS_DIRoverrides). The renders use an off-screenNSHostingView(never a visible window);Scripts/features-contact-sheet.pybuilds contact sheets.- Live smoke (integration server only, never production):
SPN_LIVE_URL=http://localhost:8486 SPN_LIVE_TOKEN=… swift test --filter LiveFeatures. FeatureCatalogView()(productSPNotesFeaturesCatalog) lists every screen over the fake backend with switches for offline, compact and dark. Host it in a DEBUG-only window / route; do not ship it.Scripts/generate-model-logos.shregeneratesResources/ModelLogos.xcassetsfrom the webpublic/model-logos/(simple-icons, CC0; marks remain trademarks of their owners).
7. Known limits (2.0.0)
Verified by model tests, hosted renders and an iOS Simulator compile only: no screen was driven by real pointer, touch or keyboard input, and nothing was run on a device.
- Graph: no concept create / rename / delete UI; no scroll-wheel zoom on macOS (buttons, pinch, drag).
- Database: board cards move through a menu (no drag and drop); gallery has no cover images; relation / file / AI
cells are read-only; no column resize / reorder, no property rename / delete; a draft filter preview queries the
API directly without
viewId. - Search: tag and folder filters exist in the model, not in the UI.
- Ask: stopping mid-stream is implemented but not covered by a test; citations of stored conversations are numbered
only when the server stored
n. - Research: experiments and papers are read-only; no reference extracts, PDF attachment or LaTeX zip.
- Canvas:
mathcards show the LaTeX source; no snap guides, align / distribute or copy / paste; a viewport change alone is not saved (as on the web). - PDF: the interactive
PDFView(live selection, ink) has not been exercised on screen; the renders use a static page picture. - Bibliography: APA only. Constellation: the server route exists only on servers that list the feature.
- Time machine: page and project scopes only (the API has no workspace scope).