SPB Git

Repository Public

DOCUMENT_API.md 26.7 KB

# SPNotesDocument — public API

Foundation only, Swift 6, value types, all Sendable and Hashable. The backend stores a note as ProseMirror / Tiptap JSON; this module turns it into a flat list of lines an editor can drive, and back, without losing anything.

swift
import SPNotesDocument

var doc = try NoteDocument(json: data)          // ProseMirror JSON → lines
doc.toggleMark(.bold, in: 0..<5, at: 2)         // edit
doc.ensureBlockIds()                            // before saving
let body = try doc.jsonData()                   // lines → canonical JSON (sorted keys)

# Conventions

  • Line index: index in doc.lines. Commands taking a Range<Int> of lines clamp it to the document.
  • Inline offset / range: UTF-16 code units (NSString / NSRange compatible). An inline atom (hard break, mention, inline math, footnote reference, unknown inline node) counts as exactly 1 unit: display it as one U+FFFC attachment character. Line.displayString gives such a string (hard break as U+2028), Line.inlineLength its length.
  • Commands are public mutating func on NoteDocument. They return Bool (whether the document changed) unless stated otherwise, never trap on out-of-range input, and leave a document that is valid for the web schema when they were given one.
  • New nodes are created with every schema attribute (defaults included) and a fresh block id, exactly as the web editor serializes them.
  • == on NoteDocument compares container keys too; use isStructurallyEqual(to:) to compare content only.

# Model

swift
public enum JSONValue { case null, bool(Bool), int(Int64), double(Double), string(String), array([JSONValue]), object([String: JSONValue]) }
public struct PMMark { var type: String; var attrs: [String: JSONValue]? }
public struct PMNode { var type: String; var attrs: [String: JSONValue]?; var content: [PMNode]?; var text: String?; var marks: [PMMark]?; var extra: [String: JSONValue] }

public struct NoteDocument { var lines: [Line] }
public struct Line { var path: [Container]; var type: String; var attrs: [String: JSONValue]; var content: LineContent }
public struct Container { var key: Int; var type: String; var attrs: [String: JSONValue] }
public enum LineContent { case inline([InlineRun]); case blockAtom(PMNode) }
public enum InlineRun { case text(String, marks: [PMMark]); case atom(PMNode) }
public struct InlinePosition { var line: Int; var offset: Int }
  • A text block (paragraph, heading, codeBlock, footnote, detailsSummary, unknown node with inline children) is one line with .inline runs. A code block is ONE line whose text contains the \n.
  • A block atom (table with its whole subtree, image, fileBlock, blockMath, horizontalRule, youtube, unknown leaf, container with no child) is one line with .blockAtom(node). The line's type and attrs are authoritative (the id lives in line.attrs["id"]); the node supplies the rest. line.atomNode gives the effective node.
  • A container (bulletList, orderedList, taskList, listItem, taskItem, blockquote, callout, aiBlock, details, detailsContent, unknown node with block children) is not a line: it is a frame in line.path, outermost first, doc excluded. Every line of the same container node carries an equal frame (same key). Consecutive lines sharing a key at a depth form one node.
text
- [ ] buy milk            path [taskList#1, taskItem#2]              paragraph
  - [x] oat               path [taskList#1, taskItem#2, taskList#3, taskItem#4]   paragraph
> quote                   path [blockquote#5]                        paragraph

Because a frame is repeated on each line of its group, change a container through doc.updateContainer(key:) { $0.attrs["open"] = true } (updates every copy), and create frames with doc.makeContainer(NodeType.blockquote) (fresh key, default attrs, fresh id) or doc.newContainerKey().

# Reading and writing

swift
init()                                   // one empty paragraph
init(lines: [Line])
init(node: PMNode)                       // flatten a `doc` node
init(json: Data) throws
init(markdown: String)                   // server import rules, schema-valid, ids assigned
init(markdown: String, resolvePage: (String) -> String?)   // [[Wiki links]] → mentions when a page id is returned
func pmNode() -> PMNode
func jsonData() throws -> Data           // canonical: sorted keys
func isStructurallyEqual(to: NoteDocument) -> Bool
mutating func ensureBlockIds()           // same rule as the server's ensureBlockIds — call before saving
mutating func newContainerKey() -> Int
mutating func makeContainer(_ type: String, attrs: [String: JSONValue] = [:]) -> Container
mutating func updateContainer(key: Int, _ body: (inout Container) -> Void)
mutating func normalizeContainerKeys()   // re-keys a container whose lines are no longer contiguous
mutating func insert(lines: [Line], at index: Int)   // paste: foreign container keys are remapped
func schemaViolations(strict: Bool = false) -> [String]   // empty when valid for the web schema; strict also reports
                                                          // what ProseMirror would normalize (missing attrs, mark order…)

Lossless guarantee. For an unmodified document, NoteDocument(json:) then jsonData() is semantically identical to the input (key order aside): unknown node types, unknown attributes, unknown keys, mark order, empty paragraphs, attrs: {} vs no attrs, content: [] vs no content. On serialization adjacent text runs with identical marks are merged and empty text runs are dropped. (A document that already held two adjacent text nodes with the same marks, an empty text node or marks: [] — none of which ProseMirror produces — still comes back unchanged: such nodes are kept as raw .atom runs of type text.)

Useful accessors: line.runs, line.isText, line.inlineLength, line.displayString, line.node (the line's own ProseMirror node), line.atomNode, run.length, run.marks, node.plainText, JSONValue.stringValue / intValue / …, JSONValue.canonicalData(), JSONValue.semanticallyEquals(_:), BlockID.generate(), NodeType.<name> constants.

# Building lines and nodes

swift
Line.paragraph(_ runs: [InlineRun] = [], path: [Container] = [])
Line.paragraph(text: String, path: [Container] = [])
Line.heading(level: Int, _ runs: [InlineRun] = [], path: [Container] = [])
Line.codeBlock(language: String? = nil, text: String = "", path: [Container] = [])
Line(blockAtom: PMNode, path: [Container] = [])
PMNode.image(src:alt:title:)   PMNode.fileBlock(src:name:size:mime:attachmentId:)   PMNode.horizontalRule()
PMNode.blockMath(latex:)       PMNode.table(rows:cols:withHeaderRow:)
PMNode.mention(id:label:)      PMNode.hardBreak()      PMNode.inlineMath(latex:)     PMNode.text(_:marks:)
PMMark.mark(_ kind: MarkKind)  PMMark.link(href:title:)

# Commands

# Block structure

swift
mutating func setLineType(_ kind: LineKind, at lines: Range<Int>) -> Bool
    // LineKind: .paragraph | .heading(level: 1...3) | .codeBlock(language: String?)
mutating func toggleList(_ kind: ListKind, at lines: Range<Int>) -> Bool          // .bullet | .ordered | .task
mutating func indentListItems(at lines: Range<Int>) -> Bool                        // Tab
mutating func outdentListItems(at lines: Range<Int>) -> Bool                       // Shift-Tab
mutating func toggleBlockquote(at lines: Range<Int>) -> Bool
mutating func toggleCallout(kind: String, icon: String, at lines: Range<Int>) -> Bool
mutating func setTaskChecked(_ checked: Bool, at line: Int) -> Bool
mutating func splitLine(at line: Int, offset: Int) -> InlinePosition               // Enter; returns the caret
mutating func mergeWithPrevious(at line: Int) -> InlinePosition?                   // Backspace at offset 0; nil = nothing done
mutating func insertBlockAtom(_ node: PMNode, after line: Int?) -> Int             // returns the index of the new line
mutating func replaceBlockAtom(at line: Int, with node: PMNode) -> Bool            // e.g. after a table edit; keeps the id
mutating func deleteLine(at line: Int) -> Bool
  • setLineType acts on paragraph / heading / codeBlock lines. The first paragraph of a list item stays a paragraph (schema: listItem: "paragraph block*"), such lines are skipped. To a code block: marks are dropped, atoms become their text. From a code block: each \n becomes a hard break.
  • toggleList: paragraphs and headings outside a list are wrapped (one item per line, joined with an adjacent list of the same kind); lines of a list of another kind convert that whole list; when every line is already in a list of that kind the items are lifted out of it.
  • indentListItems nests the item inside the previous item of its list (false when there is none). outdentListItems moves it one level out; the items that followed it in the inner list follow it as its children; at the first level the item leaves the list.
  • toggleBlockquote / toggleCallout wrap the blocks covering the lines, at the deepest level the schema allows (the first paragraph of a list item cannot be wrapped alone: its whole list is; a later block of an item is wrapped inside the item). When every line is already inside one, the blocks are lifted out. A callout of another kind is re-typed.
  • toggleList on an item of a nested list that is already of that kind turns it into a plain block of its parent item (use outdentListItems to move it one level out instead).
  • splitLine: in a list item → a new item (unchecked for tasks), the rest of the item follows the new one; on an empty item → leaves the list (one level); empty paragraph in a quote / callout → leaves it; heading split at its end → paragraph; in a code block → inserts \n; on a block atom → empty paragraph after it.
  • mergeWithPrevious: the first line of a list item is outdented / lifted out of the list; the first block of a quote or callout is lifted out of it; otherwise the line's content is appended to the previous text line and the caret position returned. An empty paragraph after a block atom is removed. Returns nil when nothing can be done (first line, non-empty line after a block atom, structural boundary such as a details summary).

# Inline

swift
mutating func replaceText(in range: Range<Int>, at line: Int, with text: String, marks: [PMMark]? = nil) -> Bool
    // typing, deleting, pasting plain text in one line; marks nil = inherit from the text before the range
mutating func insertInlineAtom(_ node: PMNode, at offset: Int, line: Int) -> Bool
mutating func toggleMark(_ kind: MarkKind, in range: Range<Int>, at line: Int) -> Bool
    // MarkKind: bold, italic, underline, strike, code, highlight, subscript, superscript; `code` excludes the others
mutating func setLink(href: String, in range: Range<Int>, at line: Int) -> Bool
mutating func removeLink(in range: Range<Int>, at line: Int) -> Bool
func marks(at offset: Int, line: Int) -> [PMMark]                 // marks typed text would take at this caret
func hasMark(_ kind: MarkKind, in range: Range<Int>, at line: Int) -> Bool
func linkRange(at offset: Int, line: Int) -> Range<Int>?          // extent of the link around a caret

# Queries for the editor chrome

swift
func listKind(at line: Int) -> ListKind?        // innermost list of the line
func listDepth(at line: Int) -> Int             // number of nested lists
func isListItemHead(at line: Int) -> Bool       // first paragraph of an item (draws the bullet / number / checkbox)
func isTaskChecked(at line: Int) -> Bool?       // nil outside a task item
func listItemNumber(at line: Int) -> Int?       // ordinal in an ordered list (honours `start`)

# Tables (on the raw table node)

swift
extension PMNode {
    var tableGrid: [[TableCell]]                 // TableCell { text: String; isHeader: Bool; colspan: Int; rowspan: Int }
    mutating func setTableCellText(_ text: String, row: Int, column: Int) -> Bool   // no-op when the text is unchanged
    mutating func insertTableRow(at row: Int) -> Bool
    mutating func deleteTableRow(at row: Int) -> Bool        // false if it is the last one
    mutating func insertTableColumn(at column: Int) -> Bool
    mutating func deleteTableColumn(at column: Int) -> Bool  // false if it is the last one
    mutating func toggleTableHeaderRow() -> Bool
}
swift
guard var table = doc.lines[i].atomNode else { return }
table.setTableCellText("Total", row: 2, column: 0)
doc.replaceBlockAtom(at: i, with: table)

Setting a cell's text replaces its content by one paragraph of plain text (line feeds as hard breaks) only when the text differs from the cell's current plain text, so formatted cells that were not edited are preserved.

# Text, Markdown, HTML

swift
func plainText() -> String              // == server docText
var wordCount: Int                      // == server wordCount(docText)
func preview(maxLength: Int) -> String  // first non-empty line, whitespace collapsed, "…" when cut
func pageReferences() -> [String]       // == server extractPageRefs
func attachmentReferences() -> [String] // /api/files/<uuid> of images and files + fileBlock attachmentId
func taskItems() -> TaskCounts          // { total, checked }
func markdown() -> String               // == server toMarkdown
func html(title: String) -> String      // standalone HTML5 file, embedded stylesheet, images by their src
func htmlBody() -> String               // the body markup alone
static func wordCount(of: String) -> Int
  • plainText, wordCount and markdown reproduce the server byte for byte (checked on the fixtures and on 400 random trees against outputs recorded from the web application's own helpers).
  • pageReferences() returns string ids only (the server would also keep a non-string truthy mention id).
  • Markdown import follows the server (marked + the import fixes): images with an absolute, data: or /api/files/ source become image blocks, other images become [image: alt] text, [[Wiki links]] become mentions when resolved. Where the server would leave a document the schema rejects, the import repairs it: an empty paragraph is added in front of a list item that starts with another block and inside an empty quote, text marked code keeps only that mark, javascript: links are dropped. Reference-style links, footnotes and HTML blocks are imported as text.
  • HTML: same markup as the server's print view, without KaTeX — math is exported as its LaTeX source in <code class="math">. Link and image URLs go through the same allow-list as the server (# otherwise).

# 3.0 nodes (SPNotesCore 2.0)

SPEC §2 adds ten block-level leaf atoms and one inline atom. They keep all their data in attrs; binary data is an attachment referenced by id. Constants: NodeType.mermaid, .drawing, .chart, .queryView, .bibliography, .pdf, .blockRef, .runCode, .audio, .canvasLink, .citation (inline); NodeType.nextBlocks lists the ten blocks.

In the flat model a new block is a .blockAtom line (line.atomNode), a citation is an .atom run of a text line (one UTF-16 unit for the editors). Insert, replace and delete with the existing commands (insertBlockAtom, replaceBlockAtom, insertInlineAtom, deleteLine).

# Typed views

Editors never read raw JSON: each node has a struct conforming to TypedNode with init?(node: PMNode) (nil for another type), node() -> PMNode, a builder with the schema defaults and a fresh block id, and typed properties.

swift
if case .audio(var audio)? = document.typedBlock(at: line) {     // or TypedBlock(node:), or AudioBlock(node:)
    audio.title = "Réunion budget"
    document.replaceBlockAtom(at: line, with: audio.node())
}
document.insertBlockAtom(MermaidBlock(code: "graph TD\n  A-->B").node(), after: line)
document.insertInlineAtom(CitationInline(refId: id, label: "Fama 1970", locator: "p. 3").node(), at: offset, line: line)
View Properties Helpers
MermaidBlock code, preview, previewHash isPreviewCurrent (render made from the current source: SHA-256 of code), setPreview(attachmentId:), MermaidBlock.hash(of:)
DrawingBlock ink, preview, pk, width, height, background setInk(attachmentId:preview:width:height:pk:) — without pk it is cleared (an editor without PencilKit changed the ink)
ChartBlock kind: ChartKind, title, columns, rows: [[ChartCell]], x, y, source: ChartSource? resolvedX, resolvedY, series() -> [ChartSeries] (ready for Swift Charts)
QueryViewBlock source: QuerySource, databaseId, viewId, filter: QueryFilter, layout: QueryLayout, limit (1…500), title —
CitationInline refId, locator, label displayText
BibliographyBlock style, title —
PDFBlock attachmentId, name, page, annotations: [PDFAnnotation] add, update, remove(annotationId:), annotations(onPage:)
PDFAnnotation id, page, kind: PDFAnnotationKind, color, rects: [PDFRect], text, note, ink: [PDFPoint]?, createdAt summaryLine; coordinates 0…1, origin top-left
BlockRefBlock pageId, blockId, mode: BlockRefMode BlockRefBlock.missingTargetText (« Référence introuvable »)
RunCodeBlock language, code, output: RunCodeOutput? (read-only) clearOutput(); natives never execute
AudioBlock attachmentId, duration, title, recordedAt, transcript: [TranscriptSegment], transcriptStatus, transcriptEngine, summary: AudioSummary? (read-only) transcriptText, segmentIndex(at:), TranscriptSegment.timecode
CanvasLinkBlock pageId —

ChartKind, QuerySource, QueryLayout, PDFAnnotationKind, BlockRefMode, TranscriptStatus, CalloutKind are OpenChoice values: string-backed, with static constants for the known values and isKnown == false for a value written by a newer editor (which is kept).

Lossless rule. A typed view wraps the node it was read from. Attributes it does not know, unknown keys of the node and values of an unexpected shape are returned untouched by node(); a setter changes its own attribute only. PDFAnnotation.fields, QueryFilter.fields and ChartBlock.source keep unknown keys the same way; PDFBlock.add / update / remove never rewrite the other entries of annotations. view[attr: "name"] reads or writes any attribute. An id property (preview, attachmentId, pageId, refId…) reads as nil unless the stored value is a UUID, exactly as the server treats it. Unknown node types still round-trip verbatim (node.isKnownType == false → show the neutral read-only card).

# Existing nodes extended

Node New optional attributes API
taskItem due (ISO date), priority (low, medium, high), taskId taskAttributes(at:), setTaskDue(_:at:), setTaskPriority(_:at:), setTaskId(_:at:), taskItemDetails() -> [TaskItemDetail] (the server's docTaskItems)
aiBlock sources ([{pageId, blockId, title}]), action aiBlockInfo(at:) -> AIBlockInfo?, AIBlockInfo(attrs:), applied(to:)
callout kinds decision, question, hypothesis CalloutKind, calloutKind(at:), toggleCallout(_:at:); defaultIcon is a native suggestion (the web had not fixed icons for the new kinds)
listItem, taskItem block id assigned by ensureBlockIds() and by every command creating an item

Block ids. Schema.idTypes equals the 3.0 server's ID_TYPES: the 2.x list plus listItem, taskItem and the ten new blocks. Consequence for the apps: ensureBlockIds() now gives an id to the list items of a document written by a 2.x editor (the 3.0 server does the same at every save), so "load then serialize" is no longer the identity on such a document. Splitting an item creates an item with a fresh id; in a task list the new item is unchecked and has no due date, priority or linked task. Converting an item between list kinds keeps its id and adds or removes the task-only attributes.

Schema check. In strict mode the attributes added in 3.0 to existing nodes may be absent (a 2.x document); nodes built by Core always carry the full 3.0 set.

# Text, Markdown, HTML of the new nodes

A line-by-line port of the server (docs/reference/next/), verified byte for byte on the four fixtures the backend publishes (Tests/SPNotesDocumentTests/Fixtures/next-nodes/: .json with its expected .md, .txt, .html) and on 521 documents recorded from the server's own functions (Fixtures/next-server.json).

Node Markdown Plain text
mermaid fenced mermaid block the source
runCode fenced block with its language; when output.text is a string, a blank line then a fenced output block code, then output
chart title line, blank line, Markdown table of columns / rows (cells: null → empty, numbers as ECMAScript prints them, ` escaped, one line); without columns: the title or[Graphique]`
drawing ![Dessin](/api/files/<preview>) or [Dessin] Dessin
pdf [PDF: name](/api/files/<id>) (or [PDF]…), blank line, one > p.<page> — <text> — <note> per annotation (empty parts dropped) the same lines without syntax
audio [Audio: title](/api/files/<id>), blank line, [mm:ss] text per segment (minutes not capped at 59, empty segments dropped) label then the segments' text (no time codes)
queryView [Vue: title] or [Vue] Vue: title
blockRef [[<pageId>#<blockId>]] empty
citation [@<label or refId or ?>] the label
bibliography ## <title or Références> the title
canvasLink [Canvas](/p/<pageId>) or [Canvas] Canvas

Transcript and annotation text are therefore in plainText(), the word count and the full-text index; attachment ids, time codes and the AI summary are not. attachmentReferences() now also returns the files of mermaid (render), drawing (ink, render, PencilKit data), pdf and audio; pageReferences() the targets of blockRef and canvasLink; citedReferences() the ids cited. htmlBody() prints one element of class nx nx-<type> per node (static: a chart is its table, code is never executed). Numbers in exported text now follow ECMAScript's Number::toString (1e-7, 1e+21).

# Ink (spn-ink-1)

Width law (the one law of every platform — lead decision 2026-11-19, the web adopts it). A pen stroke is drawn width × (0.35 + 0.65 × pressure) wide: the nominal width at pressure 1, 35 % of it at pressure 0. marker and highlighter strokes have a constant width. A point without pressure has pressure 1 (a mouse or a finger writes 1). An opaque highlighter colour is drawn at 40 % opacity. InkRenderer.penWidth(_:_:) is the law; InkRenderer.pressure(forWidth:nominal:) is its inverse, for editors that measure a width (PencilKit) and must store a pressure.

InkDocument { width, height, strokes }, InkStroke { tool: InkTool, color: InkColor, width, points: [InkPoint] } — the neutral format of a drawing's ink attachment (init(data:), jsonData(), unknown fields kept). simplified(tolerance:) (Ramer–Douglas–Peucker, pressure-aware), boundingBox, hit testing (strokeIndices(near:radius:), strokeIndices(intersecting:)). InkRenderer.image(_:scale:background:), pngData(…) and draw(_:in:) render with CoreGraphics only, identically on macOS and iOS (the preview attachment). PencilKit is not importable here: the iOS app converts PKDrawing ⇄ InkDocument (the mapping PKInkType → InkTool is in the doc comment of InkTool). Only lossy case: numbers beyond the third in a point.

# Canvas (spn-canvas-1)

CanvasDocument { nodes: [CanvasNode], edges: [CanvasEdge], viewport: CanvasViewport } with unknown fields kept at every level (init(data:), jsonData()), editing helpers (addNode, updateNode, removeNode — which removes the node's edges —, addEdge, updateEdge, removeEdge, bringToFront, sendToBack, normalizeZ, bounds, nodes(in:)).

CanvasDocument.merge(base:local:remote:) -> CanvasMergeResult merges by node / edge id: an element changed, added or deleted on one side only is taken; the same change on both sides is taken; the same id edited differently on both sides is a CanvasConflict (the merged canvas keeps the local version, the conflict carries base, local and remote); edited on one side and deleted on the other keeps the edited version and reports .editedAndDeleted; an edge left dangling by a deletion is dropped when nobody touched it, otherwise its node is restored and .deletedButReferenced is reported. Order: base order, then additions sorted by id (a clean merge is byte-identical whichever side is "local"). The viewport is per-device view state: local wins unless only the remote changed. resolving(_:takingRemote:) applies a decision. Granularity is the element: two different fields of the same node edited on the two sides conflict.

CanvasLayout.grid(…) and CanvasLayout.forceDirected(…, seed:) (step, energy, overlapArea) lay nodes out deterministically from a seed.

# Three-way merge

swift
static func merge(base: NoteDocument, mine: NoteDocument, theirs: NoteDocument) -> MergeResult   // .merged(doc) | .conflict

Top-level blocks are matched by their block id (blocks without an id, such as a horizontal rule, by their content). A block changed, inserted, deleted or moved on one side only is taken from that side. .conflict when the same block was changed differently on both sides, changed on one side and deleted on the other, when both sides inserted or reordered at the same place differently, when the result would be empty, or when top-level ids are duplicated. The merge never drops a change silently. A top-level block is the whole node (an entire list, quote or table): two edits inside the same list conflict. The result is a new document (fresh container keys).

# Validating against the real web schema

swift test writes every document the module emits in its scenarios (fixture, each command, Markdown imports, merges, random command sequences) to /tmp/spn-docs.json; validate them as described in docs/reference/README.md:

sh
scp /tmp/spn-docs.json M4M64c:/tmp/spn-docs.json
ssh M4M64c 'bash -lc "cd ~/dev/note-v2 && node_modules/.bin/tsx .spn-schema.mts validate /tmp/spn-docs.json"'

Every line must read ok … identical. doc.schemaViolations(strict: true) is the native equivalent used by the tests.

# Known limits

  • Swift compares strings by canonical equivalence: two documents differing only by Unicode normalization are ==.
  • A lone UTF-16 surrogate escape in JSON (\ud800) is read as U+FFFD.
  • Marks are toggled on text only; inline atoms keep their own marks.
  • Table helpers address cells by their position in each row; they do not resolve colspan / rowspan geometry.
Files main
Menu

Theme