Rich text format

Rich text format

Canonical storage for note CRDT bodies and study plan step instructions is a versioned JSON envelope, not markdown. Markdown is used for import, export, and derived search text only.

Storage envelope

type StorageEnvelope = {
  v: 1;
  doc: JSONContent; // TipTap / ProseMirror document
};

• Notes CRDT (body field): JSON.stringify(envelope); schema version 2 (see Note CRDT sync).
• Study plan instructions (instructions column): same envelope JSON string (column remains text).
• markdown_body (notes only): derived plain-text export on every CRDT merge for list cards and search — not the source of truth.

Strings that fail JSON envelope parse are treated as legacy markdown and converted on read via fromMarkdown().

Node and mark types

Node / mark	Purpose	Legacy markdown token
scriptureRef (inline atom)	Verse chip	[[ref:Rom.1.1]]
filterBlock (block)	Study-plan conditional content	:::filter personality=Task\n...\n:::
Marks: bold, italic, underline, code	Formatting	**, *, <u>, `
Nodes: heading (1–3), paragraph, hardBreak	Structure	#, plain text

scriptureRef attributes

Attr	Type	Description
path	string	Canonical ref path, e.g. Rom.1.1
label	string	Display label, e.g. Romans 1:1

filterBlock attributes

Attr	Type	Description
personality	string[]	Personality focus values (OR within attribute)
learning	string[]	Learning style values (OR within attribute)

All specified attributes must match the user profile (AND). Unconditional blocks omit both arrays or leave them empty.

Golden fixtures

Shared test vectors live in ui/test/fixtures/richText/ (envelope JSON + expected markdown). PHP and TypeScript test suites import the same files for parity.

Related

• Note CRDT sync — Automerge body sync, schema v2
• Study plans — filter blocks at materialization