SPB Git

Repository Public

ARCHITECTURE-NEXT.md 25.7 KB 318 lines markdown

1# SP Note Next Generation — architecture (ARCHITECTURE-NEXT)23> Status 2026-11-20: this is the cross-platform contract the upgrade was built against (web/backend 3.0.0 in4> production; SPNotesCore 2.0; SP Notes macOS 2.0.0 and iOS/iPadOS 2.0.0 on their `next` branches). Sections 0–65> are the original specification; §7 records the decisions taken during the work and supersedes earlier text where6> they differ; §8 is the native architecture. Exact request/response shapes: `API-NEXT.md`, `API-NEXT-AI.md`.7> Node behaviour on the web: `EDITOR-NODES.md`. Canvas semantics: `CANVAS.md`. Tokens and motion:8> `DESIGN-SYSTEM-NEXT.md`. Offline web: `OFFLINE-WEB.md`. Databases: `DATABASES-NEXT.md`.910## Overview1112```13              ┌──────────────────────── one backend (M4M64c) ────────────────────────┐14 Web (Next.js, Tiptap) ─┐   Next.js route handlers ── service layer ── PostgreSQL 17 + pgvector15 macOS (SwiftUI/AppKit) ─┼─► /api/* (session cookie + Origin)   │        ├─ pages (ProseMirror JSON), versions16 iOS/iPadOS (SwiftUI)  ─┘   /api/sync?kinds= change feed (rev)   │        ├─ entity feed: tasks, databases, edges,17                             /api/meta feature gating             │        │   references, canvases, concepts18                                                                  │        ├─ knowledge_events (journal)19        pg-boss worker: index, import, backup, agents, AI         │        └─ AI catalogue, usage, synopses, transcripts20        properties, graph insights, transcription ◄───────────────┘21 Providers (server side only): OpenAI, Anthropic, any OpenAI-compatible (OpenRouter, MacLustr local) — keys in .env22```2324Native stack: `SPNotesCore` package = `SPNotesDocument` (lossless ProseMirror model, typed 3.0 nodes, ink,25canvas, merge) · `SPNotesStore` (SQLite v2: pages, FTS, entities cache, outboxes, canvases, events) ·26`SPNotesAPI` (typed client for every route) · `SPNotesSync` (engine + repositories) · `SPNotesDesign`27(tokens, motion) · `SPNotesFeatures` (cross-platform SwiftUI screens). The two apps own their shells, their28TextKit 2 editors and platform integration. No WebView, no JavaScript engine in the native apps.2930Document rule: ProseMirror JSON stays canonical. New blocks are leaf atoms whose data is in attributes and31attachments; every client preserves what it does not know, byte for byte.3233Sync rule: pages, attachments, tasks and canvases are editable offline (journal/outbox, stable client ids,34versioned saves, 3-way merge per block / per canvas element, explicit conflicts). Databases, graph, research35and server-computed read models are readable offline from the last copy and written online. The server is the36shared source of truth after synchronisation; unsent local changes are always kept.3738This file is the contract between every workstream (backend, web, SPNotesCore, macOS, iOS/iPadOS).39It is a MAJOR UPGRADE of working, deployed software. If something here conflicts with what the code can40safely do, stop and report rather than improvise a different contract: four codebases implement it.4142Audits (read the one for your codebase before coding): `/tmp/spnote-next/audit-web.md`,43`/tmp/spnote-next/audit-core-macos.md`, `/tmp/spnote-next/audit-ios.md`.4445## 0. Rules for every workstream46471. Never touch production: `M4M64c:~/apps/note-spboucher-ai`, PM2 `note-web`/`note-worker`, database48   `note_spboucher`, https://note.spboucher.ai. Backend/web work happens in a git worktree under49   `M4M64c:~/dev/` against a scratch database whose name ends in `_dev`. Deployment is done later by the lead.502. Never `pkill -f`/`killall` on a node (shared machine): kill by PID of the port you own.513. On the laptop never run `open`, never launch an app window that can take focus (the owner is working).52   Use the projects' own background recipes (`Scripts/run-dev.sh --shot`, hosted tests, simulators by UDID).53   Use a dedicated simulator per UI-test suite (create one named after your workstream if needed).544. No WebView / WebKit / JavaScriptCore in the native apps (macOS `Scripts/verify-release.sh` enforces it).555. No existing feature removed, no existing node/attr renamed, no destructive migration. Every SQL migration56   is additive and has a hand-written `.down.sql`. Unknown content must round-trip untouched everywhere.576. Nothing is "done" without a test that ran. Report honestly: verified / implemented-unverified / not done.58   Never fabricate AI output, citations, benchmark numbers or test results. No mock presented as a feature.597. Secrets stay in `.env` on the node / Keychain on devices. Never print or commit them.608. Keep each project's conventions (file header with file/description/author/contact, French UI strings as61   the source language, existing lint/typecheck). Commit on your branch with clear messages; do not push to62   `main`, do not merge, do not tag, do not release. End commit messages with63   `Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>`.649. Respect Reduce Motion (web `prefers-reduced-motion`, Apple `accessibilityReduceMotion`) for every animation.6510. AI-generated content (summaries, suggested links, suggested tags…) is always visibly marked as such and66    is never applied without an explicit user action; agent writes go through the existing proposal/approval model.6768## 1. Versions6970Web/backend 3.0.0 · SPNotesCore 2.0.0 · SP Notes macOS 2.0.0 · SP Notes iOS/iPadOS 2.0.0.71`GET /api/meta` (authenticated) → `{ "api": 3, "version": "3.0.0", "features": ["entities","events","canvas",…] }`.72Clients gate new UI on `features`. Existing routes keep their paths and shapes (shipped 1.x natives use them).7374## 2. Document format — new nodes (ProseMirror JSON stays canonical)7576All existing nodes/marks are unchanged (see audit-web §3.3). New nodes are **block-level leaf atoms**77(no `content`), carry the usual block `id` attr, and keep all their data in `attrs`. Binary data is never78inline: it is an attachment referenced by id (`/api/files/<id>`). A client that does not know a node keeps it79verbatim and shows a neutral read-only card (never plain-text conversion, never deletion).8081| type | attrs (defaults) | notes |82|---|---|---|83| `mermaid` | `code:""`, `preview:null` (attachment id of an SVG or PNG render), `previewHash:null` (sha256 hex of `code` the render was made from) | Web renders with the `mermaid` library and uploads the render when it changes. Natives show the render if `previewHash` matches the sha256 of `code`, else show the source with a « rendu à mettre à jour depuis le Web » notice; natives can edit `code`. |84| `drawing` | `ink:null` (attachment id, JSON `spn-ink-1`), `preview:null` (attachment id PNG), `pk:null` (attachment id of native PKDrawing data, optional), `width:0`, `height:0`, `background:"none"` | `spn-ink-1` = `{"format":"spn-ink-1","width":W,"height":H,"strokes":[{"tool":"pen|marker|highlighter","color":"#rrggbbaa","width":n,"points":[[x,y,pressure 0..1],…]}]}` (points in canvas units). Every editor writes `ink` + `preview`. iOS also writes `pk`; an editor that changes `ink` without PencilKit sets `pk:null`. |85| `chart` | `kind:"bar"` (`bar|line|area|pie|scatter`), `title:""`, `columns:[]` (strings), `rows:[]` (arrays of string|number|null), `x:null` (column name), `y:[]` (column names), `source:null` (`{databaseId, viewId?}` → data read live from a database; `columns/rows` then hold the last snapshot) | Web: SVG renderer. Natives: Swift Charts. |86| `queryView` | `source:"tasks"` (`tasks|pages|database|references|backlinks`), `databaseId:null`, `viewId:null`, `filter:{}` (`{tag?, section?, status?, parentId?, text?, dueBefore?, dueAfter?}`), `layout:"list"` (`list|table|board`), `limit:25`, `title:""` | "Living document" block: resolved at display time through `POST /api/query` (§4.7). |87| `citation` (**inline** atom) | `refId:null` (research reference uuid), `locator:""`, `label:""` (cached "Author Year") | |88| `bibliography` | `style:"apa"`, `title:"Références"` | Lists the references cited in the page (computed). |89| `pdf` | `attachmentId:null`, `name:""`, `page:1`, `annotations:[]` | annotation = `{id, page, kind:"highlight|note|ink", color:"#rrggbb", rects:[[x,y,w,h]…] (0..1, origin top-left of the page), text:"", note:"", ink:[[x,y]…]?, createdAt}` |90| `blockRef` | `pageId:null`, `blockId:null`, `mode:"embed"` (`embed|link`) | Cross-reference / transclusion, rendered read-only from the source block. A missing target shows « Référence introuvable ». |91| `runCode` | `language:"javascript"`, `code:""`, `output:null` (`{text, error:bool, ms, at}`) | Executed only on explicit click, on the web, inside a sandboxed iframe (`sandbox="allow-scripts"`, opaque origin, no network through CSP). Natives show code + last output and can edit `code`; they do not execute (no JS engine allowed). |92| `audio` | `attachmentId:null`, `duration:0`, `title:""`, `recordedAt:null`, `transcript:[]` (`[{t:seconds, text}]`), `transcriptStatus:"none"` (`none|pending|done|failed`), `transcriptEngine:null`, `summary:null` (`{text, decisions:[], tasks:[], model, at}`) | Voice note. |93| `canvasLink` | `pageId:null` | Card that opens a canvas page (§3.4). |9495Existing nodes extended (new **optional** attrs, default null, old clients keep them):96`taskItem`: `due` (ISO date), `priority` (`low|medium|high`), `taskId` (uuid of the linked `tasks` row).97`aiBlock`: `sources` (`[{pageId, blockId, title}]`), `action` (string). `callout.kind` gains `decision`, `question`, `hypothesis`.98`listItem`/`taskItem` now receive a block `id` (fixes citations into lists).99100Text/Markdown/HTML export of new nodes (must be byte-identical between server `src/lib/editor/text.ts` and101Core `MarkdownExport`): mermaid → fenced ```` ```mermaid ```` block; runCode → fenced block with its language,102then a fenced `output` block when present; chart → `title` line + Markdown table of columns/rows;103drawing → `![Dessin](/api/files/<preview>)` (or `[Dessin]`); pdf → `[PDF: name](/api/files/<id>)` then one104`> p.<page> — <text> — <note>` line per annotation; audio → `[Audio: title](/api/files/<id>)` then the105transcript lines `[mm:ss] text`; queryView → `[Vue: title]`; blockRef → `[[<pageId>#<blockId>]]`;106citation → `[@<label or refId>]`; bibliography → `## <title>`; canvasLink → `[Canvas](/p/<pageId>)`.107Plain text (search index, word count): the same without Markdown syntax; transcript and annotation text ARE indexed.108109## 3. Backend data model additions (migrations 0003+; all additive)110111### 3.1 Entity change feed112`rev` + the existing `sync_bump_rev` / `sync_tombstone` trigger mechanism is extended to:113`tasks`, `databases`, `database_properties`, `database_views`, `database_rows`, `knowledge_edges`,114`references`, `canvases`, `concepts`. `GET /api/sync` accepts `kinds=task,database,database_property,115database_view,database_row,edge,reference,canvas,concept` (comma list). Without `kinds` the answer is116byte-compatible with 2.x. With it, the answer adds `"entities": { "<kind>": [ {…row…, "rev": n} ] }`117windowed exactly like pages (same cursor rules), and tombstones of those kinds. Writes stay on REST routes;118every create route of these kinds accepts a client-chosen uuid `id` and is idempotent on it.119120### 3.2 Events journal — `knowledge_events`121`id, workspace_id, at, kind, page_id?, entity_kind?, entity_id?, actor ('user'|'agent'|'ai'|'system'), device?, summary, data jsonb`.122Written in the service layer (same transaction as the mutation) for: `page.created|renamed|edited|moved|archived|123unarchived|trashed|restored|purged`, `page.version` (snapshot taken), `tag.added|removed`, `link.added|removed`,124`relation.created|accepted|rejected|removed`, `reference.added|linked`, `attachment.added`, `task.created|completed|reopened`,125`capture.created|filed`, `ai.applied` (an AI result inserted by the user), `agent.applied`, `decision.recorded`126(callout kind `decision` added), `canvas.edited`. `page.edited` is coalesced (at most one per page per 10 min).127Only real events are shown anywhere; nothing is back-filled except `page.created` from `pages.created_at` and128`page.version` from existing `page_versions` (flagged `data.backfilled = true`).129130### 3.3 Knowledge graph 2.0131`knowledge_edges` gains: `rel_type` (`related|supports|contradicts|extends|example_of|part_of|cites|precedes|132follows|about|answers|duplicates`), `origin` (`user|ai|system`), `note`, `valid_from`, `valid_to`,133`source_kind`/`target_kind` (`page|reference|concept`), `source_block_id`, `target_block_id`, `decided_at`.134Existing rows keep their meaning (`kind` link/ai_suggested). AI-created edges are always `status='suggested'`,135`origin='ai'` until the user accepts. New `concepts (id, workspace_id, name, description, origin, status, rev)`136and `page_concepts (page_id, concept_id, origin, status, confidence)`.137`knowledge_insights (id, kind 'contradiction|open_question|cluster|recurring_topic|duplicate', status138'suggested|accepted|dismissed', title, detail, data jsonb{pageIds, blockIds, …}, model, created_at)`.139140### 3.4 Canvas141A canvas is a page with `type='canvas'` (empty ProseMirror doc as `content`) plus one row in142`canvases (page_id PK, data jsonb, version int, rev, updated_at)`.143`data = {"format":"spn-canvas-1","nodes":[{id, kind:"text|page|image|pdf|link|drawing|shape|reference|math|table",144x,y,w,h,z, text?, pageId?, attachmentId?, url?, refId?, latex?, color?, shape?:"rect|ellipse|diamond", ink?: attachment id}],145"edges":[{id, from, to, label?, kind?:"arrow|line", color?}], "viewport":{x,y,zoom}}`.146`GET /api/canvases/<pageId>` · `PUT /api/canvases/<pageId>` `{data, baseVersion}` → 200 `{version}` | 409 with the147server copy (same optimistic model as pages; clients merge by node/edge id when both sides changed different ids).148149### 3.5 AI providers150`ai_providers` gains `kind` (`openai|anthropic|openai_compatible`), `base_url`, `key_env` (NAME of the env var),151`label`. Seeded rows: `openai`, `anthropic` (unchanged), `openrouter` (`https://openrouter.ai/api/v1`,152`OPENROUTER_API_KEY`), `maclustr` (`https://llm.spboucher.ai/v1`, `MACLUSTR_LLM_API_KEY`). A provider with no153key in the environment is listed as unavailable and never routed to. `ai_models` gains `creator` (anthropic,154openai, google, meta, mistral, qwen/alibaba, deepseek, xai, …), `route` (= provider id), `context_window`,155`price_in`, `price_out`, `capabilities jsonb`. The measured routing table is NOT changed: new-provider models156are selectable manually and enter automatic routing only after `pnpm bench:run` covers them.157158## 4. New / changed HTTP API (all under the existing auth: session cookie + Origin on mutations)159160Exact request/response shapes are written by the backend workstream in `docs/next/API-NEXT.md`161(in the web repo) — that file is the reference for the native clients. Planned surface:1621634.1 `GET /api/meta` · `GET /api/sync?kinds=` (§3.1)1644.2 Tasks: `GET/POST /api/tasks` (client `id`, `due`, `priority`, `pageId`, `blockId`), `PATCH/DELETE /api/tasks/<id>`.1654.3 Graph: `GET /api/graph?view=global|local|project|timeline|concepts|documents|references&pageId=&from=&to=`,166    `POST /api/graph/relations` (typed, user), `PATCH /api/graph/relations/<id>` (accept/reject/edit), `DELETE`,167    `GET /api/graph/insights`, `POST /api/graph/insights/run` (queues the AI analysis job),168    `PATCH /api/graph/insights/<id>` (accept/dismiss), `GET/POST/PATCH /api/concepts`.1694.4 Timeline: `GET /api/events?pageId=&projectId=&from=&to=&kinds=&cursor=`; Time machine:170    `GET /api/timemachine?at=<ISO>&pageId=|projectId=` → state at that date (nearest version ≤ at per page,171    relations/references existing at that date), `POST /api/pages/<id>/versions/<vid>/restore` (existing restore path).1724.5 Health: `GET /api/health/knowledge` → orphans, broken links, missing references, potential duplicates,173    untitled, inactive projects, open tasks (ids + counts, computed from real data).1744.6 Brief: `GET /api/brief` → recent notes, active projects, tasks due/overdue, unfiled captures, link175    suggestions, documents to revisit; optional AI summary only on explicit `POST /api/brief/summary`.1764.7 Living blocks: `POST /api/query` `{source, databaseId?, viewId?, filter, limit}` → rows for `queryView`/`chart`.1774.8 Canvas (§3.4). 4.9 Semantic zoom: `GET /api/pages/<id>/zoom?level=1|2|3` (1 = AI synopsis, cached and marked178    AI; 2 = outline: headings + first sentence of each section, computed without AI; 3 = full).1794.10 Ask: `POST /api/ai/chat` gains `scope` (`all|page|project|selection`) and citations keep `blockId`;180     `POST /api/ai/action` gains the actions `coherence`, `questions`, `links`, `synthesis`, `structure`.1814.11 Models: `GET /api/ai/models` gains creator/route/context/price/capabilities/available + `logo` path182     (`/model-logos/<creator>.svg`, neutral fallback `generic.svg`).1834.12 Capture: `POST /api/capture` kinds extended (`audio`, `screenshot`, `selection`, `document`);184     `GET /api/inbox/<id>/suggestions` (AI title/tags/project/relations/summary — suggestions only),185     `POST /api/inbox/<id>/apply` applies the chosen subset (journaled, undoable).1864.13 Voice: `POST /api/audio/<attachmentId>/transcribe` (queues job; engine reported; result written into the187     `audio` node through a normal versioned save), `GET /api/audio/<attachmentId>`.1884.14 Research: `GET /api/research/export.tex?projectId=`, project-scoped listing, `citation` resolution189     `GET /api/research/references?ids=`.1904.15 `/api/files/<id>` supports `Range`. Malformed ids → 400 everywhere. Purge deletes attachments. Parent cycles refused (409).191192## 5. Note Visual System 2.0 — « Graphite & Ultramarine · Lumen »193194Evolution of the existing identity (do not restart it): graphite neutrals, ultramarine accent, violet for195anything AI. New in 2.0: editorial serif for reading titles, a spacing/radius/elevation/motion scale,196translucent "glass" chrome, and seven signature motions. The same tokens exist on the web (CSS custom197properties, `src/app/globals.css`) and in Swift (`SPNotesDesign` module in SPNotesCore). The native apps198abandon their amber accent for ultramarine (amber stays only as the `warning` hue).199200Colour (sRGB approximations for Swift; web keeps its oklch sources of truth — audit-web §9.2):201202| token | light | dark |203|---|---|---|204| bg | #F9FAFC | #12141C |205| bgElevated | #FFFFFF | #1A1D27 |206| bgSunken | #F1F3F7 | #0D0F15 |207| bgSidebar | #F4F6F9 | #0F1118 |208| bgHover | #EBEEF4 | #222633 |209| fg | #161A26 | #EBEEF4 |210| fgMuted | #535B6E | #A6AEC0 |211| fgFaint | #8A91A3 | #707889 |212| line | #E3E6EC | #262A36 |213| lineStrong | #CFD4DE | #363B4A |214| accent | #3157D5 | #8AA2FF |215| accentFg | #FBFCFF | #0B1230 |216| accentSoft | #E9EEFF | #1F2C5C |217| ai | #7A3FD6 | #B699FF |218| aiSoft | #F1EAFF | #33205E |219| success | #2E8B57 | #6CCB93 |220| warning | #C98A1A | #F0BC5E |221| danger | #D14343 | #F08A80 |222223Signature gradient « Lumen » (hero surfaces, capture pulse, graph links, AI shimmer): accent → ai at 135°.224Typography: UI = system sans (SF Pro / Inter on web, self-hosted); reading titles + optional body = serif225(New York on Apple = `Font.Design.serif`; Source Serif 4 on web, self-hosted); code = SF Mono / JetBrains Mono.226Scale (pt/px): micro 11, ui 13, body 16 (reading 17 on iPhone), h3 20, h2 24, h1 30, display 40; reading measure 46rem / ~680 pt.227Spacing: 2, 4, 8, 12, 16, 24, 32, 48, 64. Radii: xs 4, sm 6, md 10, lg 14, xl 20, pill 999.228Elevation: card (hairline + 1px shadow), pop (16/40 blur), glass (material/backdrop-blur 20px + 60–72 % surface + hairline).229Motion tokens: instant 90 ms, fast 160 ms, base 240 ms, slow 420 ms, ambient 900 ms;230easing standard `cubic-bezier(.2,.8,.2,1)`, exit `cubic-bezier(.4,0,1,1)`, spring (response .38, damping .82).231Signature motions (each must degrade to a plain cross-fade ≤ 120 ms under Reduce Motion):2321 Living Pages (blocks rise 6 px + fade, 18 ms stagger, capped at the first 24 blocks) · 2 Morphing Editor233(toolbar content morphs with the selected block type) · 3 Knowledge Connections (edges draw themselves in the234graph/constellation) · 4 Fluid Navigation (shared-element title transition list → page) · 5 Intelligent Panels235(AI/search/properties panels slide + blur in from their edge) · 6 Quick Capture (sub-200 ms scale-in, Lumen pulse236on save) · 7 Semantic Zoom (level change cross-dissolves while keeping the scroll anchor).237238## 6. Platform expectations239240Functional parity is the goal; ergonomics differ. Server-computed features (ask, timeline, time machine,241health, brief, graph views, insights, query blocks, semantic zoom, models) are rendered **natively** from the242same endpoints. Offline: pages/attachments/tasks/canvases are editable offline on natives; databases, graph,243research, health, brief are readable offline from the last synced copy and editable online. The parity244matrix must state the truth per platform.245246## 7. Amendments (lead decisions after wave 1)247248- **Contrast**: `fgFaint` is for placeholders/decoration only (never body or label text). Semantic hues used249  as *small text* in light mode use darker text variants: `successText #1F7A47`, `warningText #8A5A00`,250  `dangerText #B93232` (dark mode keeps the base hues). Fills, icons and borders keep the base hues.251- **Block ids on list items**: loading a 2.x document now assigns ids to `listItem`/`taskItem`; this is a252  content change only when the page is next saved by the user (clients must not mark a page dirty just253  because ids were assigned at load).254- **Callout icons for the new kinds**: decision ⚖️, question ❓, hypothesis 🧪 (all platforms).255- **Canvas merge edit-vs-delete**: the edited node is kept and the conflict is reported (all platforms).256- **Exact colours (supersede the §5 approximations; measured sRGB of the web oklch tokens — natives must use these)**:257258| token | light | dark |259|---|---|---|260| bg | #F9FBFD | #0D1016 |261| bgElevated | #FFFFFF | #15181F |262| bgSunken | #F0F3F6 | #080A0F |263| bgSidebar | #F3F6F9 | #0A0C12 |264| bgHover | #EAEDF2 | #1D2028 |265| fg | #151922 | #E8EBEF |266| fgMuted | #535862 | #A0A5AE |267| fgFaint | #848992 | #6A6F77 |268| line | #E1E4E8 | #22252D |269| lineStrong | #CCD0D5 | #333640 |270| accent | #2F5DDB | #7CA5FF |271| accentFg | #FBFCFE | #090F1C |272| accentSoft | #E5F0FF | #1B2A4C |273| ai | #7E41D2 | #B999FB |274| aiSoft | #F3ECFF | #302249 |275| success | #008B4E | #5BC083 |276| warning | #D98B09 | #F2AF48 |277| danger | #CC272E | #F26A64 |278279  Light-mode small-text variants: `successText #006B3C`, `warningText #8A5A00`, `dangerText #B0181F`.280- **Languages**: web UI strings stay English (the web app's existing convention); native UI strings stay French281  as source with the English catalogue (existing convention of each project).282- **Mermaid preview** is a 2× PNG attachment (natives draw it as an image).283- **Web client module names**: client node definitions `src/lib/editor/next-node-defs.ts`; server node rules284  `src/lib/editor/next-nodes.ts`.285- Integration branch for backend + web: `M4M64c:~/dev/note-next-int` (branch `next-int`, DB `note_next_int_dev`,286  port 8486, `~/dev/note-next-int-data/srv.sh`). Contracts: `docs/next/API-NEXT.md`, `docs/next/API-NEXT-AI.md`,287  `docs/next/EDITOR-NODES.md`, `docs/next/DESIGN-SYSTEM-NEXT.md` (laptop copies of the two API files in `/tmp/spnote-next/`).288289## 8. Native architecture for the feature screens (lead decision after Core wave 2)290291To guarantee parity and avoid writing every screen twice, cross-platform SwiftUI feature screens live in a new292library **`SPNotesFeatures`** inside the SPNotesCore package (depends on SPNotesDesign, SPNotesSync repositories,293SPNotesDocument; SwiftUI + Swift Charts + PDFKit + AVFoundation; `#if os()` only where a platform API differs;294no WebKit/JavaScriptCore). Each screen takes `NotesRepositories` (plus a small `FeatureRouter` protocol the host app295implements: `openPage(id:blockId:)`, `openDatabase(id:)`, `openCanvas(pageId:)`, `openURL(_:)`, `presentError(_:)`)296and adapts by size class (compact = iPhone layouts; regular = Mac/iPad multi-column). Public screens:297298`TasksScreen`, `InboxScreen` (triage + AI suggestions checklist), `DatabaseScreen` (table, board, list, gallery,299calendar, timeline views; filters/sorts/grouping; row editor; online-write/offline-read as the repositories do),300`GraphScreen` (7 views, typed relations, insights panel), `ConstellationScreen`, `TimelineScreen` (+ time machine),301`KnowledgeHealthScreen`, `DailyBriefScreen`, `AskScreen` (scope, block citations → router), `ModelPickerView`302(creator logos generated from the web `public/model-logos/registry.json`), `UnifiedSearchScreen`, `ResearchScreen`303(references, DOI/BibTeX, LaTeX export share), `CanvasScreen` (infinite canvas; compact = list/outline mode),304`SemanticZoomControl` + `PageOutlineView`, `CommandCenterView` (palette over a command registry),305and block detail views used by both editors' atom sheets: `MermaidBlockView`, `DrawingBlockViewer` (ink render;306editing: PencilKit on iOS in the app, mouse/trackpad ink editor in Features for macOS), `ChartBlockView`307(Swift Charts + data grid editor), `QueryViewBlockView`, `BlockRefView`, `CitationPickerView`/`BibliographyView`,308`PDFBlockView` (PDFKit, highlight/note/ink annotations ⇄ `PDFAnnotation` normalised rects), `RunCodeBlockView`309(code + last output; no execution), `AudioBlockView` (record/pause/resume, player, transcript with seek, summary).310311The app projects own: the shell/navigation, the TextKit editors (atom cards for the new nodes → open the Features312view in a sheet/inspector/window), platform integration (windows, menus, Quick Note, Spotlight, widgets, share,313intents, Pencil, haptics), signing and release.314Live test server for natives: integration build on `M4M64c:127.0.0.1:8486` (tunnel with the SAME local port:315`ssh -f -N -L 8486:127.0.0.1:8486 M4M64c`; cancel only your own forward; token:316`ssh M4M64c 'cd ~/dev/note-next-int && export PATH=/opt/homebrew/bin:$PATH && set -a && . ./.env && set +a && node node_modules/tsx/dist/cli.mjs scripts/dev-session.ts'`;317mutations need `Origin: http://localhost:8486`).318
Files main
Menu

Theme