The body of a document and the body of a comment are both an ordered list of block nodes. A block node is one block plus an optional list of child block nodes. Nesting is unlimited. A leaf has no children.

An editor shows the tree, but the tree does not travel on the network. A document is the resolved state of a chain of signed Changes, and each Change carries operations on blocks. ReplaceBlock sets a block's whole state. MoveBlocks places a run of blocks under a parent after a sibling. DeleteBlocks moves blocks to the trash. The daemon replays those operations with a tree CRDT to produce the tree you read. Documents explains the merge.

Two consequences follow.

A block that has state but no position is not lost. The daemon returns it in the document's detached blocks, keyed by id. The Seed app uses one detached block, named navigation, to hold a site's menu. Its children are Link blocks, and the navigation item page describes their shape.

Moving a block never rewrites its contents, and editing a block never changes its position. This keeps concurrent edits cheap to merge.

A block is a map with five reserved keys. Everything else on the block is an attribute.

Inside a signed Change, attributes sit at the top level of the block map. The Seed API and the SDK nest them under an attributes key instead, because protobuf cannot carry open fields. So an attribute may never be named id, type, text, link or annotations. The daemon also accepts a legacy encoding forever. Some early comments spelled the id key iD and put attributes in a nested attributes map. Blobs are permanent, so both spellings read back the same.

Two attributes exist on every block that can have children.

childrenType sets how the children are laid out. The children type values are Group (the default, also when the key is absent or null), Ordered, Unordered, Blockquote and Grid. So a list is a property of the parent block. The bullet belongs to the block above the items.

columnCount sets the number of columns of a Grid.

text holds no markup. Each annotation is a layer over the block's text: a type, parallel starts and ends arrays naming one or more ranges, an optional link, and inline attributes. Offsets count Unicode code points. They do not count UTF-16 units or bytes, so a range means the same thing in every language.

A mention is an inline embed. The block's text holds a single placeholder character, U+FEFF, at the position of the mention. An Embed annotation covering that one character carries the hm:// link. mentionKind is account for a person (the link is the account or its /:profile) or document for a page. Readers render the current name of the target in place of the placeholder, so a mention follows a title change. Text fragments and search skip the placeholder characters when they count offsets.

The protocol defines a strict set of fifteen types, the core block. Each type's page lists its attributes. This table gives the one-line meaning and the attributes that matter.

An ipfs:// link points at a file stored as IPFS data. The Seed app recognizes three more types that are not in the core union. Slot is an invisible container with childrenType and columnCount. It puts a list or a grid at the top level of a document without a visible parent. Link is the navigation menu item described above. Group is a legacy container that some old documents still carry.

An unknown type is never an error. The wire block schema is open. A document that contains a block type this client has no schema for still parses, keeps the block's fields, and renders the block as well as it can. A third party adds a block type this way. The poll block example shows the schema side.

An Embed block shows another Hypermedia resource inside this one. Its link is an hm:// URL, and the URL decides what is embedded: a whole document, one block with #blockId, a block and its children with #blockId+, or a text range with #blockId[start:end]. The URL also decides which version you see. With ?v= the embed is pinned to that exact version. With &l it follows the latest version. The Seed app pins the version when you embed a block from a comment, and follows the latest by default everywhere else. URLs has the grammar.

The embed view attribute chooses the rendering. Content shows the target's body. Card shows its title, summary and cover. Comments shows its discussion. Link shows a plain link. Renderers keep a stack of the resources they are inside. They stop when an embed would show a document that already contains it, so a cycle renders as a link and does not recurse.

A Query block is a live listing. The author stores a query, and every reader sees the current result. The query has three parts.

includes: one or more inclusions, each a space, an optional path prefix inside it, and a mode of Children or AllDescendants.

sort: a list of sort terms, each {term, reverse}. The app writes title, path, created, updated, displayTime and activity today. Older documents carry Title, UpdateTime and the other capitalized spellings, and readers normalize them. A legacy time term sorted newest first by default, so readers flip its reverse flag on the way in.

limit: an optional maximum number of results.

The block's own attributes choose the presentation. style is Card, List or Table. columnCount is the number of card columns. banner shows the first result as a banner above the rest. table config remembers which columns are visible in the table view and how wide they are.

The query object carries no filters today. Attribute filters such as "status is Done" live in the Seed API's QueryDocuments request and the Explore grammar, described in the query grammar. A query block resolves through the same daemon listing and returns each document's info and metadata. That is why a folder page is usually one query block over its own children.

A table uses three block types. There is no cell type.

Table is the container.

TableColumn blocks come first among its children. They have no children and carry only identity and order. The sibling order of the columns is the display order. width and isHeader are their attributes.

TableRow blocks follow. A row's children are its cells: ordinary Paragraph blocks whose columnId attribute names a TableColumn block id. The order of cells inside a row is ignored. A cell belongs to the column its columnId names.

A cell's identity is the pair (row block, column id). It is never a grid position. Editing a cell is a text edit on one paragraph. Adding, reordering or deleting a column is one sibling move or delete of one TableColumn block, and no cell renumbers. Two people who add a row and reorder the columns at the same time merge cleanly: the new row has a cell for every column, and the reordered columns still find their cells by id. Readers drop cells whose columnId matches no column, render missing cells empty, honor isHeader only on the first row and the first column, and drop rows or columns that appear outside a Table. The daemon enforces none of this. It treats all three as ordinary blocks, so these rules are client conventions.

Because blocks have ids, a URL can address text inside a document. #blockId names a block. #blockId+ names the block with its children expanded. #blockId[start:end] names a range of the block's text in Unicode code points, counted on the text with inline-embed placeholders removed. Comments, citations and embeds all use these forms. A range comment pins the document version it was made on, because a later edit would move the offsets.

The revision the daemon reports on each block is the CID of the last Change that replaced it. A citation of a block records the revision it saw, so a reader can tell whether the cited text has changed since.

In the Seed app

CLI

SDK

Web API

Agents