SPB Git

Repository Public

FEATURES.md 11.9 KB 180 lines markdown

1<!--2SP Notes Core3File: docs/FEATURES.md4Description: How an app hosts the cross-platform feature screens of SPNotesFeatures (SPEC §8): products, the FeatureRouter,5             each screen's entry point, loaders and hooks, Info.plist strings and entitlements, tests, known limits.6Author: Simon-Pierre Boucher7Contact: contact@spboucher.ai8-->910# SPNotesFeatures — hosting the feature screens1112`SPNotesFeatures` is the SwiftUI library of the SP Note Next Generation screens shared by SP Notes macOS (15+) and13iOS / iPadOS (18+). It depends on `SPNotesDesign`, `SPNotesSync` (repositories), `SPNotesStore`, `SPNotesAPI`,14`SPNotesDocument`; it uses SwiftUI, Swift Charts, PDFKit, AVFoundation and CryptoKit — **no WebKit, no JavaScriptCore**15(a test greps the sources). It is not re-exported by the `SPNotesCore` umbrella.1617| Product | Link it in | Contains |18|---|---|---|19| `SPNotesFeatures` | the app targets | every screen, view model and block view below |20| `SPNotesFeaturesCatalog` | debug / test targets only (it links the fake backend) | `FeatureCatalogView`, `FeatureWorld`, `FeatureSamples` |2122```swift23import SPNotesFeatures2425TasksScreen(repositories: repos, router: router)          // the screen creates and owns its model26TasksScreen(model: tasksModel)                            // or the app owns the model (state restoration, tests)27```2829## 1. The contract with the host3031### 1.1 `FeatureRouter`3233```swift34@MainActor public protocol FeatureRouter: AnyObject {35    func openPage(id: String, blockId: String?)   // scroll to and flash the node whose `id` attr is blockId36    func openDatabase(id: String)                 // database id or host page id37    func openCanvas(pageId: String)38    func openURL(_ url: URL)39    func presentError(_ error: Error)             // rare: the screens show their own banners40}41```4243The models hold the router **weakly**: the app keeps it alive (one per window / scene). `FeatureRouterRecorder` is a44recording implementation for previews and tests. A screen never navigates outside its own surface by itself.4546### 1.2 Layout4748Every screen has two real designs. iOS follows the horizontal size class; macOS switches to compact under 560 pt of49width. Force one with `.featureSizeClass(.compact | .regular)`. On compact, details open as **sheets**: host the50screen where a sheet can be presented. On regular they are side inspectors. Screens draw their own title row; put51them in your navigation container without a second large title.5253### 1.3 Loading, offline, errors5455Each model exposes `phase: LoadPhase`, `freshness: Freshness?` and `actionFailure: FeatureFailure?`, and starts56loading in `.task` when `phase == .idle`. A cached read model is shown with « Copie de l'appareil · Mis à jour … »;57offline is a calm banner, never an endless spinner; an online-only write that fails changes nothing locally and58nothing is queued (as the repositories do). Tasks and canvases are editable offline.5960### 1.4 AI6162Anything produced by a model is inside `FeatureAICard` / next to `NVAIBadge`. Nothing paid is requested without a63user action (ask, brief summary, synopsis, Smart Inbox suggestions, AI insights, semantic search, transcription),64and nothing is applied without one.6566### 1.5 Strings6768French is the source (`L("…")`, the key is the text). English: `Localization/en/*.json`, compiled into69`Sources/SPNotesFeatures/Resources/Localizable.xcstrings` by `python3 Scripts/build-string-catalog.py` (`--check` in70the tests). `SPN_FEATURES_LANG=fr|en` forces a language; test runners default to French.7172## 2. Screens7374| Screen | Entry point | Host supplies / notes |75|---|---|---|76| `TasksScreen` | `(repositories:router:pageId:)` | `pageId` = tasks of one page. Public `TaskDetailView`. Offline-first. |77| `InboxScreen` | `(repositories:router:)` | Public `InboxDetailView`. Smart Inbox suggestions are an explicit, paid request. |78| `DatabaseScreen` | `(repositories:databaseId:router:)` | Database id or host page id. Public `DatabaseRowEditor`, `DatabaseBuilderView`. |79| `UnifiedSearchScreen` | `(repositories:router:)` | Semantic search only on the explicit toggle + submit. |80| `GraphScreen` | `(repositories:router:view:pageId:)` | `view` = a `GraphView` constant; `local` / `project` need `pageId`. iOS: the relation form is a sheet. |81| `ConstellationScreen` | `(repositories:router:)` | Server projection when `/api/meta` lists `constellation`, else a labelled local layout. |82| `TimelineScreen` | `(repositories:router:scope:)` | `scope: .workspace | .page(id) | .project(id)`; page / project scopes add the time machine. `TimeMachineView(model:)` also stands alone. |83| `KnowledgeHealthScreen` | `(repositories:router:)` | |84| `DailyBriefScreen` | `(repositories:router:)` | A summary the server already stored is shown (AI card); a new one only on tap. |85| `SemanticZoomControl` + `PageOutlineView` | `SemanticZoomControl(level:onChange:)`, `PageOutlineView(model:) { editor }` | Level 3 is the host's editor view; the host keeps the scroll anchor. |86| `AskScreen` | `(repositories:router:context:)` | `AskContext(pageId:pageTitle:projectId:projectTitle:selection:selectionBlockId:)` enables the page / project / selection scopes. |87| `ModelPickerView` | `(repositories:selectedId:onSelect:)` | Write `onSelect:` explicitly (the init ends with defaulted closures). "Auto" = nil. |88| `ResearchScreen` | `(repositories:router:scope:)` | `.library | .page(id) | .project(id)`; LaTeX export only for a project. Exports through `ShareLink`. |89| `CanvasScreen` | `(repositories:pageId:router:attachments:drawingEditor:)` | See §3 for the loader and the PencilKit hook. |90| `CommandCenterView` | `(registry:onDismiss:)` | See §4. |9192Block detail views (atom sheets / inspectors of both editors). Each takes the typed block of `SPNotesDocument` and93returns the edited block through a callback; **the editor writes the node and saves the page** — the views never do.9495| View | Entry point | Notes |96|---|---|---|97| `MermaidBlockView` | `(block:imageLoader:onChange:)` | Preview shown only when `previewHash == sha256(code)`; otherwise the source and « rendu à mettre à jour depuis le Web ». |98| `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. |99| `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é ». |100| `QueryViewBlockView` | `(repositories:router:block:hostPageId:)` | Resolved through `POST /api/query`; cached result offline. |101| `BlockRefView` | `(repositories:router:block:)` | Rendered from the local copy of the source page; « Référence introuvable » when missing. |102| `CitationPickerView` | `(repositories:pageId:current:onPick:)` | Returns `CitationChoice(refId, label, locator)` → attrs of the `citation` node. |103| `BibliographyView` | `(repositories:router:citedIds:style:title:)` | Pass `document.citedReferences()`. APA only; another `style` is shown in APA with a notice. |104| `PDFBlockView` | see `MediaBlocks/PDFBlockView.swift` | PDFKit. Annotations ⇄ normalised rects (`PDFPageGeometry`, tested on rotated pages). `page` is committed on disappear. |105| `RunCodeBlockView` | `(block:onChange:)` | Code + last output; says that execution happens on the web. |106| `AudioBlockView` | `AudioBlockView(model: AudioBlockModel(repositories:block:pageId:files:…))` | See §5. |107108## 3. Attachments and the PencilKit hook109110Files belong to the host (sync engine + file locator). Give the views a loader:111112```swift113let loader = FeatureAttachmentLoader.standard(repositories: repos, files: appFileLocator)114CanvasScreen(repositories: repos, pageId: id, router: router, attachments: loader, drawingEditor: pencilEditor)115PDFBlockView(…).featureAttachmentLoader(loader)        // also DrawingBlockViewer116```117118`MermaidBlockView` takes a `BlockImageLoader` closure (attachment id → `Data`) and the audio view an119`AudioFileProvider` (attachment id → local file URL): wrap the same locator. Uploads are online-only.120121`drawingEditor: CanvasDrawingEditorProvider?` — a closure receiving a `CanvasDrawingEditRequest` (node, ink122attachment, current `InkDocument`, size) and returning a `CanvasDrawingEditResult?`. The iOS app presents its123PencilKit editor there and returns the new ink; without it the built-in `InkEditorView` opens.124125## 4. Command center126127```swift128let registry = CommandRegistry()                                   // one per app129let token = registry.register(owner: "editor", [FeatureCommand(id: "page.new", title: "Nouvelle page", section: "Pages", action: { … })])130registry.unregister(token)                                         // or unregister(owner:)131CommandCenterView(registry: registry, onDismiss: { showPalette = false })132```133134The app owns the shortcut (⌘K) and the presentation (overlay / sheet / panel). The matcher is a port of the web135palette's scoring, diacritic-insensitive. `FeatureCommands.standard(router:…)` registers only what Features can do136by itself; recents persist through `UserDefaultsCommandRecents`.137138## 5. Info.plist usage strings and entitlements139140| Needed by | Key | Platforms |141|---|---|---|142| `AudioBlockView` recording | `NSMicrophoneUsageDescription` | iOS, macOS |143| `AudioBlockView` recording | entitlement `com.apple.security.device.audio-input` (App Sandbox / Hardened Runtime) | macOS |144145Nothing else: the Speech framework is not used (transcription is the server's, through `AudioRepository`), no146background-audio mode is requested (recording stops with the view), PDFKit / Charts need no key. The audio view147shows an explained state when the permission is denied.148149## 6. Tests and the gallery150151- `swift test --filter SPNotesFeaturesTests` — view-model tests of every screen over `FakeBackend` (`FeatureWorld`),152  geometry tests, and hosted renders written to `/tmp/spnote-next/shots-native/<screen>-<light|dark>-<compact|regular>.png`153  (`SPN_SHOTS_DIR` overrides). The renders use an off-screen `NSHostingView` (never a visible window);154  `Scripts/features-contact-sheet.py` builds contact sheets.155- Live smoke (integration server only, never production): `SPN_LIVE_URL=http://localhost:8486 SPN_LIVE_TOKEN=… swift test --filter LiveFeatures`.156- `FeatureCatalogView()` (product `SPNotesFeaturesCatalog`) lists every screen over the fake backend with switches for157  offline, compact and dark. Host it in a DEBUG-only window / route; do not ship it.158- `Scripts/generate-model-logos.sh` regenerates `Resources/ModelLogos.xcassets` from the web `public/model-logos/`159  (simple-icons, CC0; marks remain trademarks of their owners).160161## 7. Known limits (2.0.0)162163Verified by model tests, hosted renders and an iOS Simulator **compile** only: no screen was driven by real pointer,164touch or keyboard input, and nothing was run on a device.165166- Graph: no concept create / rename / delete UI; no scroll-wheel zoom on macOS (buttons, pinch, drag).167- Database: board cards move through a menu (no drag and drop); gallery has no cover images; relation / file / AI168  cells are read-only; no column resize / reorder, no property rename / delete; a draft filter preview queries the169  API directly without `viewId`.170- Search: tag and folder filters exist in the model, not in the UI.171- Ask: stopping mid-stream is implemented but not covered by a test; citations of stored conversations are numbered172  only when the server stored `n`.173- Research: experiments and papers are read-only; no reference extracts, PDF attachment or LaTeX zip.174- Canvas: `math` cards show the LaTeX source; no snap guides, align / distribute or copy / paste; a viewport change175  alone is not saved (as on the web).176- PDF: the interactive `PDFView` (live selection, ink) has not been exercised on screen; the renders use a static177  page picture.178- Bibliography: APA only. Constellation: the server route exists only on servers that list the feature.179- Time machine: page and project scopes only (the API has no workspace scope).180
Files main
Menu

Theme