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.
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 aRange<Int>of lines clamp it to the document. - Inline offset / range: UTF-16 code units (
NSString/NSRangecompatible). An inline atom (hard break, mention, inline math, footnote reference, unknown inline node) counts as exactly 1 unit: display it as oneU+FFFCattachment character.Line.displayStringgives such a string (hard break asU+2028),Line.inlineLengthits length. - Commands are
public mutating funconNoteDocument. They returnBool(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.
==onNoteDocumentcompares container keys too; useisStructurallyEqual(to:)to compare content only.
Model
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
.inlineruns. 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'stypeandattrsare authoritative (the id lives inline.attrs["id"]); the node supplies the rest.line.atomNodegives 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,docexcluded. Every line of the same container node carries an equal frame (samekey). Consecutive lines sharing a key at a depth form one node.
- [ ] buy milk path [taskList#1, taskItem#2] paragraph
- [x] oat path [taskList#1, taskItem#2, taskList#3, taskItem#4] paragraph
> quote path [blockquote#5] paragraphBecause 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
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
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
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) -> BoolsetLineTypeacts 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\nbecomes 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.indentListItemsnests the item inside the previous item of its list (false when there is none).outdentListItemsmoves 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/toggleCalloutwrap 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.toggleListon an item of a nested list that is already of that kind turns it into a plain block of its parent item (useoutdentListItemsto 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
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 caretQueries for the editor chrome
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)
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
}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
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) -> IntplainText,wordCountandmarkdownreproduce 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 markedcodekeeps 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.
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 |
 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
static func merge(base: NoteDocument, mine: NoteDocument, theirs: NoteDocument) -> MergeResult // .merged(doc) | .conflictTop-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:
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/rowspangeometry.