Tick 12a, moving its text to todo-history.md

AGENTS.md

@@ -23,8 +23,8 @@ backticks read back as a fence — so a parse succeeding does not imply a spella
 `corpus/commonmark-spec/exceptions.json` names those.
 
 "Equals" is structural equality over editor-normal ADF — adjacent text nodes with identical marks
-merged, JSON number semantics, an empty attrs object, marks array or content array the absent
-key — the only domain markdown can restore.
+and no attributes merged, JSON number semantics, an empty attrs object, marks array or content
+array the absent key — the only domain markdown can restore.
 
 Round-trip equality is a property tested over a corpus, not a claim made in prose.
 
@@ -43,8 +43,11 @@ Round-trip equality is a property tested over a corpus, not a claim made in pros
 
 ## 4. The flavour
 
-- Directives, one grammar for everything markdown lacks: `:::panel info` … `:::` blocks,
-  `:mention[@Mikael]{id=5b10a2}` inline. Prior art: CommonMark's generic-directives proposal.
+- Directives, one grammar for everything markdown lacks, namespaced under `!adf:`: `!adf:panel info`
+  … `!adf:/panel` blocks, `!adf:mention[@Mikael]{id=5b10a2}` inline, `\!adf:` the one escape. Not
+  CommonMark's generic-directives proposal: its `:::` claims a form prose writes, and its
+  fence-length discipline ties a container's opener to its own body, where closing from the opener
+  nests by itself and leaf versus container falls out of the node's content model.
 - Plain CommonMark is a subset, with carve-outs (`spec/flavour.md`): literal text shaped like a
   directive, a pipe table or a `~~` pair is claimed — plus one image gap.
 - Tables: one header row plus plain inline cells → pipe table; anything richer → directive form.
@@ -63,8 +66,12 @@ module, so entity decoding is complete without one. The CommonMark spec suite is
 data and ships vendored at `corpus/commonmark-spec/` rather than as the `commonmark-spec` dev
 dependency — that package is CommonJS-only, and Renovate auto-bumping a spec version would silently
 point the vendored exception list's example numbers at a renumbered suite. A spec bump is a
-deliberate re-pin, exceptions re-derived by hand beside it. `devDependencies`: few, each earning its
-keep; they never reach a consumer.
+deliberate re-pin, exceptions re-derived by hand beside it. Atlassian's ADF JSON Schemas ship
+vendored the same way, at `spec/adf-schema/`, rather than as the `@atlaskit/adf-schema` dev
+dependency — CommonJS-only, some fifty packages with React among them, and a release most days for
+Renovate to automerge — re-pinned by hand when a payload or a report shows the need.
+`devDependencies`: few, each earning its keep; they never reach a consumer. `fast-check` earns its
+place shrinking a failing generated document to the nodes that break it.
 
 ## 6. The package contract
 
@@ -94,15 +101,17 @@ against the README's personas.
 
 The emitted markdown and HTML are contracts. After 1.0: previously-emitted output parsing
 differently, or not at all, is MAJOR; new syntax while old output still round-trips is MINOR.
-Pre-1.0, normal 0.x rules.
+Pre-1.0, normal 0.x rules. A spelled node's content model is part of that contract — leaf or
+container is the model, not the syntax — so giving a spelled node's model content it had not, or
+taking it away, is MAJOR whatever ADF's own schema does.
 
 The error surface is a contract too. `ConvertError` is `{ code, message, path, position? }` — the
 code from a closed list a consumer may switch exhaustively, the message free text, the path the
 node's place from the document root, the position where a parse read the refusal in its input.
 A message names the violation, not the rule alone — a rule by itself states a truth the reader
 must invert before it reads as a failure — and where the flavour's claim refuses ordinary prose it
-names the escape that unclaims the form claimed: `\:::` for a directive line, `\|` for every pipe
-row, `\:` for an inline directive.
+names the escape that unclaims the form claimed: `\!adf:` for a directive, block line and inline
+alike, `\|` for every pipe row.
 Adding, removing or renaming a code is breaking, so a milestone meeting a new failure cause
 reuses a code where one fits; the list is complete at `0.1.0`. A code names the
 cause; where one cause recurs across node types, across one mark's attributes or across
@@ -112,7 +121,7 @@ direction hits it, `unspellable-link` the destination and the title alike. Where
 apart, the line between them is what they name: `unspellable-character` is a character CommonMark
 rewrites wherever text holds it, `unspellable-whitespace` the newline no inline directive's
 content slot spans, in either direction. A claim code names the spelling claimed, never the node that spelling would have built:
-a malformed `:::table` is a `malformed-directive`, and an alignment colon a `malformed-pipe-table` —
+a malformed `!adf:table` is a `malformed-directive`, and an alignment colon a `malformed-pipe-table` —
 the flavour's own delimiter row is `-` runs, so the grammar refuses the colon rather than ADF's
 missing column model doing it. A refusal no spelling recovers from is a gap in the flavour rather
 than a code: give the flavour the spelling and the code goes, which the freeze is the last moment
@@ -121,8 +130,8 @@ spelling writes rides the carry with its node. A directive whose name reads back
 `unknown-directive-name` rather than a claim code — the spelling is well formed, and telling that
 apart from a typo is what a consumer switches on when a later MINOR gives the name meaning. A
 reserved name is a known name, so never that code, and the two the flavour reserves part on form:
-a form the grammar does not have is a claim code — `::adf`, whose carry is the fence — and a
-well-formed form in the wrong place is `unsupported-node-shape`, `::listBreak` parting anything
+a form the grammar does not have is a claim code — `!adf:carry`, whose carry is the fence — and a
+well-formed form in the wrong place is `unsupported-node-shape`, `!adf:listBreak` parting anything
 but two adjacent lists of one type. What
 the grammar itself refuses stays a claim code, key order among it; a well-formed directive the
 node tables refuse — an attribute a node does not hold or spells elsewhere, a value outside its
@@ -204,9 +213,10 @@ resolver maps them, under `NodeNext` alone; a `.d.ts` reader that is not `tsc` s
 `node-floor.js` round-trips the installed package under a Node pinned to `engines.node`'s floor.
 
 A fourth engine reads the build rather than the source: a headless Firefox loads `dist/index.js`
-over HTTP and converts the round-trip, normalization and error fixtures — the `commonmark-spec`
-sort is the Node suite's to check — which is §6's browser half and the only SpiderMonkey
-there is — the gate's other three engines are two V8s and a JavaScriptCore that is not Safari's.
+over HTTP and converts the round-trip, normalization and error fixtures and the real payloads —
+the `commonmark-spec` sort is the Node suite's to check — which is §6's browser half and the only
+SpiderMonkey there is — the gate's other three engines are two V8s and a JavaScriptCore that is
+not Safari's.
 A WebDriver session is what carries a verdict back out, the driver and the page's server sharing
 one network namespace so each is the other's `127.0.0.1`; `--headless --screenshot` has no such
 channel, and loading `dist/index.js` in a globals-stripped realm buys one by not running a browser.
@@ -219,9 +229,13 @@ functions, and a branch floor that only ever moves upward. It sits below 100 bec
 `noUncheckedIndexedAccess` and ADF's optional keys force — `?? []`, `?? {}`, `?.`, an index
 compared against `undefined` — have a half no valid document reaches.
 
-The corpus, all checked in: hand-built fixtures per node and combination; real sanitized ADF from
-live Atlassian APIs; property-generated ADF trees; the CommonMark spec suite against
-`markdownToAdf` and `markdownToHtml`.
+The corpus, all checked in: hand-built fixtures per node and combination; real ADF Atlassian's
+editor wrote; the CommonMark spec suite against `markdownToAdf` and `markdownToHtml`.
+
+Beside the corpus, properties run over documents generated from the node tables and over generated
+markdown, on a fixed seed in the gate; `PROPERTY_RUNS=<runs>` raises the runs and randomizes the
+seed for local digging, and a counterexample found becomes a round-trip fixture. The generators and
+run parameters properties share live in `src/property-harness.ts`, outside the build and coverage.
 
 `spec/flavour.md` is read as a source too, so the node tables cannot drift from the prose they
 copy: each `- ` bullet in `## Block nodes`, `## Inline nodes` and `## Marks` declares the nodes
@@ -231,6 +245,12 @@ of a bullet; fenced examples are skipped. It guards the attributes alone: nodes
 content model share a bullet, and the argument attribute is spelled ahead of `Attributes: `, so
 both answer to the round-trip corpus and to nothing else where a node has no fixture.
 
+The tables answer to Atlassian's schema too (§5): for every node and mark they spell, the attribute
+names and kinds equal what `full.json` and `stage-0.json` hold between them. Value sets stay
+documentation, since any value round-trips. What the schema holds and the tables do not spell is
+pinned by name — an attribute as a gap, a type as carried — so a re-pin adding either goes red until
+someone spells it or pins it.
+
 ## 11. Code rules
 
 - Two-space indent, strict TypeScript, English everywhere. Alphabetical order wherever order

browser-tests/convert-corpus.js

@@ -3,6 +3,11 @@ try {
   window.convertCorpus = (corpus) => ({
     errors: corpus.errors.map(({ markdown, name }) => ({ name, parsed: markdownToAdf(markdown) })),
     normalization: corpus.normalization.map(({ markdown, name }) => ({ name, parsed: markdownToAdf(markdown) })),
+    realPayloads: corpus.realPayloads.map(({ json, name }) => {
+      const adf = JSON.parse(json)
+      const emitted = adfToMarkdown(adf)
+      return { emitted, isDocument: isAdfDocument(adf), name, parsed: emitted.ok ? markdownToAdf(emitted.value) : undefined }
+    }),
     roundTrip: corpus.roundTrip.map(({ json, markdown, name }) => {
       const adf = JSON.parse(json)
       return { emitted: adfToMarkdown(adf), isDocument: isAdfDocument(adf), name, parsed: markdownToAdf(markdown) }

browser-tests/run.js

@@ -2,6 +2,7 @@ import assert from 'node:assert/strict'
 import { readFileSync, readdirSync } from 'node:fs'
 import { createServer } from 'node:http'
 import { extname, join } from 'node:path'
+import { toEditorNormal } from '../dist/adf/editor-normal.js'
 
 const contentTypes = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript' }
 const driver = 'http://127.0.0.1:4444'
@@ -66,6 +67,7 @@ async function whenDriverAnswers() {
 const corpus = {
   errors: fixtureNames('errors', '.md').map((name) => ({ markdown: fixture(name, '.md'), name })),
   normalization: fixtureNames('normalization', '.md').map((name) => ({ markdown: fixture(name, '.md'), name })),
+  realPayloads: fixtureNames('real-payloads', '.json').map((name) => ({ json: fixture(name, '.json'), name })),
   roundTrip: fixtureNames('round-trip', '.json').map((name) => ({ json: fixture(name, '.json'), markdown: fixture(name, '.md'), name })),
 }
 assert.deepEqual(
@@ -74,7 +76,7 @@ assert.deepEqual(
     .map((entry) => entry.name)
     .filter((name) => name !== 'commonmark-spec')
     .sort(),
-  ['errors', 'normalization', 'round-trip'],
+  ['errors', 'normalization', 'real-payloads', 'round-trip'],
   'a corpus kind the browser leg does not convert',
 )
 for (const [kind, fixtures] of Object.entries(corpus)) assert.ok(fixtures.length > 0, `the browser leg found no ${kind} fixture to convert`)
@@ -105,7 +107,7 @@ for (const [index, { json, markdown, name }] of corpus.roundTrip.entries()) {
     assert.ok(result.emitted.ok, `it did not emit — ${refusal(result.emitted)}`)
     assert.equal(result.emitted.value, markdown)
     assert.ok(result.parsed.ok, `it did not parse — ${refusal(result.parsed)}`)
-    assert.deepEqual(result.parsed.value, JSON.parse(json))
+    assert.deepEqual(toEditorNormal(result.parsed.value), JSON.parse(json))
   })
 }
 
@@ -113,7 +115,17 @@ for (const [index, { name }] of corpus.normalization.entries()) {
   const result = results.normalization[index]
   checking(name, result, () => {
     assert.ok(result.parsed.ok, `it did not parse — ${refusal(result.parsed)}`)
-    assert.deepEqual(result.parsed.value, JSON.parse(fixture(name, '.json')))
+    assert.deepEqual(toEditorNormal(result.parsed.value), JSON.parse(fixture(name, '.json')))
+  })
+}
+
+for (const [index, { json, name }] of corpus.realPayloads.entries()) {
+  const result = results.realPayloads[index]
+  checking(name, result, () => {
+    assert.ok(result.isDocument, `${name}.json is no ADF document`)
+    assert.ok(result.emitted.ok, `it did not emit — ${refusal(result.emitted)}`)
+    assert.ok(result.parsed.ok, `it did not parse back — ${refusal(result.parsed)}`)
+    assert.deepEqual(toEditorNormal(result.parsed.value), JSON.parse(json))
   })
 }
 
@@ -126,5 +138,5 @@ for (const [index, { name }] of corpus.errors.entries()) {
 }
 
 console.log(
-  `Firefox ${session.capabilities.browserVersion} converted ${corpus.roundTrip.length} round-trip, ${corpus.normalization.length} normalization and ${corpus.errors.length} error fixtures`,
+  `Firefox ${session.capabilities.browserVersion} converted ${corpus.roundTrip.length} round-trip, ${corpus.normalization.length} normalization and ${corpus.errors.length} error fixtures and ${corpus.realPayloads.length} real payloads`,
 )

ci.sh

@@ -16,7 +16,7 @@ if printf '%s' "$test_output" | grep -q 'ℹ tests 0'; then
   exit 1
 fi
 
-in_image "$deno_image" deno test --allow-read --no-check src/
+in_image "$deno_image" deno test --allow-env=PROPERTY_RUNS --allow-read --no-check src/
 in_image "$bun_image" bun test src/
 
 in_image "$node_image" npm run build

corpus/README.md

@@ -10,8 +10,8 @@ One directory per contract kind, each landing with its milestone:
   markdown is not canonical.
 - `errors/` — `<name>.md`: markdown input that must not convert. A `<name>.error` beside it
   pins which error.
-- `real-payloads/` — `<name>.json`: sanitized live ADF, round-tripped ADF→markdown→ADF. No
-  expected markdown.
+- `real-payloads/` — `<name>.json`: ADF Atlassian's editor wrote, round-tripped ADF→markdown→ADF.
+  No expected markdown.
 - `commonmark-spec/` — the CommonMark suite run against `markdownToAdf` by three checks. `spec.json`
   is the suite; `refusals.json` pins each refusing example to its error `code`; `exceptions.json`
   pins each known divergence by `check`, `example`, `kind` and the exact `divergence`, with a

corpus/real-payloads/code-blocks.json

@@ -0,0 +1,173 @@
+{
+  "content": [
+    {
+      "attrs": {
+        "level": 2,
+        "localId": "0d42e7ff24ba"
+      },
+      "content": [
+        {
+          "text": "Code blocks",
+          "type": "text"
+        }
+      ],
+      "type": "heading"
+    },
+    {
+      "attrs": {
+        "localId": "a971506228e7"
+      },
+      "content": [
+        {
+          "text": "Run the setup once, then start the server with ",
+          "type": "text"
+        },
+        {
+          "marks": [
+            {
+              "type": "code"
+            }
+          ],
+          "text": "npm start",
+          "type": "text"
+        },
+        {
+          "text": " and open the page.",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "language": "javascript",
+        "localId": "eaf42046-6454-451d-ab13-8bd5ed2333bb",
+        "wrap": true
+      },
+      "content": [
+        {
+          "text": "function greet(name) {\n  return `Hello, ${name}!`\n}",
+          "type": "text"
+        }
+      ],
+      "type": "codeBlock"
+    },
+    {
+      "attrs": {
+        "localId": "d69616dee641"
+      },
+      "content": [
+        {
+          "text": "The same idea in Python:",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "language": "python",
+        "localId": "2094b559-280a-49d5-9be3-182572e5d2d8",
+        "wrap": true
+      },
+      "content": [
+        {
+          "text": "def total(prices):\n    return sum(prices)\n\nprint(total([3, 4.5]))",
+          "type": "text"
+        }
+      ],
+      "type": "codeBlock"
+    },
+    {
+      "attrs": {
+        "localId": "abe1971d1f18"
+      },
+      "content": [
+        {
+          "text": "A query that lists visitors by city:",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "language": "sql",
+        "localId": "5551dc8e-8fe0-455e-a9cf-22e48b589fe8",
+        "wrap": true
+      },
+      "content": [
+        {
+          "text": "SELECT name, city\nFROM visitors\nWHERE city = 'Lund'\nORDER BY name;",
+          "type": "text"
+        }
+      ],
+      "type": "codeBlock"
+    },
+    {
+      "attrs": {
+        "localId": "51efdd2f1f02"
+      },
+      "content": [
+        {
+          "text": "Plain output, no language chosen:",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "localId": "d0f83c92-c252-4a70-9e31-dfb5ac255cd1",
+        "wrap": true
+      },
+      "content": [
+        {
+          "text": "$ ./setup\nChecking folders... done\n  3 files copied",
+          "type": "text"
+        }
+      ],
+      "type": "codeBlock"
+    },
+    {
+      "attrs": {
+        "localId": "3dac57e146fa"
+      },
+      "content": [
+        {
+          "text": "Keep ",
+          "type": "text"
+        },
+        {
+          "marks": [
+            {
+              "type": "code"
+            }
+          ],
+          "text": ".env",
+          "type": "text"
+        },
+        {
+          "text": " files out of version control, and never paste a ",
+          "type": "text"
+        },
+        {
+          "marks": [
+            {
+              "type": "code"
+            }
+          ],
+          "text": "password",
+          "type": "text"
+        },
+        {
+          "text": " into a ticket.",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    }
+  ],
+  "type": "doc",
+  "version": 1
+}

corpus/real-payloads/inline-nodes.json

@@ -0,0 +1,254 @@
+{
+  "content": [
+    {
+      "attrs": {
+        "level": 2,
+        "localId": "0fcbc98aec1f"
+      },
+      "content": [
+        {
+          "text": "Where things stand",
+          "type": "text"
+        }
+      ],
+      "type": "heading"
+    },
+    {
+      "attrs": {
+        "localId": "32b6266eb05c"
+      },
+      "content": [
+        {
+          "text": "Office move ",
+          "type": "text"
+        },
+        {
+          "attrs": {
+            "color": "blue",
+            "localId": "1ab19511-a0fa-41a1-b6d0-6729813c0526",
+            "style": "mixedCase",
+            "text": "In progress"
+          },
+          "type": "status"
+        },
+        {
+          "text": "  since ",
+          "type": "text"
+        },
+        {
+          "attrs": {
+            "localId": "493624162706",
+            "timestamp": "1790812800000"
+          },
+          "type": "date"
+        },
+        {
+          "text": " , owned by ",
+          "type": "text"
+        },
+        {
+          "attrs": {
+            "accessLevel": "",
+            "id": "712020:78bf5058-bc76-4783-99af-6d70cb593cee",
+            "localId": "604060e1-e533-4019-aa28-21952dfdea19",
+            "text": "@Larvit Developer"
+          },
+          "type": "mention"
+        },
+        {
+          "text": " .",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "localId": "73a94328c89f"
+      },
+      "content": [
+        {
+          "text": "Furniture ",
+          "type": "text"
+        },
+        {
+          "attrs": {
+            "color": "green",
+            "localId": "7b27ff33-1483-452b-8982-311cf9429023",
+            "style": "mixedCase",
+            "text": "Done"
+          },
+          "type": "status"
+        },
+        {
+          "text": " , cabling ",
+          "type": "text"
+        },
+        {
+          "attrs": {
+            "color": "red",
+            "localId": "b6eb05a9-e0e7-4269-9cbd-e912640364a6",
+            "style": "mixedCase",
+            "text": "Blocked"
+          },
+          "type": "status"
+        },
+        {
+          "text": " , signage ",
+          "type": "text"
+        },
+        {
+          "attrs": {
+            "color": "yellow",
+            "localId": "ff7ed7fb-1846-48cb-b5ea-8be6b598ccc6",
+            "style": "mixedCase",
+            "text": "Waiting"
+          },
+          "type": "status"
+        },
+        {
+          "text": " , parking ",
+          "type": "text"
+        },
+        {
+          "attrs": {
+            "color": "purple",
+            "localId": "e9218ff4-6fcb-4e43-b36a-b1bef8a19376",
+            "style": "mixedCase",
+            "text": "Maybe"
+          },
+          "type": "status"
+        },
+        {
+          "text": "  and keys ",
+          "type": "text"
+        },
+        {
+          "attrs": {
+            "color": "neutral",
+            "localId": "f1455340-2469-4bc6-a371-ed6b1f54386c",
+            "style": "mixedCase",
+            "text": "Not started"
+          },
+          "type": "status"
+        },
+        {
+          "text": " ",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "localId": "8d9e2dc70265"
+      },
+      "content": [
+        {
+          "attrs": {
+            "accessLevel": "",
+            "id": "712020:78bf5058-bc76-4783-99af-6d70cb593cee",
+            "localId": "ab5b7997-43ce-4238-b540-db3864e0965c",
+            "text": "@Larvit Developer"
+          },
+          "type": "mention"
+        },
+        {
+          "text": " please confirm the handover on ",
+          "type": "text"
+        },
+        {
+          "attrs": {
+            "localId": "77e2bdefa7fd",
+            "timestamp": "1795132800000"
+          },
+          "type": "date"
+        },
+        {
+          "text": "  before lunch.",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "localId": "f7fb8a7527a3"
+      },
+      "content": [
+        {
+          "text": "Great work so far ",
+          "type": "text"
+        },
+        {
+          "attrs": {
+            "id": "1f44d",
+            "localId": "8fe9a02e94ce",
+            "shortName": ":thumbsup:",
+            "text": "👍"
+          },
+          "type": "emoji"
+        },
+        {
+          "text": " and thanks for the snacks ",
+          "type": "text"
+        },
+        {
+          "attrs": {
+            "id": "1f389",
+            "localId": "c19496cc742f",
+            "shortName": ":tada:",
+            "text": "🎉"
+          },
+          "type": "emoji"
+        },
+        {
+          "text": " ",
+          "type": "text"
+        },
+        {
+          "attrs": {
+            "id": "1f600",
+            "localId": "c05a6757d0ee",
+            "shortName": ":grinning:",
+            "text": "😀"
+          },
+          "type": "emoji"
+        },
+        {
+          "text": " ",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "localId": "b75918031ebd"
+      },
+      "content": [
+        {
+          "text": "Deliveries go to:",
+          "type": "text"
+        },
+        {
+          "type": "hardBreak"
+        },
+        {
+          "text": "Building C, third floor",
+          "type": "text"
+        },
+        {
+          "type": "hardBreak"
+        },
+        {
+          "text": "Ring the bell twice",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    }
+  ],
+  "type": "doc",
+  "version": 1
+}

corpus/real-payloads/lists-and-blocks.json

@@ -0,0 +1,527 @@
+{
+  "content": [
+    {
+      "attrs": {
+        "level": 1,
+        "localId": "cfdcc54363d9"
+      },
+      "content": [
+        {
+          "text": "Project handbook",
+          "type": "text"
+        }
+      ],
+      "type": "heading"
+    },
+    {
+      "attrs": {
+        "localId": "91177a27b0ff"
+      },
+      "content": [
+        {
+          "text": "Welcome to the handbook for the spring project.",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "level": 2,
+        "localId": "7e7d9113a89b"
+      },
+      "content": [
+        {
+          "text": "Getting started",
+          "type": "text"
+        }
+      ],
+      "type": "heading"
+    },
+    {
+      "attrs": {
+        "localId": "e65711ca96b6"
+      },
+      "content": [
+        {
+          "text": "Pack the following before the first day:",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "localId": "b5c36c57fe79"
+      },
+      "content": [
+        {
+          "attrs": {
+            "localId": "1f4aa02de452"
+          },
+          "content": [
+            {
+              "attrs": {
+                "localId": "8993e22a13aa"
+              },
+              "content": [
+                {
+                  "text": "Laptop",
+                  "type": "text"
+                }
+              ],
+              "type": "paragraph"
+            },
+            {
+              "attrs": {
+                "localId": "2b335a4504ab"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "c9180347caf0"
+                  },
+                  "content": [
+                    {
+                      "attrs": {
+                        "localId": "60990e48da32"
+                      },
+                      "content": [
+                        {
+                          "text": "Charger",
+                          "type": "text"
+                        }
+                      ],
+                      "type": "paragraph"
+                    }
+                  ],
+                  "type": "listItem"
+                },
+                {
+                  "attrs": {
+                    "localId": "fc5d4c8a875d"
+                  },
+                  "content": [
+                    {
+                      "attrs": {
+                        "localId": "3b8ec5318463"
+                      },
+                      "content": [
+                        {
+                          "text": "Mouse",
+                          "type": "text"
+                        }
+                      ],
+                      "type": "paragraph"
+                    }
+                  ],
+                  "type": "listItem"
+                }
+              ],
+              "type": "bulletList"
+            }
+          ],
+          "type": "listItem"
+        },
+        {
+          "attrs": {
+            "localId": "90f5f37a8a8f"
+          },
+          "content": [
+            {
+              "attrs": {
+                "localId": "90fab5a310c5"
+              },
+              "content": [
+                {
+                  "text": "Notebook",
+                  "type": "text"
+                }
+              ],
+              "type": "paragraph"
+            },
+            {
+              "attrs": {
+                "localId": "46840b8bd24b",
+                "order": 1
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "b4f06fbd15ef"
+                  },
+                  "content": [
+                    {
+                      "attrs": {
+                        "localId": "93db4583bdba"
+                      },
+                      "content": [
+                        {
+                          "text": "Lined for notes",
+                          "type": "text"
+                        }
+                      ],
+                      "type": "paragraph"
+                    }
+                  ],
+                  "type": "listItem"
+                },
+                {
+                  "attrs": {
+                    "localId": "6904c80dd06d"
+                  },
+                  "content": [
+                    {
+                      "attrs": {
+                        "localId": "0bc1c819d38d"
+                      },
+                      "content": [
+                        {
+                          "text": "Squared for sketches",
+                          "type": "text"
+                        }
+                      ],
+                      "type": "paragraph"
+                    }
+                  ],
+                  "type": "listItem"
+                }
+              ],
+              "type": "orderedList"
+            }
+          ],
+          "type": "listItem"
+        },
+        {
+          "attrs": {
+            "localId": "65bd0afce26e"
+          },
+          "content": [
+            {
+              "attrs": {
+                "localId": "a753e5ecdad3"
+              },
+              "content": [
+                {
+                  "text": "Water bottle",
+                  "type": "text"
+                }
+              ],
+              "type": "paragraph"
+            }
+          ],
+          "type": "listItem"
+        }
+      ],
+      "type": "bulletList"
+    },
+    {
+      "attrs": {
+        "level": 3,
+        "localId": "5b6a671499c5"
+      },
+      "content": [
+        {
+          "text": "Unpacking",
+          "type": "text"
+        }
+      ],
+      "type": "heading"
+    },
+    {
+      "attrs": {
+        "localId": "f460abd3a962"
+      },
+      "content": [
+        {
+          "text": "The first two steps happen at reception, so ours start at three:",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "localId": "baf0046a0432",
+        "order": 3
+      },
+      "content": [
+        {
+          "attrs": {
+            "localId": "b4df865a31a9"
+          },
+          "content": [
+            {
+              "attrs": {
+                "localId": "3f1b32f952d0"
+              },
+              "content": [
+                {
+                  "text": "Unpack the boxes",
+                  "type": "text"
+                }
+              ],
+              "type": "paragraph"
+            }
+          ],
+          "type": "listItem"
+        },
+        {
+          "attrs": {
+            "localId": "f64930d87d4e"
+          },
+          "content": [
+            {
+              "attrs": {
+                "localId": "d953389c865a"
+              },
+              "content": [
+                {
+                  "text": "Label the shelves",
+                  "type": "text"
+                }
+              ],
+              "type": "paragraph"
+            }
+          ],
+          "type": "listItem"
+        },
+        {
+          "attrs": {
+            "localId": "840daad9cb43"
+          },
+          "content": [
+            {
+              "attrs": {
+                "localId": "8708b8c7aeec"
+              },
+              "content": [
+                {
+                  "text": "Recycle the cardboard",
+                  "type": "text"
+                }
+              ],
+              "type": "paragraph"
+            }
+          ],
+          "type": "listItem"
+        }
+      ],
+      "type": "orderedList"
+    },
+    {
+      "attrs": {
+        "level": 4,
+        "localId": "27d1d408ae3e"
+      },
+      "content": [
+        {
+          "text": "Shelf labels",
+          "type": "text"
+        }
+      ],
+      "type": "heading"
+    },
+    {
+      "attrs": {
+        "localId": "8b5cf239dbb5",
+        "order": 1
+      },
+      "content": [
+        {
+          "attrs": {
+            "localId": "0948562abdc3"
+          },
+          "content": [
+            {
+              "attrs": {
+                "localId": "4da9d4f45923"
+              },
+              "content": [
+                {
+                  "text": "Top shelf",
+                  "type": "text"
+                }
+              ],
+              "type": "paragraph"
+            },
+            {
+              "attrs": {
+                "localId": "36edf97d8e2c"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "7915e252429c"
+                  },
+                  "content": [
+                    {
+                      "attrs": {
+                        "localId": "9b15cc9fa8a1"
+                      },
+                      "content": [
+                        {
+                          "text": "Binders",
+                          "type": "text"
+                        }
+                      ],
+                      "type": "paragraph"
+                    }
+                  ],
+                  "type": "listItem"
+                },
+                {
+                  "attrs": {
+                    "localId": "efe607ab9e41"
+                  },
+                  "content": [
+                    {
+                      "attrs": {
+                        "localId": "d559a2f29321"
+                      },
+                      "content": [
+                        {
+                          "text": "Archive boxes",
+                          "type": "text"
+                        }
+                      ],
+                      "type": "paragraph"
+                    }
+                  ],
+                  "type": "listItem"
+                }
+              ],
+              "type": "bulletList"
+            }
+          ],
+          "type": "listItem"
+        },
+        {
+          "attrs": {
+            "localId": "229692097876"
+          },
+          "content": [
+            {
+              "attrs": {
+                "localId": "928b1862c273"
+              },
+              "content": [
+                {
+                  "text": "Bottom shelf",
+                  "type": "text"
+                }
+              ],
+              "type": "paragraph"
+            }
+          ],
+          "type": "listItem"
+        }
+      ],
+      "type": "orderedList"
+    },
+    {
+      "attrs": {
+        "level": 5,
+        "localId": "353a84ef9126"
+      },
+      "content": [
+        {
+          "text": "Quiet hours",
+          "type": "text"
+        }
+      ],
+      "type": "heading"
+    },
+    {
+      "attrs": {
+        "localId": "9c11b949ed48"
+      },
+      "content": [
+        {
+          "attrs": {
+            "localId": "bd576489e8b6"
+          },
+          "content": [
+            {
+              "text": "Good tools make good work, and quiet rooms make good thinking.",
+              "type": "text"
+            }
+          ],
+          "type": "paragraph"
+        },
+        {
+          "attrs": {
+            "localId": "727fda576a9d"
+          },
+          "content": [
+            {
+              "text": "Please keep calls in the booths.",
+              "type": "text"
+            }
+          ],
+          "type": "paragraph"
+        }
+      ],
+      "type": "blockquote"
+    },
+    {
+      "attrs": {
+        "level": 6,
+        "localId": "b12277440bc7"
+      },
+      "content": [
+        {
+          "text": "Small print",
+          "type": "text"
+        }
+      ],
+      "type": "heading"
+    },
+    {
+      "attrs": {
+        "localId": "9f6fbb5a19af"
+      },
+      "type": "rule"
+    },
+    {
+      "attrs": {
+        "localId": "8a6e253c110e"
+      },
+      "content": [
+        {
+          "text": "Office hours:",
+          "type": "text"
+        },
+        {
+          "type": "hardBreak"
+        },
+        {
+          "text": "Monday to Thursday, eight to five",
+          "type": "text"
+        },
+        {
+          "type": "hardBreak"
+        },
+        {
+          "text": "Friday, eight to three",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "localId": "b9c3f5daa373"
+      },
+      "content": [
+        {
+          "text": "That is all for now.",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    }
+  ],
+  "type": "doc",
+  "version": 1
+}

corpus/real-payloads/media.json

@@ -0,0 +1,106 @@
+{
+  "content": [
+    {
+      "attrs": {
+        "level": 2,
+        "localId": "d5c3a2503683"
+      },
+      "content": [
+        {
+          "text": "Media and attachments",
+          "type": "text"
+        }
+      ],
+      "type": "heading"
+    },
+    {
+      "attrs": {
+        "localId": "f71287760586"
+      },
+      "content": [
+        {
+          "text": "A photo of the meadow behind the office:",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "layout": "align-start",
+        "localId": "95de25bcdecc",
+        "width": 320,
+        "widthType": "pixel"
+      },
+      "content": [
+        {
+          "attrs": {
+            "alt": "Green meadow under a yellow sun",
+            "collection": "",
+            "height": 180,
+            "id": "8c586460-fb0d-44f6-949f-d800d5dd0f45",
+            "localId": "630d0d0457b8",
+            "type": "file",
+            "width": 320
+          },
+          "marks": [
+            {
+              "attrs": {
+                "color": "#091e4224",
+                "size": 2
+              },
+              "type": "border"
+            }
+          ],
+          "type": "media"
+        }
+      ],
+      "type": "mediaSingle"
+    },
+    {
+      "attrs": {
+        "localId": "b4bfee3ad3ec"
+      },
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "localId": "ffe5710ea995"
+      },
+      "content": [
+        {
+          "text": "The packing list is attached as a file:",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "content": [
+        {
+          "attrs": {
+            "collection": "",
+            "id": "8dfd7046-2382-4377-b3ba-ec31e34cd01a",
+            "type": "file"
+          },
+          "type": "media"
+        }
+      ],
+      "type": "mediaGroup"
+    },
+    {
+      "attrs": {
+        "localId": "77fcb609f709"
+      },
+      "content": [
+        {
+          "text": "Both were uploaded from the editor.",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    }
+  ],
+  "type": "doc",
+  "version": 1
+}

corpus/real-payloads/panels-and-expands.json

@@ -0,0 +1,292 @@
+{
+  "content": [
+    {
+      "attrs": {
+        "level": 2,
+        "localId": "d483ec27f809"
+      },
+      "content": [
+        {
+          "text": "Panels",
+          "type": "text"
+        }
+      ],
+      "type": "heading"
+    },
+    {
+      "attrs": {
+        "localId": "cb02f8e9812b"
+      },
+      "content": [
+        {
+          "text": "Each colour of panel below holds a short note for the visiting team.",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "localId": "b6d76c21e77e",
+        "panelType": "info"
+      },
+      "content": [
+        {
+          "attrs": {
+            "localId": "2d871d80f6e1"
+          },
+          "content": [
+            {
+              "text": "The workshop starts at nine in the morning.",
+              "type": "text"
+            }
+          ],
+          "type": "paragraph"
+        }
+      ],
+      "type": "panel"
+    },
+    {
+      "attrs": {
+        "localId": "cbaab515445c",
+        "panelType": "note"
+      },
+      "content": [
+        {
+          "attrs": {
+            "localId": "13cafc26c42d"
+          },
+          "content": [
+            {
+              "text": "Bring your own laptop charger.",
+              "type": "text"
+            }
+          ],
+          "type": "paragraph"
+        }
+      ],
+      "type": "panel"
+    },
+    {
+      "attrs": {
+        "localId": "c5fa8b34e2aa",
+        "panelType": "success"
+      },
+      "content": [
+        {
+          "attrs": {
+            "localId": "e186fca354d9"
+          },
+          "content": [
+            {
+              "text": "All rooms are booked for the week.",
+              "type": "text"
+            }
+          ],
+          "type": "paragraph"
+        }
+      ],
+      "type": "panel"
+    },
+    {
+      "attrs": {
+        "localId": "ee223a0f886e",
+        "panelType": "warning"
+      },
+      "content": [
+        {
+          "attrs": {
+            "localId": "e0006fb2b972"
+          },
+          "content": [
+            {
+              "text": "The east entrance closes early on Fridays.",
+              "type": "text"
+            }
+          ],
+          "type": "paragraph"
+        },
+        {
+          "attrs": {
+            "localId": "ea6a56b9c863"
+          },
+          "content": [
+            {
+              "text": "Use the main door after four.",
+              "type": "text"
+            }
+          ],
+          "type": "paragraph"
+        }
+      ],
+      "type": "panel"
+    },
+    {
+      "attrs": {
+        "localId": "fedbadc6d1c7",
+        "panelType": "error"
+      },
+      "content": [
+        {
+          "attrs": {
+            "localId": "c0f6122d81b7"
+          },
+          "content": [
+            {
+              "text": "The projector in room two is out of order.",
+              "type": "text"
+            }
+          ],
+          "type": "paragraph"
+        }
+      ],
+      "type": "panel"
+    },
+    {
+      "attrs": {
+        "level": 2,
+        "localId": "afe638de11c5"
+      },
+      "content": [
+        {
+          "text": "Expands",
+          "type": "text"
+        }
+      ],
+      "type": "heading"
+    },
+    {
+      "attrs": {
+        "localId": "e635bf2eac43",
+        "title": "Agenda for the first day"
+      },
+      "content": [
+        {
+          "attrs": {
+            "localId": "c8beb4c392ee"
+          },
+          "content": [
+            {
+              "attrs": {
+                "localId": "6d6ff472d878"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "d1186101c5a1"
+                  },
+                  "content": [
+                    {
+                      "text": "Welcome and introductions",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "listItem"
+            },
+            {
+              "attrs": {
+                "localId": "01d203b97343"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "61bfec91218d"
+                  },
+                  "content": [
+                    {
+                      "text": "Tour of the building",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "listItem"
+            },
+            {
+              "attrs": {
+                "localId": "004e47604c2a"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "726aa40e1e38"
+                  },
+                  "content": [
+                    {
+                      "text": "Lunch in the courtyard",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "listItem"
+            }
+          ],
+          "type": "bulletList"
+        }
+      ],
+      "type": "expand"
+    },
+    {
+      "attrs": {
+        "localId": "cb6e48b9d746"
+      },
+      "content": [
+        {
+          "text": "Questions go to the organisers before the event.",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "localId": "32a8832682b2",
+        "title": "Travel details"
+      },
+      "content": [
+        {
+          "attrs": {
+            "localId": "00b05814cccb"
+          },
+          "content": [
+            {
+              "text": "Trains leave the central station every twenty minutes.",
+              "type": "text"
+            }
+          ],
+          "type": "paragraph"
+        },
+        {
+          "attrs": {
+            "localId": "eec0df0ed4f1",
+            "panelType": "note"
+          },
+          "content": [
+            {
+              "attrs": {
+                "localId": "712c49fa7ecc"
+              },
+              "content": [
+                {
+                  "text": "Tickets are cheaper before seven.",
+                  "type": "text"
+                }
+              ],
+              "type": "paragraph"
+            }
+          ],
+          "type": "panel"
+        }
+      ],
+      "type": "expand"
+    }
+  ],
+  "type": "doc",
+  "version": 1
+}

corpus/real-payloads/release-planning-notes.json

@@ -0,0 +1,630 @@
+{
+  "content": [
+    {
+      "attrs": {
+        "localId": "3b911072ce78"
+      },
+      "content": [
+        {
+          "text": "Summary of the planning session on Thursday. Attendees: ",
+          "type": "text"
+        },
+        {
+          "attrs": {
+            "accessLevel": "",
+            "id": "712020:78bf5058-bc76-4783-99af-6d70cb593cee",
+            "localId": "c8b64b9f-d396-4525-9456-38cf690ade1e",
+            "text": "@Larvit Developer"
+          },
+          "type": "mention"
+        },
+        {
+          "text": " and two guests from the design team.",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "level": 2,
+        "localId": "3e97ef36cbc3"
+      },
+      "content": [
+        {
+          "text": "Where we are",
+          "type": "text"
+        }
+      ],
+      "type": "heading"
+    },
+    {
+      "attrs": {
+        "localId": "530e0e3aa621"
+      },
+      "content": [
+        {
+          "text": "The beta is ",
+          "type": "text"
+        },
+        {
+          "attrs": {
+            "color": "green",
+            "localId": "ac0975eb-fafe-44ad-8293-8a12fdbcaebc",
+            "style": "mixedCase",
+            "text": "On track"
+          },
+          "type": "status"
+        },
+        {
+          "text": "  and the public launch is set for ",
+          "type": "text"
+        },
+        {
+          "attrs": {
+            "localId": "84d9a1cde860",
+            "timestamp": "1793664000000"
+          },
+          "type": "date"
+        },
+        {
+          "text": " .",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "localId": "ffcd53578640",
+        "panelType": "warning"
+      },
+      "content": [
+        {
+          "attrs": {
+            "localId": "0f0e8b9e13bb"
+          },
+          "content": [
+            {
+              "text": "Translation files are still ",
+              "type": "text"
+            },
+            {
+              "marks": [
+                {
+                  "type": "strong"
+                }
+              ],
+              "text": "missing",
+              "type": "text"
+            },
+            {
+              "text": " for two languages.",
+              "type": "text"
+            }
+          ],
+          "type": "paragraph"
+        }
+      ],
+      "type": "panel"
+    },
+    {
+      "attrs": {
+        "level": 2,
+        "localId": "d9b590d479ad"
+      },
+      "content": [
+        {
+          "text": "Decisions",
+          "type": "text"
+        }
+      ],
+      "type": "heading"
+    },
+    {
+      "attrs": {
+        "localId": "69dc2d52-34f7-43bb-8d6c-36d52a47179e"
+      },
+      "content": [
+        {
+          "attrs": {
+            "localId": "852a35a7-f660-4161-85dd-2d54adaf662b",
+            "state": "DECIDED"
+          },
+          "content": [
+            {
+              "text": "Ship the beta to internal users first",
+              "type": "text"
+            }
+          ],
+          "type": "decisionItem"
+        },
+        {
+          "attrs": {
+            "localId": "2df16457-331f-4d26-90ba-539f82949d70",
+            "state": "DECIDED"
+          },
+          "content": [
+            {
+              "text": "Keep the old export for one more release",
+              "type": "text"
+            }
+          ],
+          "type": "decisionItem"
+        }
+      ],
+      "type": "decisionList"
+    },
+    {
+      "attrs": {
+        "level": 2,
+        "localId": "7813370b5e89"
+      },
+      "content": [
+        {
+          "text": "Next steps",
+          "type": "text"
+        }
+      ],
+      "type": "heading"
+    },
+    {
+      "attrs": {
+        "localId": "21a7a33c-199d-4396-a148-c8404f70554f"
+      },
+      "content": [
+        {
+          "attrs": {
+            "localId": "5343dfdb-e70d-4ce6-bca5-8a382123c7bd",
+            "state": "TODO"
+          },
+          "content": [
+            {
+              "text": "Draft the release notes",
+              "type": "text"
+            }
+          ],
+          "type": "taskItem"
+        },
+        {
+          "attrs": {
+            "localId": "67d65eb8-17e9-4cd6-93cb-7d495f84e01d",
+            "state": "TODO"
+          },
+          "content": [
+            {
+              "text": "Book the demo room",
+              "type": "text"
+            }
+          ],
+          "type": "taskItem"
+        }
+      ],
+      "type": "taskList"
+    },
+    {
+      "attrs": {
+        "level": 2,
+        "localId": "e5806b037d61"
+      },
+      "content": [
+        {
+          "text": "Numbers",
+          "type": "text"
+        }
+      ],
+      "type": "heading"
+    },
+    {
+      "attrs": {
+        "isNumberColumnEnabled": false,
+        "layout": "align-start",
+        "localId": "cbae6bea-3c35-42b9-9a8f-3b37749e1a87"
+      },
+      "content": [
+        {
+          "attrs": {
+            "localId": "e4d343447bf5"
+          },
+          "content": [
+            {
+              "attrs": {
+                "localId": "4fcec7ad0a0f"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "974849d6e63c"
+                  },
+                  "content": [
+                    {
+                      "marks": [
+                        {
+                          "type": "strong"
+                        }
+                      ],
+                      "text": "Metric",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableHeader"
+            },
+            {
+              "attrs": {
+                "localId": "42df5203769e"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "8b0da0854a0a"
+                  },
+                  "content": [
+                    {
+                      "marks": [
+                        {
+                          "type": "strong"
+                        }
+                      ],
+                      "text": "Beta",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableHeader"
+            },
+            {
+              "attrs": {
+                "localId": "cbdae6c8508d"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "2584f222d6c3"
+                  },
+                  "content": [
+                    {
+                      "marks": [
+                        {
+                          "type": "strong"
+                        }
+                      ],
+                      "text": "Goal",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableHeader"
+            }
+          ],
+          "type": "tableRow"
+        },
+        {
+          "attrs": {
+            "localId": "65e4d7a700c0"
+          },
+          "content": [
+            {
+              "attrs": {
+                "localId": "a37175350eea"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "7efe32972497"
+                  },
+                  "content": [
+                    {
+                      "text": "Sign-ups",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableCell"
+            },
+            {
+              "attrs": {
+                "localId": "e0a95cdbd3c5"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "4628a3afe71b"
+                  },
+                  "content": [
+                    {
+                      "text": "140",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableCell"
+            },
+            {
+              "attrs": {
+                "localId": "b802fc652961"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "94c6ec93acb2"
+                  },
+                  "content": [
+                    {
+                      "text": "200",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableCell"
+            }
+          ],
+          "type": "tableRow"
+        },
+        {
+          "attrs": {
+            "localId": "bd6465cc546d"
+          },
+          "content": [
+            {
+              "attrs": {
+                "localId": "b6dcef3c6ac5"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "ba5c99353d30"
+                  },
+                  "content": [
+                    {
+                      "text": "Crash reports",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableCell"
+            },
+            {
+              "attrs": {
+                "localId": "554b7b5a8e71"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "569a134488bc"
+                  },
+                  "content": [
+                    {
+                      "text": "3",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableCell"
+            },
+            {
+              "attrs": {
+                "localId": "fb03db2017b1"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "c0ce0ada482c"
+                  },
+                  "content": [
+                    {
+                      "text": "0",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableCell"
+            }
+          ],
+          "type": "tableRow"
+        }
+      ],
+      "type": "table"
+    },
+    {
+      "attrs": {
+        "localId": "b4eb1362eb9f"
+      },
+      "content": [
+        {
+          "text": "The flag that turns the beta on:",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "language": "yaml",
+        "localId": "14298a36-6632-458f-a548-7fccd4b7186b",
+        "wrap": true
+      },
+      "content": [
+        {
+          "text": "beta:\n  enabled: true\n  audience: internal",
+          "type": "text"
+        }
+      ],
+      "type": "codeBlock"
+    },
+    {
+      "attrs": {
+        "localId": "a98274e22eaa"
+      },
+      "content": [
+        {
+          "text": "Risks we talked about:",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "localId": "fb3e387688ff"
+      },
+      "content": [
+        {
+          "attrs": {
+            "localId": "fdeee4ce0678"
+          },
+          "content": [
+            {
+              "attrs": {
+                "localId": "5ff2e05f1c7e"
+              },
+              "content": [
+                {
+                  "text": "Late translations",
+                  "type": "text"
+                }
+              ],
+              "type": "paragraph"
+            }
+          ],
+          "type": "listItem"
+        },
+        {
+          "attrs": {
+            "localId": "043a7ded718e"
+          },
+          "content": [
+            {
+              "attrs": {
+                "localId": "73a4d8e4ef0d"
+              },
+              "content": [
+                {
+                  "text": "The holiday week",
+                  "type": "text"
+                }
+              ],
+              "type": "paragraph"
+            },
+            {
+              "attrs": {
+                "localId": "3e32c1b868a1"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "98969cd5548e"
+                  },
+                  "content": [
+                    {
+                      "attrs": {
+                        "localId": "3b9989413325"
+                      },
+                      "content": [
+                        {
+                          "text": "Half the team is away",
+                          "type": "text"
+                        }
+                      ],
+                      "type": "paragraph"
+                    }
+                  ],
+                  "type": "listItem"
+                }
+              ],
+              "type": "bulletList"
+            }
+          ],
+          "type": "listItem"
+        }
+      ],
+      "type": "bulletList"
+    },
+    {
+      "attrs": {
+        "localId": "ba7d8422f4c6"
+      },
+      "content": [
+        {
+          "attrs": {
+            "localId": "a6837cfad3f5"
+          },
+          "content": [
+            {
+              "text": "Small steps, shipped often.",
+              "type": "text"
+            }
+          ],
+          "type": "paragraph"
+        }
+      ],
+      "type": "blockquote"
+    },
+    {
+      "attrs": {
+        "localId": "6ec9ef8df224"
+      },
+      "content": [
+        {
+          "text": "Thanks, everyone ",
+          "type": "text"
+        },
+        {
+          "attrs": {
+            "id": "1f389",
+            "localId": "2481c60576e0",
+            "shortName": ":tada:",
+            "text": "🎉"
+          },
+          "type": "emoji"
+        },
+        {
+          "text": " ",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "localId": "782129bf30c1",
+        "title": "Raw notes"
+      },
+      "content": [
+        {
+          "attrs": {
+            "localId": "e9614e389875"
+          },
+          "content": [
+            {
+              "text": "We spent twenty minutes on the colour of the launch banner.",
+              "type": "text"
+            }
+          ],
+          "type": "paragraph"
+        }
+      ],
+      "type": "expand"
+    }
+  ],
+  "type": "doc",
+  "version": 1
+}

corpus/real-payloads/review-comment.json

@@ -0,0 +1,118 @@
+{
+  "content": [
+    {
+      "attrs": {
+        "localId": "3e9517d02129"
+      },
+      "content": [
+        {
+          "text": "Looks good to me. Two small things:",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "localId": "5738867bf15d",
+        "order": 1
+      },
+      "content": [
+        {
+          "attrs": {
+            "localId": "ccd8d283e36d"
+          },
+          "content": [
+            {
+              "attrs": {
+                "localId": "638111edfab4"
+              },
+              "content": [
+                {
+                  "text": "Rename ",
+                  "type": "text"
+                },
+                {
+                  "marks": [
+                    {
+                      "type": "code"
+                    }
+                  ],
+                  "text": "beta.enabled",
+                  "type": "text"
+                },
+                {
+                  "text": " before the launch",
+                  "type": "text"
+                }
+              ],
+              "type": "paragraph"
+            }
+          ],
+          "type": "listItem"
+        },
+        {
+          "attrs": {
+            "localId": "0adfb25bb321"
+          },
+          "content": [
+            {
+              "attrs": {
+                "localId": "980750fad0fe"
+              },
+              "content": [
+                {
+                  "text": "Move the demo to the ",
+                  "type": "text"
+                },
+                {
+                  "marks": [
+                    {
+                      "type": "em"
+                    }
+                  ],
+                  "text": "large",
+                  "type": "text"
+                },
+                {
+                  "text": " room",
+                  "type": "text"
+                }
+              ],
+              "type": "paragraph"
+            }
+          ],
+          "type": "listItem"
+        }
+      ],
+      "type": "orderedList"
+    },
+    {
+      "attrs": {
+        "localId": "40e080c7acd4"
+      },
+      "content": [
+        {
+          "text": "Thanks ",
+          "type": "text"
+        },
+        {
+          "attrs": {
+            "accessLevel": "",
+            "id": "712020:78bf5058-bc76-4783-99af-6d70cb593cee",
+            "localId": "c4e073cd-8b3a-48b2-93a0-ade57b4ec2cf",
+            "text": "@Larvit Developer"
+          },
+          "type": "mention"
+        },
+        {
+          "text": " !",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    }
+  ],
+  "type": "doc",
+  "version": 1
+}

corpus/real-payloads/smart-links.json

@@ -0,0 +1,124 @@
+{
+  "content": [
+    {
+      "attrs": {
+        "level": 2,
+        "localId": "e632994a13ae"
+      },
+      "content": [
+        {
+          "text": "Smart links",
+          "type": "text"
+        }
+      ],
+      "type": "heading"
+    },
+    {
+      "attrs": {
+        "localId": "dcfa975dde87"
+      },
+      "content": [
+        {
+          "text": "An inline card sits in a sentence, like ",
+          "type": "text"
+        },
+        {
+          "attrs": {
+            "localId": "042b9a548674",
+            "url": "https://en.wikipedia.org/wiki/Markdown"
+          },
+          "type": "inlineCard"
+        },
+        {
+          "text": "   which keeps the text flowing.",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "localId": "c138d931a131"
+      },
+      "content": [
+        {
+          "text": "A block card stands on its own line:",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "localId": "9e527ae5f2bd"
+      },
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "localId": "88bd10974ec6",
+        "url": "https://spec.commonmark.org/"
+      },
+      "type": "blockCard"
+    },
+    {
+      "attrs": {
+        "localId": "9879bb1368ea"
+      },
+      "content": [
+        {
+          "text": " An embed shows the page itself, where the site allows it:",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "localId": "ccbed18139bb"
+      },
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "layout": "wide",
+        "localId": "8320cf243168",
+        "originalHeight": 480,
+        "originalWidth": 853.344,
+        "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
+        "width": 100
+      },
+      "type": "embedCard"
+    },
+    {
+      "attrs": {
+        "localId": "22f60b236c1c"
+      },
+      "content": [
+        {
+          "text": " And a plain address stays a link: ",
+          "type": "text"
+        },
+        {
+          "marks": [
+            {
+              "attrs": {
+                "href": "https://www.markdownguide.org/"
+              },
+              "type": "link"
+            }
+          ],
+          "text": "https://www.markdownguide.org/",
+          "type": "text"
+        },
+        {
+          "text": " for reference.",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    }
+  ],
+  "type": "doc",
+  "version": 1
+}

corpus/real-payloads/synced-block.json

@@ -0,0 +1,124 @@
+{
+  "content": [
+    {
+      "attrs": {
+        "level": 2,
+        "localId": "3265660b5792"
+      },
+      "content": [
+        {
+          "text": "Shared checklist",
+          "type": "text"
+        }
+      ],
+      "type": "heading"
+    },
+    {
+      "attrs": {
+        "localId": "c7d94ae59a47"
+      },
+      "content": [
+        {
+          "text": "The block below is synced, so an edit shows up wherever it is used.",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "localId": "72651b28-757c-44a1-be0b-586c3e6df546",
+        "resourceId": "03a667ab-4c6b-402d-adae-0c55582e32eb"
+      },
+      "content": [
+        {
+          "attrs": {
+            "localId": "0eb44ec3924b"
+          },
+          "content": [
+            {
+              "text": "Before every release:",
+              "type": "text"
+            }
+          ],
+          "type": "paragraph"
+        },
+        {
+          "attrs": {
+            "localId": "4beeefa0c6fa"
+          },
+          "content": [
+            {
+              "attrs": {
+                "localId": "07d19212447f"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "2fd9fc0e5d71"
+                  },
+                  "content": [
+                    {
+                      "text": "Run the tests",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "listItem"
+            },
+            {
+              "attrs": {
+                "localId": "7f5f50f7642c"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "14d3435ce5f4"
+                  },
+                  "content": [
+                    {
+                      "text": "Update the changelog",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "listItem"
+            }
+          ],
+          "type": "bulletList"
+        },
+        {
+          "attrs": {
+            "localId": "e405ebea5e00"
+          },
+          "content": [
+            {
+              "text": "Ask for a second pair of eyes.",
+              "type": "text"
+            }
+          ],
+          "type": "paragraph"
+        }
+      ],
+      "type": "bodiedSyncBlock"
+    },
+    {
+      "attrs": {
+        "localId": "73b5f0a1ef05"
+      },
+      "content": [
+        {
+          "text": "Anything specific to this release goes below the synced block.",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    }
+  ],
+  "type": "doc",
+  "version": 1
+}

corpus/real-payloads/tables.json

@@ -0,0 +1,620 @@
+{
+  "content": [
+    {
+      "attrs": {
+        "level": 2,
+        "localId": "a0c750451c14"
+      },
+      "content": [
+        {
+          "text": "A simple table",
+          "type": "text"
+        }
+      ],
+      "type": "heading"
+    },
+    {
+      "attrs": {
+        "localId": "944306a6da33"
+      },
+      "content": [
+        {
+          "text": "Rooms for the week:",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "isNumberColumnEnabled": false,
+        "layout": "align-start",
+        "localId": "92b28760-e51b-436d-82f0-45c6b6bf5b60"
+      },
+      "content": [
+        {
+          "attrs": {
+            "localId": "d53d5ad740cb"
+          },
+          "content": [
+            {
+              "attrs": {
+                "localId": "a8c82e01543e"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "00c1bde1a44d"
+                  },
+                  "content": [
+                    {
+                      "marks": [
+                        {
+                          "type": "strong"
+                        }
+                      ],
+                      "text": "Room",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableHeader"
+            },
+            {
+              "attrs": {
+                "localId": "c736c185bcd0"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "3dc846d8aaf9"
+                  },
+                  "content": [
+                    {
+                      "marks": [
+                        {
+                          "type": "strong"
+                        }
+                      ],
+                      "text": "Capacity",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableHeader"
+            },
+            {
+              "attrs": {
+                "localId": "b484834a890d"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "5b0671aadeed"
+                  },
+                  "content": [
+                    {
+                      "marks": [
+                        {
+                          "type": "strong"
+                        }
+                      ],
+                      "text": "Notes",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableHeader"
+            }
+          ],
+          "type": "tableRow"
+        },
+        {
+          "attrs": {
+            "localId": "45395ea36f04"
+          },
+          "content": [
+            {
+              "attrs": {
+                "localId": "8b19b08b6a93"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "363cf87d44be"
+                  },
+                  "content": [
+                    {
+                      "text": "North",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableCell"
+            },
+            {
+              "attrs": {
+                "localId": "e189034484f3"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "42a5bad514ea"
+                  },
+                  "content": [
+                    {
+                      "text": "12",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableCell"
+            },
+            {
+              "attrs": {
+                "localId": "9cfc78f9a553"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "2ae747c00211"
+                  },
+                  "content": [
+                    {
+                      "text": "Projector",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableCell"
+            }
+          ],
+          "type": "tableRow"
+        },
+        {
+          "attrs": {
+            "localId": "8bc7abba3229"
+          },
+          "content": [
+            {
+              "attrs": {
+                "localId": "0e7980a31697"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "a001411b475e"
+                  },
+                  "content": [
+                    {
+                      "text": "South",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableCell"
+            },
+            {
+              "attrs": {
+                "localId": "e61493f2b3d9"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "79c522faf7e8"
+                  },
+                  "content": [
+                    {
+                      "text": "8",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableCell"
+            },
+            {
+              "attrs": {
+                "localId": "db911772081a"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "6721e0a4f29f"
+                  },
+                  "content": [
+                    {
+                      "text": "Quiet corner",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableCell"
+            }
+          ],
+          "type": "tableRow"
+        }
+      ],
+      "type": "table"
+    },
+    {
+      "attrs": {
+        "level": 2,
+        "localId": "c21221cbaeda"
+      },
+      "content": [
+        {
+          "text": "A richer table",
+          "type": "text"
+        }
+      ],
+      "type": "heading"
+    },
+    {
+      "attrs": {
+        "localId": "b9cdc4e693ca"
+      },
+      "content": [
+        {
+          "text": "Budget by season, with merged, coloured and resized cells:",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "isNumberColumnEnabled": false,
+        "layout": "align-start",
+        "localId": "ac1b1f4b-3d7a-4cd2-a0a7-05ece633ba69"
+      },
+      "content": [
+        {
+          "attrs": {
+            "localId": "c411338ed251"
+          },
+          "content": [
+            {
+              "attrs": {
+                "background": "#b3d4ff",
+                "colwidth": [
+                  135
+                ],
+                "localId": "798f1dea331f"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "b605b3c1f598"
+                  },
+                  "content": [
+                    {
+                      "marks": [
+                        {
+                          "type": "strong"
+                        }
+                      ],
+                      "text": "Item",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableHeader"
+            },
+            {
+              "attrs": {
+                "colwidth": [
+                  233
+                ],
+                "localId": "db4768c076d4"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "b4890b2d833e"
+                  },
+                  "content": [
+                    {
+                      "marks": [
+                        {
+                          "type": "strong"
+                        }
+                      ],
+                      "text": "Spring",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableHeader"
+            },
+            {
+              "attrs": {
+                "colwidth": [
+                  184
+                ],
+                "localId": "4dde2fbfb921"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "7986b41ed947"
+                  },
+                  "content": [
+                    {
+                      "marks": [
+                        {
+                          "type": "strong"
+                        }
+                      ],
+                      "text": "Autumn",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableHeader"
+            }
+          ],
+          "type": "tableRow"
+        },
+        {
+          "attrs": {
+            "localId": "b4ac97bec992"
+          },
+          "content": [
+            {
+              "attrs": {
+                "colwidth": [
+                  135
+                ],
+                "localId": "ba92b57558d8"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "f23f030e9233"
+                  },
+                  "content": [
+                    {
+                      "text": "Venue",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableHeader"
+            },
+            {
+              "attrs": {
+                "background": "#abf5d1",
+                "colspan": 2,
+                "colwidth": [
+                  233,
+                  184
+                ],
+                "localId": "51af31d44baa"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "ba55f45dc035"
+                  },
+                  "content": [
+                    {
+                      "text": "Booked for both",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableCell"
+            }
+          ],
+          "type": "tableRow"
+        },
+        {
+          "attrs": {
+            "localId": "e911af70b656"
+          },
+          "content": [
+            {
+              "attrs": {
+                "colwidth": [
+                  135
+                ],
+                "localId": "50a820456456"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "b04d0749aee7"
+                  },
+                  "content": [
+                    {
+                      "text": "Catering",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableHeader"
+            },
+            {
+              "attrs": {
+                "colwidth": [
+                  233
+                ],
+                "localId": "d0cc276de239"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "90211ae7a504"
+                  },
+                  "content": [
+                    {
+                      "text": "400",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableCell"
+            },
+            {
+              "attrs": {
+                "colwidth": [
+                  184
+                ],
+                "localId": "1962d05e8763"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "221cf059e38d"
+                  },
+                  "content": [
+                    {
+                      "text": "450",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableCell"
+            }
+          ],
+          "type": "tableRow"
+        },
+        {
+          "attrs": {
+            "localId": "2c8a06942ac4"
+          },
+          "content": [
+            {
+              "attrs": {
+                "colwidth": [
+                  135
+                ],
+                "localId": "ba4e1cb93e92"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "e6bb346c5fd4"
+                  },
+                  "content": [
+                    {
+                      "text": "Notes",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableHeader"
+            },
+            {
+              "attrs": {
+                "colwidth": [
+                  233
+                ],
+                "localId": "d7a1dec97b03"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "5cbd8813deab"
+                  },
+                  "content": [
+                    {
+                      "text": "Spring is confirmed.",
+                      "type": "text"
+                    }
+                  ],
+                  "type": "paragraph"
+                }
+              ],
+              "type": "tableCell"
+            },
+            {
+              "attrs": {
+                "colwidth": [
+                  184
+                ],
+                "localId": "85f9a8dab00b"
+              },
+              "content": [
+                {
+                  "attrs": {
+                    "localId": "da90346e9a26",
+                    "title": "Payment terms"
+                  },
+                  "content": [
+                    {
+                      "attrs": {
+                        "localId": "ef6c6f374bca"
+                      },
+                      "content": [
+                        {
+                          "text": "Invoices arrive monthly.",
+                          "type": "text"
+                        }
+                      ],
+                      "type": "paragraph"
+                    }
+                  ],
+                  "type": "nestedExpand"
+                }
+              ],
+              "type": "tableCell"
+            }
+          ],
+          "type": "tableRow"
+        }
+      ],
+      "type": "table"
+    },
+    {
+      "attrs": {
+        "localId": "10d03e65eff2"
+      },
+      "content": [
+        {
+          "text": "Figures are estimates.",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    }
+  ],
+  "type": "doc",
+  "version": 1
+}

corpus/real-payloads/tasks-and-decisions.json

@@ -0,0 +1,195 @@
+{
+  "content": [
+    {
+      "attrs": {
+        "level": 2,
+        "localId": "26d50a5240c3"
+      },
+      "content": [
+        {
+          "text": "Action items",
+          "type": "text"
+        }
+      ],
+      "type": "heading"
+    },
+    {
+      "attrs": {
+        "localId": "f8b236b2-3b7c-412a-a0df-6c523af43a76"
+      },
+      "content": [
+        {
+          "attrs": {
+            "localId": "eebe3cb9-5773-4753-b6a3-5a5df104b6e8",
+            "state": "DONE"
+          },
+          "content": [
+            {
+              "text": "Book the meeting room",
+              "type": "text"
+            }
+          ],
+          "type": "taskItem"
+        },
+        {
+          "attrs": {
+            "localId": "2263a39a-c49c-4711-8f00-cca6e8f3ea35",
+            "state": "TODO"
+          },
+          "content": [
+            {
+              "text": "Order name badges",
+              "type": "text"
+            }
+          ],
+          "type": "taskItem"
+        },
+        {
+          "attrs": {
+            "localId": "e323e762-8880-43c0-945d-17a7341fdefb"
+          },
+          "content": [
+            {
+              "attrs": {
+                "localId": "55523903-9f79-4711-b276-ec1bc98be977",
+                "state": "DONE"
+              },
+              "content": [
+                {
+                  "text": "Print a spare set for the front desk",
+                  "type": "text"
+                }
+              ],
+              "type": "taskItem"
+            }
+          ],
+          "type": "taskList"
+        },
+        {
+          "attrs": {
+            "localId": "680d665a-a859-4345-b032-d5a46fd6db0d",
+            "state": "TODO"
+          },
+          "content": [
+            {
+              "text": "Send the agenda to everyone",
+              "type": "text"
+            }
+          ],
+          "type": "taskItem"
+        },
+        {
+          "attrs": {
+            "localId": "48d45b93-2180-4b80-b0ed-f9eb458ed1ed",
+            "state": "TODO"
+          },
+          "content": [
+            {
+              "text": "Ask ",
+              "type": "text"
+            },
+            {
+              "attrs": {
+                "accessLevel": "",
+                "id": "712020:78bf5058-bc76-4783-99af-6d70cb593cee",
+                "localId": "09321e9b-b551-48ee-8868-5339e8b86863",
+                "text": "@Larvit Developer"
+              },
+              "type": "mention"
+            },
+            {
+              "text": " about parking by ",
+              "type": "text"
+            },
+            {
+              "attrs": {
+                "localId": "16c6b2a1718e",
+                "timestamp": "1792022400000"
+              },
+              "type": "date"
+            },
+            {
+              "text": " ",
+              "type": "text"
+            }
+          ],
+          "type": "taskItem"
+        }
+      ],
+      "type": "taskList"
+    },
+    {
+      "attrs": {
+        "localId": "90a7d38e3ed7"
+      },
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "localId": "8c510497da2e"
+      },
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "level": 2,
+        "localId": "3b52fc685167"
+      },
+      "content": [
+        {
+          "text": "Decisions",
+          "type": "text"
+        }
+      ],
+      "type": "heading"
+    },
+    {
+      "attrs": {
+        "localId": "82dbc28b-49c8-428c-8c21-65cc000ef7c5"
+      },
+      "content": [
+        {
+          "attrs": {
+            "localId": "2f7a7680-2c41-4b45-9162-29d97f922a7b",
+            "state": "DECIDED"
+          },
+          "content": [
+            {
+              "text": "Hold the kickoff on the second floor",
+              "type": "text"
+            }
+          ],
+          "type": "decisionItem"
+        },
+        {
+          "attrs": {
+            "localId": "c94ef59b-6db4-4ddc-8d22-576821020306",
+            "state": "DECIDED"
+          },
+          "content": [
+            {
+              "text": "Keep the budget under the agreed limit",
+              "type": "text"
+            }
+          ],
+          "type": "decisionItem"
+        }
+      ],
+      "type": "decisionList"
+    },
+    {
+      "attrs": {
+        "localId": "562121f961a8"
+      },
+      "content": [
+        {
+          "text": "Done items are ticked; the rest are still open.",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    }
+  ],
+  "type": "doc",
+  "version": 1
+}

corpus/real-payloads/text-formatting.json

@@ -0,0 +1,288 @@
+{
+  "content": [
+    {
+      "attrs": {
+        "level": 2,
+        "localId": "ef39f25be439"
+      },
+      "content": [
+        {
+          "text": "Text formatting",
+          "type": "text"
+        }
+      ],
+      "type": "heading"
+    },
+    {
+      "attrs": {
+        "localId": "4a24d2441f4b"
+      },
+      "content": [
+        {
+          "text": "This sentence has ",
+          "type": "text"
+        },
+        {
+          "marks": [
+            {
+              "type": "strong"
+            }
+          ],
+          "text": "bold",
+          "type": "text"
+        },
+        {
+          "text": ", ",
+          "type": "text"
+        },
+        {
+          "marks": [
+            {
+              "type": "em"
+            }
+          ],
+          "text": "italic",
+          "type": "text"
+        },
+        {
+          "text": ", ",
+          "type": "text"
+        },
+        {
+          "marks": [
+            {
+              "type": "underline"
+            }
+          ],
+          "text": "underlined",
+          "type": "text"
+        },
+        {
+          "text": ", ",
+          "type": "text"
+        },
+        {
+          "marks": [
+            {
+              "type": "strike"
+            }
+          ],
+          "text": "struck",
+          "type": "text"
+        },
+        {
+          "text": " and ",
+          "type": "text"
+        },
+        {
+          "marks": [
+            {
+              "type": "code"
+            }
+          ],
+          "text": "inline code",
+          "type": "text"
+        },
+        {
+          "text": " words in it.",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "localId": "707e9aa736b2"
+      },
+      "content": [
+        {
+          "text": "Water is H",
+          "type": "text"
+        },
+        {
+          "marks": [
+            {
+              "attrs": {
+                "type": "sub"
+              },
+              "type": "subsup"
+            }
+          ],
+          "text": "2",
+          "type": "text"
+        },
+        {
+          "text": "O and the room measures 20 m",
+          "type": "text"
+        },
+        {
+          "marks": [
+            {
+              "attrs": {
+                "type": "sup"
+              },
+              "type": "subsup"
+            }
+          ],
+          "text": "2",
+          "type": "text"
+        },
+        {
+          "text": ".",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "localId": "a03bd1fe3442"
+      },
+      "content": [
+        {
+          "text": "Some words are ",
+          "type": "text"
+        },
+        {
+          "marks": [
+            {
+              "attrs": {
+                "color": "#ff5630"
+              },
+              "type": "textColor"
+            }
+          ],
+          "text": "red",
+          "type": "text"
+        },
+        {
+          "text": ", some are ",
+          "type": "text"
+        },
+        {
+          "marks": [
+            {
+              "attrs": {
+                "color": "#0747a6"
+              },
+              "type": "textColor"
+            }
+          ],
+          "text": "bold blue",
+          "type": "text"
+        },
+        {
+          "text": ", and one is ",
+          "type": "text"
+        },
+        {
+          "marks": [
+            {
+              "attrs": {
+                "color": "#f8e6a0"
+              },
+              "type": "backgroundColor"
+            }
+          ],
+          "text": "highlighted",
+          "type": "text"
+        },
+        {
+          "text": ".",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "localId": "f3a744347f56"
+      },
+      "content": [
+        {
+          "text": "A ",
+          "type": "text"
+        },
+        {
+          "marks": [
+            {
+              "type": "em"
+            },
+            {
+              "type": "strong"
+            }
+          ],
+          "text": "bold italic",
+          "type": "text"
+        },
+        {
+          "text": " phrase, and a ",
+          "type": "text"
+        },
+        {
+          "marks": [
+            {
+              "type": "strike"
+            },
+            {
+              "type": "underline"
+            }
+          ],
+          "text": "struck underlined",
+          "type": "text"
+        },
+        {
+          "text": " one.",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "attrs": {
+        "localId": "643a019d97c1"
+      },
+      "content": [
+        {
+          "text": "Read the ",
+          "type": "text"
+        },
+        {
+          "marks": [
+            {
+              "attrs": {
+                "href": "https://spec.commonmark.org/0.31.2/"
+              },
+              "type": "link"
+            }
+          ],
+          "text": "CommonMark spec",
+          "type": "text"
+        },
+        {
+          "text": " or the ",
+          "type": "text"
+        },
+        {
+          "marks": [
+            {
+              "attrs": {
+                "href": "https://www.markdownguide.org/basic-syntax/"
+              },
+              "type": "link"
+            }
+          ],
+          "text": "basic syntax guide",
+          "type": "text"
+        },
+        {
+          "text": " before you edit.",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    }
+  ],
+  "type": "doc",
+  "version": 1
+}

corpus/round-trip/combinations/carry-text-attributes.json

@@ -0,0 +1,57 @@
+{
+  "content": [
+    {
+      "content": [
+        {
+          "attrs": {
+            "localId": "01a0a067-68cf-78af-abd6-c660ec0d189b"
+          },
+          "text": "Owner",
+          "type": "text"
+        },
+        {
+          "text": " signs off.",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "content": [
+        {
+          "text": "Signed by ",
+          "type": "text"
+        },
+        {
+          "attrs": {
+            "localId": "01a0a067-68d2-787e-afc5-2459776aa029"
+          },
+          "text": "the owner",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "content": [
+        {
+          "attrs": {
+            "localId": "01a0a067-68d5-7372-9962-29a039654056"
+          },
+          "text": "One ",
+          "type": "text"
+        },
+        {
+          "attrs": {
+            "localId": "01a0a067-68d5-7372-9962-29a039654056"
+          },
+          "text": "anchor",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    }
+  ],
+  "type": "doc",
+  "version": 1
+}

corpus/round-trip/combinations/carry-text-attributes.md

@@ -0,0 +1,5 @@
+:adf{json="{\"attrs\":{\"localId\":\"01a0a067-68cf-78af-abd6-c660ec0d189b\"},\"text\":\"Owner\",\"type\":\"text\"}"} signs off.
+
+Signed by :adf{json="{\"attrs\":{\"localId\":\"01a0a067-68d2-787e-afc5-2459776aa029\"},\"text\":\"the owner\",\"type\":\"text\"}"}
+
+:adf{json="{\"attrs\":{\"localId\":\"01a0a067-68d5-7372-9962-29a039654056\"},\"text\":\"One \",\"type\":\"text\"}"}:adf{json="{\"attrs\":{\"localId\":\"01a0a067-68d5-7372-9962-29a039654056\"},\"text\":\"anchor\",\"type\":\"text\"}"}

corpus/round-trip/combinations/code-span-joined-run.json

@@ -0,0 +1,73 @@
+{
+  "content": [
+    {
+      "content": [
+        {
+          "text": "`` ``",
+          "type": "text"
+        },
+        {
+          "marks": [
+            {
+              "type": "code"
+            }
+          ],
+          "text": "a",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "content": [
+        {
+          "marks": [
+            {
+              "type": "underline"
+            }
+          ],
+          "text": "``",
+          "type": "text"
+        },
+        {
+          "text": "``",
+          "type": "text"
+        },
+        {
+          "marks": [
+            {
+              "type": "code"
+            }
+          ],
+          "text": "a",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "content": [
+        {
+          "text": "``\\`",
+          "type": "text"
+        },
+        {
+          "marks": [
+            {
+              "type": "code"
+            }
+          ],
+          "text": "`",
+          "type": "text"
+        },
+        {
+          "text": "`",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    }
+  ],
+  "type": "doc",
+  "version": 1
+}

corpus/round-trip/combinations/code-span-joined-run.md

@@ -0,0 +1,5 @@
+\`\` \`\``a`
+
+:underline[\`\`]\`\``a`
+
+\`\`\\\``` ` ``\`

corpus/round-trip/combinations/directive-autolink-backtick.json

@@ -0,0 +1,50 @@
+{
+  "content": [
+    {
+      "content": [
+        {
+          "marks": [
+            {
+              "type": "underline"
+            },
+            {
+              "attrs": {
+                "href": "http://a`b"
+              },
+              "type": "link"
+            }
+          ],
+          "text": "http://a`b",
+          "type": "text"
+        },
+        {
+          "text": "`c",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "content": [
+        {
+          "marks": [
+            {
+              "type": "underline"
+            },
+            {
+              "attrs": {
+                "href": "http://d`e"
+              },
+              "type": "link"
+            }
+          ],
+          "text": "http://d`e",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    }
+  ],
+  "type": "doc",
+  "version": 1
+}

corpus/round-trip/combinations/directive-autolink-backtick.md

@@ -0,0 +1,3 @@
+:underline[[http://a\`b](http://a\`b)]`c
+
+:underline[[http://d\`e](http://d`e)]

corpus/round-trip/combinations/directive-link-backticks.json

@@ -0,0 +1,83 @@
+{
+  "content": [
+    {
+      "content": [
+        {
+          "marks": [
+            {
+              "attrs": {
+                "color": ""
+              },
+              "type": "textColor"
+            },
+            {
+              "attrs": {
+                "href": "`"
+              },
+              "type": "link"
+            }
+          ],
+          "text": " ",
+          "type": "text"
+        },
+        {
+          "text": "`a",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "content": [
+        {
+          "marks": [
+            {
+              "type": "underline"
+            },
+            {
+              "attrs": {
+                "href": "c",
+                "title": "`"
+              },
+              "type": "link"
+            }
+          ],
+          "text": "b",
+          "type": "text"
+        },
+        {
+          "marks": [
+            {
+              "type": "code"
+            }
+          ],
+          "text": "c",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "content": [
+        {
+          "marks": [
+            {
+              "type": "underline"
+            },
+            {
+              "attrs": {
+                "href": "e`f"
+              },
+              "type": "link"
+            }
+          ],
+          "text": "d",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    }
+  ],
+  "type": "doc",
+  "version": 1
+}

corpus/round-trip/combinations/directive-link-backticks.md

@@ -0,0 +1,5 @@
+:textColor[[ ](\`)]{color=""}`a
+
+:underline[[b](c "\`")]`c`
+
+:underline[[d](e`f)]

corpus/round-trip/combinations/directive-link-brackets.json

@@ -0,0 +1,111 @@
+{
+  "content": [
+    {
+      "content": [
+        {
+          "marks": [
+            {
+              "type": "subsup"
+            },
+            {
+              "attrs": {
+                "href": "["
+              },
+              "type": "link"
+            }
+          ],
+          "text": "a",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "content": [
+        {
+          "marks": [
+            {
+              "type": "underline"
+            },
+            {
+              "attrs": {
+                "href": "]"
+              },
+              "type": "link"
+            }
+          ],
+          "text": "b",
+          "type": "text"
+        },
+        {
+          "marks": [
+            {
+              "type": "underline"
+            }
+          ],
+          "text": " ",
+          "type": "text"
+        },
+        {
+          "marks": [
+            {
+              "type": "underline"
+            },
+            {
+              "attrs": {
+                "href": "x",
+                "title": "["
+              },
+              "type": "link"
+            }
+          ],
+          "text": "c",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "content": [
+        {
+          "marks": [
+            {
+              "type": "underline"
+            },
+            {
+              "attrs": {
+                "href": "e[f]"
+              },
+              "type": "link"
+            }
+          ],
+          "text": "d",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "content": [
+        {
+          "marks": [
+            {
+              "type": "underline"
+            },
+            {
+              "attrs": {
+                "href": "http://a[b"
+              },
+              "type": "link"
+            }
+          ],
+          "text": "http://a[b",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    }
+  ],
+  "type": "doc",
+  "version": 1
+}

corpus/round-trip/combinations/directive-link-brackets.md

@@ -0,0 +1,7 @@
+:subsup[[a](\[)]
+
+:underline[[b](\]) [c](x "\[")]
+
+:underline[[d](e[f])]
+
+:underline[[http://a\[b](http://a\[b)]

corpus/round-trip/combinations/directive-link-colon.json

@@ -0,0 +1,107 @@
+{
+  "content": [
+    {
+      "content": [
+        {
+          "marks": [
+            {
+              "type": "underline"
+            },
+            {
+              "attrs": {
+                "href": ":a{"
+              },
+              "type": "link"
+            }
+          ],
+          "text": "x",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "content": [
+        {
+          "marks": [
+            {
+              "type": "underline"
+            },
+            {
+              "attrs": {
+                "href": "y",
+                "title": ":a{"
+              },
+              "type": "link"
+            }
+          ],
+          "text": "x",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "content": [
+        {
+          "marks": [
+            {
+              "type": "underline"
+            },
+            {
+              "attrs": {
+                "href": ":a[]{"
+              },
+              "type": "link"
+            }
+          ],
+          "text": "x",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "content": [
+        {
+          "marks": [
+            {
+              "type": "underline"
+            },
+            {
+              "attrs": {
+                "href": "https://example.com/?q=:emoji{"
+              },
+              "type": "link"
+            }
+          ],
+          "text": "x",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "content": [
+        {
+          "marks": [
+            {
+              "type": "underline"
+            },
+            {
+              "attrs": {
+                "href": "ab:c{"
+              },
+              "type": "link"
+            }
+          ],
+          "text": "ab:c{",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    }
+  ],
+  "type": "doc",
+  "version": 1
+}

corpus/round-trip/combinations/directive-link-colon.md

@@ -0,0 +1,9 @@
+:underline[[x](\:a{)]
+
+:underline[[x](y "\:a{")]
+
+:underline[[x](\:a[]{)]
+
+:underline[[x](https://example.com/?q=\:emoji{)]
+
+:underline[[ab\:c{](ab\:c{)]

corpus/round-trip/combinations/link-definition-carry.json

@@ -0,0 +1,45 @@
+{
+  "content": [
+    {
+      "content": [
+        {
+          "marks": [
+            {
+              "attrs": {
+                "href": "/u"
+              },
+              "type": "link"
+            },
+            {
+              "type": "code"
+            }
+          ],
+          "text": "]: a",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "content": [
+        {
+          "attrs": {
+            "timestamp": "]:a"
+          },
+          "marks": [
+            {
+              "attrs": {
+                "href": "/u"
+              },
+              "type": "link"
+            }
+          ],
+          "type": "date"
+        }
+      ],
+      "type": "paragraph"
+    }
+  ],
+  "type": "doc",
+  "version": 1
+}

corpus/round-trip/combinations/link-definition-carry.md

@@ -0,0 +1,3 @@
+:adf{json="{\"marks\":[{\"attrs\":{\"href\":\"/u\"},\"type\":\"link\"},{\"type\":\"code\"}],\"text\":\"]: a\",\"type\":\"text\"}"}
+
+:adf{json="{\"attrs\":{\"timestamp\":\"]:a\"},\"marks\":[{\"attrs\":{\"href\":\"/u\"},\"type\":\"link\"}],\"type\":\"date\"}"}

corpus/round-trip/combinations/link-definition-line.json

@@ -0,0 +1,76 @@
+{
+  "content": [
+    {
+      "content": [
+        {
+          "text": "[",
+          "type": "text"
+        },
+        {
+          "attrs": {
+            "timestamp": "]:a"
+          },
+          "type": "date"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "content": [
+        {
+          "content": [
+            {
+              "text": "[",
+              "type": "text"
+            },
+            {
+              "marks": [
+                {
+                  "type": "code"
+                }
+              ],
+              "text": "]: a",
+              "type": "text"
+            }
+          ],
+          "type": "paragraph"
+        }
+      ],
+      "type": "blockquote"
+    },
+    {
+      "content": [
+        {
+          "content": [
+            {
+              "content": [
+                {
+                  "text": "[",
+                  "type": "text"
+                },
+                {
+                  "attrs": {
+                    "timestamp": "]:a"
+                  },
+                  "type": "date"
+                },
+                {
+                  "type": "hardBreak"
+                },
+                {
+                  "text": "b",
+                  "type": "text"
+                }
+              ],
+              "type": "paragraph"
+            }
+          ],
+          "type": "listItem"
+        }
+      ],
+      "type": "bulletList"
+    }
+  ],
+  "type": "doc",
+  "version": 1
+}

corpus/round-trip/combinations/link-definition-line.md

@@ -0,0 +1,6 @@
+\[:date{timestamp="]:a"}
+
+> \[`]: a`
+
+- \[:date{timestamp="]:a"}\
+  b

corpus/round-trip/combinations/list-item-whitespace-line.json

@@ -0,0 +1,57 @@
+{
+  "content": [
+    {
+      "content": [
+        {
+          "content": [
+            {
+              "content": [
+                {
+                  "text": " \na",
+                  "type": "text"
+                }
+              ],
+              "type": "codeBlock"
+            }
+          ],
+          "type": "listItem"
+        }
+      ],
+      "type": "bulletList"
+    },
+    {
+      "attrs": {
+        "order": 1
+      },
+      "content": [
+        {
+          "content": [
+            {
+              "content": [
+                {
+                  "content": [
+                    {
+                      "content": [
+                        {
+                          "text": "\t",
+                          "type": "text"
+                        }
+                      ],
+                      "type": "codeBlock"
+                    }
+                  ],
+                  "type": "listItem"
+                }
+              ],
+              "type": "bulletList"
+            }
+          ],
+          "type": "listItem"
+        }
+      ],
+      "type": "orderedList"
+    }
+  ],
+  "type": "doc",
+  "version": 1
+}

corpus/round-trip/combinations/list-item-whitespace-line.md

@@ -0,0 +1,20 @@
+::::bulletList
+:::listItem
+```
+ 
+a
+```
+:::
+::::
+
+::::::orderedList {order=1}
+:::::listItem
+::::bulletList
+:::listItem
+```
+	
+```
+:::
+::::
+:::::
+::::::

corpus/round-trip/commonmark-subset/link-empty-destination.json

@@ -0,0 +1,24 @@
+{
+  "content": [
+    {
+      "content": [
+        {
+          "marks": [
+            {
+              "attrs": {
+                "href": "",
+                "title": ""
+              },
+              "type": "link"
+            }
+          ],
+          "text": "a",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    }
+  ],
+  "type": "doc",
+  "version": 1
+}

corpus/round-trip/commonmark-subset/link-empty-destination.md

@@ -0,0 +1 @@
+[a](<> "")

corpus/round-trip/commonmark-subset/text-backtick-run.json

@@ -0,0 +1,31 @@
+{
+  "content": [
+    {
+      "content": [
+        {
+          "text": "`a ``b``",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    },
+    {
+      "content": [
+        {
+          "text": "`a",
+          "type": "text"
+        },
+        {
+          "type": "hardBreak"
+        },
+        {
+          "text": "```b``",
+          "type": "text"
+        }
+      ],
+      "type": "paragraph"
+    }
+  ],
+  "type": "doc",
+  "version": 1
+}

corpus/round-trip/commonmark-subset/text-backtick-run.md

@@ -0,0 +1,4 @@
+\`a \`\`b``
+
+\`a\
+\`\`\`b``

docker-runner.sh

@@ -7,7 +7,7 @@ node_image=node:24.19.0-alpine3.24
 in_image() {
   local image=$1 entrypoint=$2
   shift 2
-  docker run --rm -u "$(id -u):$(id -g)" -e HOME=/tmp ${in_image_network:+--network "$in_image_network"} -v "$PWD:/app" -w /app --entrypoint "$entrypoint" "$image" "$@"
+  docker run --rm -u "$(id -u):$(id -g)" -e HOME=/tmp ${PROPERTY_RUNS+-e PROPERTY_RUNS} ${in_image_network:+--network "$in_image_network"} -v "$PWD:/app" -w /app --entrypoint "$entrypoint" "$image" "$@"
 }
 
 with_firefox() {

package-lock.json

@@ -10,6 +10,7 @@
       "license": "MIT",
       "devDependencies": {
         "@types/node": "24.13.3",
+        "fast-check": "4.10.0",
         "typescript": "7.0.2"
       },
       "engines": {
@@ -366,6 +367,46 @@
         "node": ">=16.20.0"
       }
     },
+    "node_modules/fast-check": {
+      "version": "4.10.0",
+      "resolved": "https://registry.npmjs.org/fast-check/-/fast-check-4.10.0.tgz",
+      "integrity": "sha512-hhqQL+IJllZi3aM4TKvmCj3bywLEcycNTTLZeLhA9ttMxBrCqM07q7Di4kl+j9EWSTXvJH1+EpIgsDbF/+8H5Q==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "individual",
+          "url": "https://github.com/sponsors/dubzzz"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fast-check"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "pure-rand": "^8.0.0"
+      },
+      "engines": {
+        "node": ">=12.17.0"
+      }
+    },
+    "node_modules/pure-rand": {
+      "version": "8.4.2",
+      "resolved": "https://registry.npmjs.org/pure-rand/-/pure-rand-8.4.2.tgz",
+      "integrity": "sha512-vvuOGgcuPJAirlHvuQw1TrOiw7ptaIXXmIbNuiNOY6lNGJJH49PQ1Kj4nd783nPdQhQdicgOjVI2yI/9BD6/Ng==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "individual",
+          "url": "https://github.com/sponsors/dubzzz"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fast-check"
+        }
+      ],
+      "license": "MIT"
+    },
     "node_modules/typescript": {
       "version": "7.0.2",
       "resolved": "https://registry.npmjs.org/typescript/-/typescript-7.0.2.tgz",

package.json

@@ -23,11 +23,12 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "test": "node --test --experimental-test-coverage --test-coverage-exclude=\"src/**/*.test.ts\" --test-coverage-branches=98 --test-coverage-functions=100 --test-coverage-lines=100 \"src/**/*.test.ts\"",
+    "test": "node --test --experimental-test-coverage --test-coverage-exclude=\"src/**/*.test.ts\" --test-coverage-exclude=src/property-harness.ts --test-coverage-branches=98 --test-coverage-functions=100 --test-coverage-lines=100 \"src/**/*.test.ts\"",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.build.json"
   },
   "devDependencies": {
     "@types/node": "24.13.3",
+    "fast-check": "4.10.0",
     "typescript": "7.0.2"
   }
 }

spec/adf-schema/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2019 Atlassian Pty Ltd
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

spec/adf-schema/LICENSE-2.0.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

spec/adf-schema/README.md

@@ -0,0 +1,6 @@
+# Atlassian's ADF JSON Schemas
+
+`full.json` and `stage-0.json` are byte-exact from `dist/json-schema/v1/` in
+[`@atlaskit/adf-schema` 57.4.9](https://registry.npmjs.org/@atlaskit/adf-schema/-/adf-schema-57.4.9.tgz)
+(© Atlassian Pty Ltd, Apache-2.0: `LICENSE` is the package's own notice, `LICENSE-2.0.txt` the
+licence it names).

spec/flavour.md

@@ -3,7 +3,7 @@
 The grammar of the extended markdown `adfToMarkdown` emits and `markdownToAdf` parses. Plain
 CommonMark is a subset apart from raw HTML (below), with three carve-outs: literal text that
 matches directive syntax below or reads as a pipe table is claimed by the flavour, and a matched
-`~~` pair spells `strike` (escape the `:`, `|` or `~` to keep it literal) — and one gap: a
+`~~` pair spells `strike` (escape the `!adf:`, `|` or `~` to keep it literal) — and one gap: a
 CommonMark image fits only as its own
 title-less paragraph — mid-text and titled images are named errors. The emitted form is contract
 (AGENTS.md §8). Per-node syntaxes build on this grammar in the sections below.
@@ -25,10 +25,11 @@ normalizes to it through the round-trip.
   whose first item is empty), whatever block sits above it. Blank lines between items normalize
   away, and no list opens beside one of its own kind — the marker change CommonMark starts a
   second list on merges instead: ADF records no tightness, so one `- ` spelling reads two
-  adjacent lists of a kind back as one. The leaf `::listBreak` parts them, taking the separation
+  adjacent lists of a kind back as one. The leaf `!adf:listBreak` parts them, taking the separation
   any directive block takes where it sits. It builds no node, and it reads only between two
   adjacent lists of one type: elsewhere, or carrying an argument, `{attrs}` or a body, it is a
-  named error.
+  named error. A list whose item holds a line of spaces or tabs alone, which a list item reads
+  back empty, takes the directive form.
 - Blockquotes prefix lines with `> `; a blank line inside a blockquote is a bare `>`.
 - ATX headings (`#` … `######`); setext input normalizes to ATX.
 - Code fences ``` with the node's language as info string, the fence lengthened past any backtick
@@ -42,15 +43,25 @@ normalizes to it through the round-trip.
 - Hard break: backslash at end of line (survives editors that trim trailing spaces). Where
   CommonMark admits no spelling — the end of a block, inside an ATX heading — or where the node
   carries an attribute, it is the inline directive.
-- An empty paragraph — real payloads carry them — is `::paragraph`.
-- Links `[text](url)`; `<…>` around a destination containing spaces; title in double quotes. A
-  backslash escapes a parenthesis the destination leaves unbalanced, and a quote inside the title;
-  a balanced pair stays bare. `<url>` autolink form only when the text equals the destination and
-  the destination is a valid CommonMark autolink (absolute URI).
+- An empty paragraph — real payloads carry them — is an `!adf:paragraph` … `!adf:/paragraph` pair
+  holding nothing.
+- Links `[text](url)`; `<…>` around a destination containing spaces, `<>` an empty one beside a
+  title; title in double quotes. A backslash escapes a parenthesis the destination leaves
+  unbalanced, and a quote inside the title; a balanced pair stays bare. `<url>` autolink form only
+  when the text equals the destination and the destination is a valid CommonMark autolink
+  (absolute URI) — inside an inline directive's `[content]`, one holding no backtick, no
+  unbalanced bracket and no inline directive opener.
 - Paragraphs on one line — no soft wrapping; a soft line break in input becomes a single space.
 - Entity references in input decode to their characters; output backslash-escapes only where text
   would otherwise parse as syntax, scanning the assembled line rather than each text node: escape
   the leading delimiter of a construct that would otherwise open, re-scan from there, and repeat.
+  A backtick run escapes whole, and a bare one escapes wherever a later backtick string of its
+  length forms around an escape in the same inline content — an escaped backtick alone, one joined
+  to the bare run after it, or a bare run an escape splits off: CommonMark reads no escape inside a
+  code span, so such a string still closes one.
+  Where a paragraph opens with what reads as a link reference definition, which resolves before
+  any inline construct binds (a `]` inside a code span or `{attrs}` counts), an opening text `[`
+  escapes and an opening link's nodes ride the carry.
   An emphasis delimiter run in text escapes where CommonMark can open **or** close with it, so
   `*not emphasis*` is `\*not emphasis\*` — no delimiter the emitter did not write reaches the
   matching below, which is what lets the emitter decide its own pairings.
@@ -62,56 +73,59 @@ normalizes to it through the round-trip.
 
 ## Directives
 
-One grammar for everything CommonMark lacks. A directive name is `[a-z][A-Za-z0-9]*` — the ADF
-node and mark names the sections below spell as directives. Recognition is syntactic and
-name-set-independent: anything matching the forms below parses as a directive regardless of
-whether the name is known, and an unknown name is an error result naming it — so output an old
-emitter escaped stays escaped, and erroring input gaining meaning later is MINOR, never a reparse
-(§8). Each name belongs to one position, and a name the other one spells — a mark or an inline
-node written as a block directive, a block node written inline — is a different error, naming the
-spelling it takes. Two reserved names read back to no node: `adf` for the opaque carry, as both
-directive name and fence info string, and `listBreak` for the leaf that parts two adjacent lists
-(Canonical form).
+One grammar for everything CommonMark lacks, namespaced: every directive opens with the literal
+`!adf:`. A directive name is `[a-z][A-Za-z0-9]*` — the ADF node and mark names the sections below
+spell as directives. Recognition is syntactic and name-set-independent: anything matching the forms
+below parses as a directive regardless of whether the name is known, and an unknown name is an
+error result naming it at the opener, whatever follows it — so output an old emitter escaped stays
+escaped, and erroring input gaining meaning later is MINOR, never a reparse (§8). Each name belongs
+to one position, and a name the other one spells — a mark or an inline node written as a block
+directive, a block node written inline — is a different error, naming the spelling it takes. Two
+reserved names read back to no node: `carry` for the opaque carry, as both directive name and fence
+info string, and `listBreak` for the leaf that parts two adjacent lists (Canonical form).
 
-**Inline**: `:name[content]{attrs}`, on one line — an inline directive never spans lines.
+**Claiming**: an unescaped `!adf:` claims wherever it stands. What follows picks the form: `/name`
+closes a container, and a name picks by what follows it in turn — a space or the line's end a block
+line, `[` or `{` an inline directive. A `!adf:` completing none of the three is a named error, and
+`\!adf:` is the literal, block and inline alike. A claimed block line also ends a lazy continuation:
+the blockquote or list item whose paragraph CommonMark would fold it into closes instead.
+
+**Inline**: `!adf:name[content]{attrs}`, on one line — an inline directive never spans lines.
 `[content]` is inline markdown; brackets inside balance as in CommonMark link text, `\]` for a
 literal bracket. Whitespace at either edge of `[content]`, space or tab, is part of it and
-survives inline parsing. Each section below says whether content is required. `:` opens a
-directive only when the name is followed immediately by `[` or `{`, and `{attrs}` must follow
-`]` (or the name) with no gap — anything else (`10:30`, `:smile:`, a stray `{…}` in text) is
-literal text. An inline directive binds as a unit before bracket matching, the way a code span
-does: a `]` or `(` inside its `{attrs}` is the directive's, never the enclosing content's, and a
-`(` after its closing `]` opens no link.
+survives inline parsing. Each section below says whether content is required, and `{attrs}` must
+follow `]` (or the name) with no gap. An inline directive binds as a unit before bracket matching,
+the way a code span does: a `]` or `(` inside its `{attrs}` is the directive's, never the enclosing
+content's, and a `(` after its closing `]` opens no link.
 
-**Container block**:
+**Block container**:
 
 ```
-:::name arg {attrs}
+!adf:name arg {attrs}
 block content
-:::
+!adf:/name
 ```
 
-The fence is three or more colons. `arg` is one optional bare token whose meaning each node
-defines (e.g. the panel type). The body is block markdown. The closing fence is a line of at
-least the opening's length and closes the innermost open container however long its run, and a
-container's fence is longer than every directive fence line anywhere in its body, however deeply a list item or blockquote nests it; a colon run inside a code
-fence or opaque carry is content. Canonical form uses minimal lengths.
-Directive fence lines follow code-fence indentation (up to three spaces relative to their
-container).
+`arg` is one optional bare token whose meaning each node defines (e.g. the panel type). The body is
+block markdown. The closer names the innermost open container and carries nothing after the name;
+one naming another node, or standing where no container is open, is a named error. Opening and
+closing is what nests, so the opener reads the same at every depth, and a closer crosses no list
+item or blockquote edge — a container opened inside one closes inside it. Directive block lines
+follow code-fence indentation (up to three spaces relative to their container); an `!adf:` inside a
+code fence or opaque carry is content.
 
-**Leaf block**: `::name arg {attrs}` — a block-position node with no body, `arg` reading as
-above.
+**Block leaf**: `!adf:name arg {attrs}` — the same opener with no closer, `arg` reading as above.
+
+Which of the two a node takes is its content model, never the spelling: a model taking content is
+written as an opener–closer pair and one taking none as a leaf, so a leaf given a body and a
+container missing its closer are each a named error. A node holding no content whose model takes
+some is an empty pair. A spelled node's content model is contract in consequence — changing one is
+MAJOR (AGENTS.md §8).
 
 Canonical spacing is the only spacing input reads: one space parts the name, `arg` and `{attrs}`,
 and one parts each attribute pair, with no padding inside the braces. Trailing whitespace on a
 directive block line is tolerated in input, never emitted.
 
-**Claiming at block level**, symmetric with inline: a line whose leading run of two or more
-colons is followed immediately by a name character is claimed and must parse fully as a container
-opening or a leaf, else it is a named error. A bare colon-run line is a closing fence while a
-container is open, a named error otherwise. A claimed line also ends a lazy continuation: the
-blockquote or list item whose paragraph CommonMark would fold it into closes instead.
-
 **Attributes**: `{key=value key2="two words"}`. `{attrs}` is optional in every form, and `{}` is
 valid — no attributes. A bare value matches `[A-Za-z0-9_-]+`; any other value is double-quoted
 with JSON string escaping (`\"` `\\` `\n` `\t` `\uXXXX`, …) — total over
@@ -121,22 +135,23 @@ after a directive binds and stay raw. The closing `}` is the first one outside q
 quoted value holds `}` unescaped. All values are strings at the grammar level; each node's section
 assigns types.
 Canonical form orders keys alphabetically, spells values bare wherever allowed, escapes inside
-quotes in the shortest form each escape has, and omits empty `{attrs}` except where the `{` itself
-claims the directive (`:hardBreak{}`). Input reads that spelling alone: keys out of order, a value
-quoted where bare carries it, an escape longer than it need be, an empty `{attrs}` the name or the
-`[content]` already claims, and a number or `json` value outside its canonical JSON spelling are
-each a named error naming the spelling to write instead.
+quotes in the shortest form each escape has, and omits empty `{attrs}` except where the `{` is what
+ends the name (`!adf:hardBreak{}`). Input reads that spelling alone: keys out of order, a value
+quoted where bare carries it, an escape longer than it need be, an empty `{attrs}` on a block line
+or after a `[content]`, and a number or `json` value outside its canonical JSON spelling are each a
+named error naming the spelling to write instead.
 
 **Escaping**: the emitter backslash-escapes whatever literal text would otherwise parse as
-directive syntax — the leading `:` of a would-be directive, `]` inside content, a `{` right
-after a directive's closing `]`, which would otherwise be read as the attributes it has none
-of; outside code spans and code blocks, a backslash before `:` in input yields a literal colon.
+directive syntax — every literal `!adf:`, `]` inside content, a bracket a link's destination and
+title inside content leave unbalanced, a backtick there that would open a code span, a `{` right
+after a directive's closing `]`, which would otherwise be read as the attributes it has none of;
+outside code spans and code blocks, `\!adf:` in input yields the literal text.
 
-**Malformed directives are error results**, named: an unclosed container at end of input, a body
-fence line of the container's length or longer, a bare colon-run line outside any container or
-shorter than the fence it would close, an inline `[content]` or `{attrs}` left unclosed at end of
-line, unparseable or duplicate-keyed attrs, invalid JSON in an opaque carry. Never a silent
-literal-text fallback — a typo that reparses as prose is the silent loss §2 refuses.
+**Malformed directives are error results**, named: an unclosed container at end of input, a closer
+naming no open container or a node other than the innermost open one, a leaf given a body, an
+`!adf:` completing no directive, an inline `[content]` or `{attrs}` left unclosed at end of line,
+unparseable or duplicate-keyed attrs, invalid JSON in an opaque carry. Never a silent literal-text
+fallback — a typo that reparses as prose is the silent loss §2 refuses.
 
 ## The opaque carry (AGENTS.md §3)
 
@@ -146,16 +161,15 @@ a node the emitter spells natively: it restores unreinterpreted, and the next em
 canonically (AGENTS.md §2). Block and inline positions canonicalize differently, each fitting
 where it sits:
 
-- **Block position**: a fenced code block with info string `adf`, body = the node's JSON —
+- **Block position**: a fenced code block with info string `carry`, body = the node's JSON —
   two-space indent, object keys sorted.
-- **Inline position**: `:adf{json="…"}` — compact serialization (keys sorted, no whitespace),
+- **Inline position**: `!adf:carry{json="…"}` — compact serialization (keys sorted, no whitespace),
   JSON-string-escaped into the attribute.
 
-The info string `adf` is reserved: a genuine `codeBlock` whose `language` is exactly `adf` takes
+The info string `carry` is reserved: a genuine `codeBlock` whose `language` is exactly `carry` takes
 the attribute the section below keeps for a language no info string holds, so the reservation
 stays absolute.
-In block-directive positions (`::adf`, `:::adf`) the reserved name is a named error — the
-carry's block form is the fence.
+In block-directive position `!adf:carry` is a named error — the carry's block form is the fence.
 
 ## Raw HTML in input
 
@@ -181,9 +195,9 @@ editor-normal ADF reads an empty attrs object, marks array or content array as t
 (AGENTS.md §2) — the grammar's empty-`{attrs}` omission already collapses the two spellings.
 
 Marks on a block node ride the reserved attribute key `marks` — the node's marks array as a
-`json` value: `::::layoutSection {marks="[{\"attrs\":{\"mode\":\"wide\"},\"type\":\"breakout\"}]"}`.
+`json` value: `!adf:layoutSection {marks="[{\"attrs\":{\"mode\":\"wide\"},\"type\":\"breakout\"}]"}`.
 A section saying its body is inline takes at most one paragraph, whose inline content becomes
-the node's `content`; any other body is a named error, and a node holding no content is the leaf.
+the node's `content`; any other body is a named error, and an empty pair is a node holding none.
 
 A node the sections cannot spell rides the opaque carry: an attrs key its section does not
 list, a value that is not the section's type, or an arg-slot value that is no bare token. In
@@ -200,7 +214,7 @@ form.
 - `codeBlock` — container, body one fenced code block whose info string is the language and whose
   content is the node's. Attributes: `hideLineNumbers` (boolean), `language` (string), `localId`
   (string), `uniqueId` (string), `wrap` (boolean). A language no info string carries back — empty,
-  the reserved `adf`, or holding a backtick, a backslash, a control character, edge whitespace or
+  the reserved `carry`, or holding a backtick, a backslash, a control character, edge whitespace or
   an entity reference — rides the `language` attribute instead and the fence carries no info
   string; writing it in the slot that rule leaves empty, or in both, is a named error. The body is
   one ordinary code block, and a fence's info string decodes escapes and entity references as any
@@ -215,11 +229,11 @@ form.
 - `rule` — leaf. Attributes: `localId` (string).
 
 ````
-:::codeBlock {localId=01a03d5c-9b21-73f4-8e6a-0c47b1d9e2f8 wrap=true}
+!adf:codeBlock {localId=01a03d5c-9b21-73f4-8e6a-0c47b1d9e2f8 wrap=true}
 ```rust
 fn main() {}
 ```
-:::
+!adf:/codeBlock
 ````
 
 ### Panel
@@ -230,9 +244,9 @@ fn main() {}
   panels.
 
 ```
-:::panel warning
+!adf:panel warning
 Check the collation before importing.
-:::
+!adf:/panel
 ```
 
 ### Expand
@@ -241,9 +255,9 @@ Check the collation before importing.
   which. Attributes: `localId` (string), `title` (string).
 
 ```
-:::expand {title="Full build log"}
+!adf:expand {title="Full build log"}
 …
-:::
+!adf:/expand
 ```
 
 ### The media family
@@ -252,19 +266,19 @@ Check the collation before importing.
   (string), `localId` (string), `occurrenceKey` (string), `type` (`external` `file` `link`),
   `url` (string), `width` (number). `file` and `link` media carry `collection` + `id`;
   `external` media carry `url`.
-- `mediaSingle` — container: one `::media`, then optionally one `:::caption`. Attributes:
+- `mediaSingle` — container: one `!adf:media`, then optionally one `!adf:caption`. Attributes:
   `layout` (`align-end` `align-start` `center` `full-width` `wide` `wrap-left` `wrap-right`),
   `localId` (string), `width` (number), `widthType` (`percentage` `pixel`).
 - `caption` — container, inline body. Attributes: `localId` (string).
-- `mediaGroup` — container of `::media` leaves. Attributes: none.
+- `mediaGroup` — container of `!adf:media` leaves. Attributes: none.
 
 ```
-::::mediaSingle {layout=center width=50}
-::media {collection=MediaServicesSample id=4478e39c-cf9b-41d1-ba92-68589487cd75 type=file}
-:::caption
+!adf:mediaSingle {layout=center width=50}
+!adf:media {collection=MediaServicesSample id=4478e39c-cf9b-41d1-ba92-68589487cd75 type=file}
+!adf:caption
 The moon, at night.
-:::
-::::
+!adf:/caption
+!adf:/mediaSingle
 ```
 
 **The CommonMark image.** A paragraph whose entire inline content is one image `![alt](url)` is
@@ -307,27 +321,27 @@ inline layer's ordinary CommonMark escaping yields the pipe; each cell is the in
 one paragraph, trimmed; canonical form pads cells with single spaces and ends rows with `|`
 (optional in input). Named errors: a delimiter or body row whose cell count differs from the
 header's, and an alignment colon in the delimiter row — ADF holds no column alignment. In a
-pipe cell a hard break is `:hardBreak{}` and a literal `|` is `\|`; a `|` inside a quoted
+pipe cell a hard break is `!adf:hardBreak{}` and a literal `|` is `\|`; a `|` inside a quoted
 attribute value is already `\u007c`, so the split never reaches it.
 
 The directive form nests cells as containers of block content inside `tableRow` containers:
 
 ```
-:::::table {isNumberColumnEnabled=true width=760}
-::::tableRow
-:::tableHeader {colspan=2 colwidth="[340,420]"}
+!adf:table {isNumberColumnEnabled=true width=760}
+!adf:tableRow
+!adf:tableHeader {colspan=2 colwidth="[340,420]"}
 Assembly
-:::
-::::
-::::tableRow
-:::tableCell {background="#deebff"}
+!adf:/tableHeader
+!adf:/tableRow
+!adf:tableRow
+!adf:tableCell {background="#deebff"}
 Bolt M8
-:::
-:::tableCell {valign=top}
+!adf:/tableCell
+!adf:tableCell {valign=top}
 40
-:::
-::::
-:::::
+!adf:/tableCell
+!adf:/tableRow
+!adf:/table
 ```
 
 - `table` — container of `tableRow` containers. Attributes: `displayMode` (`default` `fixed`),
@@ -351,14 +365,14 @@ Bolt M8
   free-form; the editor writes `DECIDED`).
 
 ```
-::::taskList {localId=0198f3a2-7c41-7f2e-9b3a-4d8e2c1a6b90}
-:::taskItem DONE {localId=0198f3a2-8d52-70b1-8c4f-5e9f3d2b7ca1}
+!adf:taskList {localId=0198f3a2-7c41-7f2e-9b3a-4d8e2c1a6b90}
+!adf:taskItem DONE {localId=0198f3a2-8d52-70b1-8c4f-5e9f3d2b7ca1}
 Write the spec
-:::
-:::taskItem TODO {localId=0198f3a2-9e63-7d80-a15b-6fa04e3c8db2}
+!adf:/taskItem
+!adf:taskItem TODO {localId=0198f3a2-9e63-7d80-a15b-6fa04e3c8db2}
 Ship it
-:::
-::::
+!adf:/taskItem
+!adf:/taskList
 ```
 
 ### Layout
@@ -368,14 +382,14 @@ Ship it
   `middle` `top`), `width` (number — percent).
 
 ```
-::::layoutSection
-:::layoutColumn {width=50}
+!adf:layoutSection
+!adf:layoutColumn {width=50}
 Left.
-:::
-:::layoutColumn {width=50}
+!adf:/layoutColumn
+!adf:layoutColumn {width=50}
 Right.
-:::
-::::
+!adf:/layoutColumn
+!adf:/layoutSection
 ```
 
 ### Extensions
@@ -387,7 +401,7 @@ Right.
 - `extensionFrame` — container, block body. Attributes: none.
 
 ```
-::extension {extensionKey=toc extensionType="com.atlassian.confluence.macro.core" parameters="{\"maxLevel\":2}"}
+!adf:extension {extensionKey=toc extensionType="com.atlassian.confluence.macro.core" parameters="{\"maxLevel\":2}"}
 ```
 
 ### Sync blocks
@@ -396,7 +410,7 @@ Right.
   `localId` (string), `resourceId` (string).
 
 ```
-::syncBlock {localId=0198f3a2-af74-7e91-b26c-70b15f4d9ec3 resourceId="ari:cloud:confluence:site/page/123"}
+!adf:syncBlock {localId=0198f3a2-af74-7e91-b26c-70b15f4d9ec3 resourceId="ari:cloud:confluence:site/page/123"}
 ```
 
 ## Inline nodes
@@ -404,10 +418,10 @@ Right.
 Attributes and the carry fallback read as in the block sections, the carry in its inline form. Of
 the nodes below, `emoji`, `mention` and `status` spell their `text` attribute in the content slot
 as plain text: `[]` is the empty string, absent content is the absent attribute, non-empty content
-parsing to anything but one unmarked text node — adjacent identical-mark text nodes merged first —
-is a named error, and so is a `text` key in `{attrs}`. An enclosing mark spelling does not reach
-into the slot. The rest take no content, `:text` included; content on a node that takes none is a
-named error.
+parsing to anything but one unmarked text node — adjacent text nodes with identical marks and no
+attributes merged first — is a named error, and so is a `text` key in `{attrs}`. An enclosing mark
+spelling does not reach into the slot. The rest take no content, `!adf:text` included; content on a
+node that takes none is a named error.
 
 - `date` — Attributes: `localId` (string), `timestamp` (string, epoch milliseconds).
 - `emoji` — Attributes: `id` (string), `localId` (string), `shortName` (string, `:name:`), `text`
@@ -424,30 +438,30 @@ named error.
   (string), `style` (string), `text` (string).
 
 ```
-:status[In review]{color=yellow} — :mention[@Mikael]{id=01a032c3-7a7c-775f-a730-2d79351338b4}
+!adf:status[In review]{color=yellow} — !adf:mention[@Mikael]{id=01a032c3-7a7c-775f-a730-2d79351338b4}
 
-Shipped :emoji[🎉]{shortName=":tada:"} on :date{timestamp=1756080000000}.
+Shipped !adf:emoji[🎉]{shortName=":tada:"} on !adf:date{timestamp=1756080000000}.
 ```
 
 **Whitespace CommonMark cannot hold.** A newline inside a text node, and a space or tab where
 CommonMark strips or refuses one — a block's inline content edges, either side of a line break,
 an em, strong or strike spelling's inner edges, a pipe cell's edges — is spelled
-`:text{text="…"}`, the reserved key carrying the node's text, escaped by the attribute grammar
+`!adf:text{text="…"}`, the reserved key carrying the node's text, escaped by the attribute grammar
 and never literal: pipe cells trim and pad. The emitter wraps the whitespace run alone and leaves
-the rest plain text; `markdownToAdf` merges adjacent text nodes carrying identical marks
-(AGENTS.md §2). Input reads that spelling alone: the value is one run of spaces and tabs, or one
-run of newlines, and anything else — a mixed run, or text CommonMark carries plainly — is a named
-error.
+the rest plain text; `markdownToAdf` merges adjacent text nodes carrying identical marks and no
+attributes (AGENTS.md §2). Input reads that spelling alone: the value is one run of spaces and
+tabs, or one run of newlines, and anything else — a mixed run, or text CommonMark carries plainly —
+is a named error.
 
 ```
-:text{text="  "}Two leading spaces held, and one text node split:text{text="\n"}over two lines.
+!adf:text{text="  "}Two leading spaces held, and one text node split!adf:text{text="\n"}over two lines.
 ```
 
 ## Marks
 
 An inline node's marks ride the spelling wrapped around them, never the block sections' reserved
 `marks` key. `code`, `em`, `link`, `strike` and `strong` keep their markdown spellings, and are
-not directive names: `:em[x]` is a named error. `border`, `subsup`, `textColor` and `underline`
+not directive names: `!adf:em[x]` is a named error. `border`, `subsup`, `textColor` and `underline`
 are inline directives, content required non-empty.
 
 - `border` — Attributes: `color` (string, `#rrggbb` or `#rrggbbaa`), `size` (number, 1–3).
@@ -458,7 +472,8 @@ are inline directives, content required non-empty.
 - `underline` — Attributes: none.
 
 A spelling adds its mark to every inline node it wraps, and nesting is the marks array in order,
-outermost first: `_:underline[x]_` gives marks `[em, underline]`, `:underline[_x_]` the reverse.
+outermost first: `_!adf:underline[x]_` gives marks `[em, underline]`, `!adf:underline[_x_]` the
+reverse.
 `adfToMarkdown` nests in the order the array holds rather than sorting it — §2's equality
 restores the array, not a set — and opens each spelling once over the longest run of adjacent
 inline nodes carrying an identical mark, attributes included, at that depth. A run breaks at every
@@ -476,7 +491,7 @@ opaque carry inside a mark spelling is a named error in input: the carry restore
 exactly, marks included (AGENTS.md §3).
 
 ```
-:textColor[**Overdue**]{color="#ae2e24"}, H:subsup[2]{type=sub}O, :underline[signed].
+!adf:textColor[**Overdue**]{color="#ae2e24"}, H!adf:subsup[2]{type=sub}O, !adf:underline[signed].
 
-:border[:mediaInline{collection=contentId-98237 id=01a032c3-7a90-70c9-88f6-c60f710eda07}]{color="#091e42" size=2}
+!adf:border[!adf:mediaInline{collection=contentId-98237 id=01a032c3-7a90-70c9-88f6-c60f710eda07}]{color="#091e42" size=2}
 ```

src/adf-property.test.ts

@@ -0,0 +1,23 @@
+import fc from 'fast-check'
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+import { adfDocument, propertyRuns, propertyTimeout } from './property-harness.ts'
+import { adfToMarkdown } from './markdown/emit/adf-to-markdown.ts'
+import { markdownToAdf } from './markdown/parse/markdown-to-adf.ts'
+import { toEditorNormal } from './adf/editor-normal.ts'
+
+const gateRuns = 1600
+
+test('a generated document refuses to emit, or its markdown reads back to it', { timeout: propertyTimeout }, () => {
+  fc.assert(
+    fc.property(adfDocument, (document) => {
+      const emitted = adfToMarkdown(document)
+      if (!emitted.ok) return
+      const read = markdownToAdf(emitted.value)
+      assert.ok(read.ok, read.ok ? '' : `${read.error.code}: ${read.error.message} — reading ${JSON.stringify(emitted.value)}`)
+      assert.deepEqual(toEditorNormal(read.value), document, `reading ${JSON.stringify(emitted.value)}`)
+    }),
+    propertyRuns(gateRuns),
+  )
+})

src/adf-schema.test.ts

@@ -0,0 +1,183 @@
+import assert from 'node:assert/strict'
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import test from 'node:test'
+import { fileURLToPath } from 'node:url'
+
+import type { AttributeKind, AttributeVocabulary } from './adf/attribute-vocabulary.ts'
+import { blockDirectives } from './adf/block-directives.ts'
+import { inlineDirectives } from './adf/inline-directives.ts'
+import { markAttributes } from './adf/mark-attributes.ts'
+import { blockArgument } from './markdown/block-directive-arguments.ts'
+
+type Held = Map<string, Set<AttributeKind>>
+type Properties = Map<string, SchemaObject[]>
+type SchemaObject = Readonly<Record<string, unknown>>
+type Spelled = [string, Map<string, AttributeKind>]
+
+const carried = ['alignment', 'annotation', 'backgroundColor', 'blockCard', 'bodiedRule', 'breakout', 'dataConsumer', 'embedCard', 'fontSize', 'fragment', 'indentation', 'inlineExtension', 'placeholder']
+const definitionReference = '#/definitions/'
+const gaps = ['layoutSection.columnRuleStyle', 'link.collection', 'link.id', 'link.occurrenceKey', 'rule.color', 'rule.style', 'rule.weight']
+const grammarOwn = ['doc', 'text']
+const readKeywords = ['$ref', 'additionalProperties', 'allOf', 'anyOf', 'enum', 'items', 'maxItems', 'maximum', 'minItems', 'minLength', 'minimum', 'pattern', 'properties', 'required', 'type']
+const root = join(dirname(fileURLToPath(import.meta.url)), '..', 'spec', 'adf-schema')
+const schemaFiles = ['full.json', 'stage-0.json']
+
+test('the ADF JSON Schemas are @atlaskit/adf-schema 57.4.9, vendored byte-exact', () => {
+  const digest = (name: string) => createHash('sha256').update(readFileSync(join(root, name))).digest('hex')
+  assert.equal(digest('full.json'), '75f080928a970250eb8289e9cae5374e3c2a6c0ac3ca22478acaa9d3f39484a3')
+  assert.equal(digest('stage-0.json'), '56747e5a71c0d5f8c58f94180d69e4482f62c08020d66aaf327333681fcc1c8f')
+})
+
+test('the tables spell the attribute names and kinds the ADF JSON Schemas give each type they spell, the pinned gaps apart', () => {
+  const held = schemaTypes()
+  const spelledTypes = spelled()
+  const found: string[] = []
+  const gapsHeld = new Set<string>()
+  for (const [type, spelledKinds] of spelledTypes) {
+    const kinds = held.get(type)
+    if (kinds === undefined) {
+      found.push(`${type}: the tables spell the type, the schema holds no definition of it`)
+      continue
+    }
+    for (const [attribute, schemaKinds] of kinds) {
+      const kind = spelledKinds.get(attribute)
+      const holds = [...schemaKinds].sort().join(' or ')
+      if (kind === undefined && gaps.includes(`${type}.${attribute}`)) gapsHeld.add(`${type}.${attribute}`)
+      else if (kind === undefined) found.push(`${type}.${attribute}: the schema holds ${holds}, the tables spell nothing and the gaps list does not name it`)
+      else if (schemaKinds.size !== 1 || !schemaKinds.has(kind)) found.push(`${type}.${attribute}: the tables spell ${kind}, the schema holds ${holds}`)
+    }
+    for (const [attribute, kind] of spelledKinds) if (!kinds.has(attribute)) found.push(`${type}.${attribute}: the tables spell ${kind}, the schema holds nothing`)
+  }
+  for (const gap of gaps) {
+    if (gapsHeld.has(gap)) continue
+    const [type = '', attribute = ''] = gap.split('.')
+    const spelledKinds = spelledTypes.find(([name]) => name === type)?.[1]
+    const kind = spelledKinds?.get(attribute)
+    if (spelledKinds === undefined) found.push(`${gap}: the gaps list names it, the tables spell no ${type} type`)
+    else if (kind === undefined) found.push(`${gap}: the gaps list names it, the schema holds nothing`)
+    else found.push(`${gap}: the gaps list names it, the tables spell ${kind}`)
+  }
+  assert.deepEqual(found, [])
+})
+
+test("the ADF JSON Schemas hold no type the tables leave unspelled, the pinned carried ones and the grammar's own apart", () => {
+  const held = schemaTypes()
+  const spelledNames = new Set(spelled().map(([type]) => type))
+  const found: string[] = []
+  for (const type of held.keys()) {
+    if (!spelledNames.has(type) && !carried.includes(type) && !grammarOwn.includes(type)) found.push(`${type}: the schema holds the type, the tables spell none of it and the carried list does not name it`)
+  }
+  for (const type of carried) {
+    if (!held.has(type)) found.push(`${type}: the carried list names the type, the schema holds no definition of it`)
+    if (spelledNames.has(type)) found.push(`${type}: the carried list names the type, and the tables spell it`)
+  }
+  assert.deepEqual(found, [])
+})
+
+function spelled(): Spelled[] {
+  return [
+    ...Object.entries(blockDirectives).map(([type, entry]) => spelledType(type, entry.attributes, blockArgument(type))),
+    ...Object.entries(inlineDirectives).map(([type, entry]) => spelledType(type, entry.attributes)),
+    ...Object.entries(markAttributes).map(([type, attributes]) => spelledType(type, attributes)),
+  ]
+}
+
+function spelledType(type: string, attributes: AttributeVocabulary, argument?: string): Spelled {
+  const kinds = new Map(Object.entries(attributes))
+  if (argument !== undefined) kinds.set(argument, 'string')
+  return [type, kinds]
+}
+
+function schemaTypes(): Map<string, Held> {
+  const held = new Map<string, Held>()
+  for (const file of schemaFiles) {
+    const definitions = schemaObject(schemaObject(JSON.parse(readFileSync(join(root, file), 'utf8')), file)['definitions'], `${file} definitions`)
+    for (const [name, definition] of Object.entries(definitions)) {
+      const where = `${file} ${name}`
+      for (const properties of alternatives(schemaObject(definition, where), definitions, where)) {
+        const attributes = (properties.get('attrs') ?? []).flatMap((attrs) => alternatives(attrs, definitions, `${where} attrs`)).flatMap((alternative) => [...alternative])
+        for (const type of (properties.get('type') ?? []).flatMap((schema) => enumStrings(schema, `${where} type`))) {
+          const kinds = held.get(type) ?? new Map<string, Set<AttributeKind>>()
+          held.set(type, kinds)
+          for (const [attribute, schemas] of attributes) {
+            const attributeKinds = kinds.get(attribute) ?? new Set<AttributeKind>()
+            kinds.set(attribute, attributeKinds)
+            for (const schema of schemas) for (const kind of propertyKinds(schema, `${where} ${type}.${attribute}`)) attributeKinds.add(kind)
+          }
+        }
+      }
+    }
+  }
+  return held
+}
+
+function alternatives(schema: SchemaObject, definitions: SchemaObject, where: string): Properties[] {
+  const own = Object.entries(schemaObject(readSchema(schema, where)['properties'] ?? {}, `${where} properties`))
+  let found: Properties[] = [new Map(own.map(([name, property]): [string, SchemaObject[]] => [name, [readSchema(schemaObject(property, `${where} ${name}`), `${where} ${name}`)]]))]
+  if (schema['$ref'] !== undefined) found = intersect(found, alternatives(referenced(schema['$ref'], definitions, where), definitions, `${where} ${String(schema['$ref'])}`))
+  for (const branch of branches(schema['allOf'], `${where} allOf`)) found = intersect(found, alternatives(branch, definitions, `${where} allOf`))
+  if (schema['anyOf'] !== undefined) found = intersect(found, branches(schema['anyOf'], `${where} anyOf`).flatMap((branch) => alternatives(branch, definitions, `${where} anyOf`)))
+  return found
+}
+
+function readSchema(schema: SchemaObject, where: string): SchemaObject {
+  const unread = Object.keys(schema).find((keyword) => !readKeywords.includes(keyword))
+  if (unread !== undefined) return assert.fail(`${where}: the schema holds the keyword ${unread}, which the gate does not read`)
+  const extra = schema['additionalProperties']
+  return extra === undefined || typeof extra === 'boolean' ? schema : assert.fail(`${where}: additionalProperties holds a schema, which the gate does not read`)
+}
+
+function intersect(left: readonly Properties[], right: readonly Properties[]): Properties[] {
+  return left.flatMap((own) =>
+    right.map((other) => {
+      const merged = new Map(own)
+      for (const [name, schemas] of other) merged.set(name, [...(merged.get(name) ?? []), ...schemas])
+      return merged
+    }),
+  )
+}
+
+function referenced(reference: unknown, definitions: SchemaObject, where: string): SchemaObject {
+  const name = typeof reference === 'string' && reference.startsWith(definitionReference) ? reference.slice(definitionReference.length) : undefined
+  return schemaObject(name === undefined ? undefined : definitions[name], `${where}: the reference ${String(reference)}`)
+}
+
+function branches(value: unknown, where: string): SchemaObject[] {
+  if (value === undefined) return []
+  return Array.isArray(value) ? value.map((branch, index) => schemaObject(branch, `${where} ${index}`)) : assert.fail(`${where} is no array of schemas`)
+}
+
+function enumStrings(schema: SchemaObject, where: string): string[] {
+  const values = schema['enum']
+  return Array.isArray(values) ? values.filter((value: unknown): value is string => typeof value === 'string') : assert.fail(`${where}: the type property holds no enum naming the type`)
+}
+
+function propertyKinds(property: SchemaObject, where: string): AttributeKind[] {
+  const type = property['type']
+  if (type === 'boolean') return ['boolean']
+  if (type === 'integer' || type === 'number') return ['number']
+  if (type === 'string') return ['string']
+  if (type === 'array' || type === 'object') return ['json']
+  if (type !== undefined) return assert.fail(`${where}: the schema types it ${JSON.stringify(type)}, which reads as no attribute kind`)
+  const combinator = ['$ref', 'allOf', 'anyOf'].find((keyword) => property[keyword] !== undefined)
+  if (combinator !== undefined) return assert.fail(`${where}: the schema holds the keyword ${combinator}, which the gate reads as no attribute kind`)
+  const values = property['enum']
+  return Array.isArray(values) ? values.map(valueKind) : ['json']
+}
+
+function valueKind(value: unknown): AttributeKind {
+  if (typeof value === 'boolean') return 'boolean'
+  if (typeof value === 'number') return 'number'
+  if (typeof value === 'string') return 'string'
+  return 'json'
+}
+
+function schemaObject(value: unknown, where: string): SchemaObject {
+  return isSchemaObject(value) ? value : assert.fail(`${where} is no JSON Schema object`)
+}
+
+function isSchemaObject(value: unknown): value is SchemaObject {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

src/adf/document.ts

@@ -52,8 +52,8 @@ export function attributeNestingMessage(key: string, type: string, levels: numbe
 }
 
 export function carriesOnly(node: AdfNode, attributes: readonly string[]): boolean {
-  if ((node.marks ?? []).length > 0 || node.text !== undefined) return false
-  return holdsOnly(node.attrs ?? {}, attributes)
+  if (nodeMarks(node).length > 0 || node.text !== undefined) return false
+  return holdsOnly(nodeAttrs(node), attributes)
 }
 
 // Depth is the walks' business, not the shape's: the guard waves a deep document through as blocks and marks do.
@@ -72,6 +72,18 @@ export function isAdfMark(value: unknown): value is AdfMark {
   return !('attrs' in value) || isAttributes(value['attrs'])
 }
 
+export function nodeAttrs(node: { attrs?: AdfAttributes }): Readonly<AdfAttributes> {
+  return node.attrs ?? {}
+}
+
+export function nodeContent(node: { content?: AdfNode[] }): readonly AdfNode[] {
+  return node.content ?? []
+}
+
+export function nodeMarks(node: { marks?: AdfMark[] }): readonly AdfMark[] {
+  return node.marks ?? []
+}
+
 function isNodeArray(value: readonly unknown[]): value is readonly AdfNode[] {
   const pending: unknown[] = [...value]
   while (pending.length > 0) {
@@ -95,23 +107,23 @@ function nestingFault(nodes: readonly AdfNode[]): ConvertFault | undefined {
   while (pending.length > 0) {
     const node = pending.pop()
     if (node === undefined) continue
-    const fault = attributesFault(node.attrs, node.type) ?? marksFault(node.marks)
+    const fault = attributesFault(nodeAttrs(node), node.type) ?? marksFault(nodeMarks(node))
     if (fault !== undefined) return fault
-    pending.push(...(node.content ?? []))
+    pending.push(...nodeContent(node))
   }
   return undefined
 }
 
-function marksFault(marks: readonly AdfMark[] | undefined): ConvertFault | undefined {
-  for (const mark of marks ?? []) {
-    const fault = attributesFault(mark.attrs, mark.type, markAttributeNesting)
+function marksFault(marks: readonly AdfMark[]): ConvertFault | undefined {
+  for (const mark of marks) {
+    const fault = attributesFault(nodeAttrs(mark), mark.type, markAttributeNesting)
     if (fault !== undefined) return fault
   }
   return undefined
 }
 
-function attributesFault(attrs: AdfAttributes | undefined, type: string, levels: number = largestNesting): ConvertFault | undefined {
-  for (const [key, value] of Object.entries(attrs ?? {})) {
+function attributesFault(attrs: AdfAttributes, type: string, levels: number = largestNesting): ConvertFault | undefined {
+  for (const [key, value] of Object.entries(attrs)) {
     if (overNested(value, levels)) return { code: 'unsupported-nesting-depth', message: attributeNestingMessage(key, type, levels) }
   }
   return undefined

src/adf/editor-normal.test.ts

@@ -0,0 +1,77 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+import type { AdfNode } from './document.ts'
+import type { JsonValue } from '../json-value.ts'
+import { toEditorNormal } from './editor-normal.ts'
+
+test('merges adjacent text nodes carrying identical marks, at every level', () => {
+  const content: AdfNode[] = [
+    { text: 'a', type: 'text' },
+    { text: 'b', type: 'text' },
+    { marks: [{ type: 'strong' }], text: 'c', type: 'text' },
+    { marks: [{ attrs: {}, type: 'strong' }], text: 'd', type: 'text' },
+    { type: 'hardBreak' },
+    { text: 'e', type: 'text' },
+    { attrs: { localId: '01a0a06b-5281-7f27-9022-8d3a74b0ab0d' }, text: 'f', type: 'text' },
+    { text: 'g', type: 'text' },
+    { attrs: {}, text: 'h', type: 'text' },
+  ]
+  assert.deepEqual(toEditorNormal({ content: [{ attrs: { panelType: 'info' }, content: [{ content, type: 'paragraph' }], type: 'panel' }], type: 'doc', version: 1 }), {
+    content: [
+      {
+        attrs: { panelType: 'info' },
+        content: [
+          {
+            content: [
+              { text: 'ab', type: 'text' },
+              { marks: [{ type: 'strong' }], text: 'cd', type: 'text' },
+              { type: 'hardBreak' },
+              { text: 'e', type: 'text' },
+              { attrs: { localId: '01a0a06b-5281-7f27-9022-8d3a74b0ab0d' }, text: 'f', type: 'text' },
+              { text: 'gh', type: 'text' },
+            ],
+            type: 'paragraph',
+          },
+        ],
+        type: 'panel',
+      },
+    ],
+    type: 'doc',
+    version: 1,
+  })
+})
+
+test('reads negative zero as zero, as JSON does', () => {
+  const marks = [{ attrs: { size: -0 }, type: 'border' }]
+  assert.deepEqual(
+    toEditorNormal({ content: [{ attrs: { a: -0, b: [{ c: -0 }, null, 'd'] }, content: [{ marks, text: 'x', type: 'text' }], type: 'paragraph' }], type: 'doc', version: -0 }),
+    { content: [{ attrs: { a: 0, b: [{ c: 0 }, null, 'd'] }, content: [{ marks: [{ attrs: { size: 0 }, type: 'border' }], text: 'x', type: 'text' }], type: 'paragraph' }], type: 'doc', version: 0 },
+  )
+})
+
+test('reads an empty attrs object, marks array or content array as the absent key', () => {
+  const paragraph: AdfNode = { attrs: {}, content: [{ attrs: {}, marks: [], text: 'a', type: 'text' }, { marks: [{ attrs: {}, type: 'em' }], text: 'b', type: 'text' }], marks: [], type: 'paragraph' }
+  assert.deepEqual(toEditorNormal({ content: [paragraph, { content: [], type: 'rule' }], type: 'doc', version: 1 }), {
+    content: [{ content: [{ text: 'a', type: 'text' }, { marks: [{ type: 'em' }], text: 'b', type: 'text' }], type: 'paragraph' }, { type: 'rule' }],
+    type: 'doc',
+    version: 1,
+  })
+  assert.deepEqual(toEditorNormal({ content: [], type: 'doc', version: 1 }), { type: 'doc', version: 1 })
+})
+
+test('normalizes blocks and mark attributes nesting far past the levels a recursive walk survives', () => {
+  const levels = 100000
+  let node: AdfNode = { content: [], type: 'paragraph' }
+  for (let level = 0; level < levels; level += 1) node = { content: [node], type: 'blockquote' }
+  let normal = toEditorNormal({ content: [node], type: 'doc', version: 1 }).content?.[0]
+  let depth = 0
+  for (; normal?.content !== undefined; depth += 1) normal = normal.content[0]
+  assert.equal(depth, levels)
+  assert.deepEqual(normal, { type: 'paragraph' })
+  let deep: JsonValue = 1
+  for (let level = 0; level < 2 * levels; level += 1) deep = [deep]
+  const marks = [{ attrs: { deep }, type: 'textColor' }]
+  const merged = toEditorNormal({ content: [{ content: [{ marks, text: 'a', type: 'text' }, { marks, text: 'b', type: 'text' }], type: 'paragraph' }], type: 'doc', version: 1 })
+  assert.deepEqual(merged.content?.[0]?.content?.map((text) => text.text), ['ab'])
+})

src/adf/editor-normal.ts

@@ -1,16 +1,21 @@
-import type { AdfMark, AdfNode } from './document.ts'
+import type { AdfAttributes, AdfDocument, AdfMark, AdfNode } from './document.ts'
+import type { JsonValue } from '../json-value.ts'
+import { nodeAttrs, nodeContent, nodeMarks } from './document.ts'
 import { serializeCanonicalJson } from '../canonical-json.ts'
 
+type JsonContainer = JsonValue[] | { [key: string]: JsonValue }
+
+type NodeHolder = { content?: AdfNode[] }
+
 export function sameMark(candidate: AdfMark, mark: AdfMark): boolean {
   return markKey(candidate) === markKey(mark)
 }
 
-// AGENTS.md §2: adjacent text nodes carrying identical marks are one node.
 export function mergeAdjacentText(nodes: readonly AdfNode[]): AdfNode[] {
   const merged: AdfNode[] = []
   for (const node of nodes) {
     const previous = merged[merged.length - 1]
-    if (previous !== undefined && previous.type === 'text' && node.type === 'text' && sameMarks(previous, node)) {
+    if (previous !== undefined && mergesText(previous) && mergesText(node) && sameMarks(previous, node)) {
       merged[merged.length - 1] = { ...previous, text: `${previous.text ?? ''}${node.text ?? ''}` }
       continue
     }
@@ -19,8 +24,61 @@ export function mergeAdjacentText(nodes: readonly AdfNode[]): AdfNode[] {
   return merged
 }
 
+export function toEditorNormal(document: AdfDocument): AdfDocument {
+  const normal: AdfDocument = { type: document.type, version: Object.is(document.version, -0) ? 0 : document.version }
+  const pending: { holder: NodeHolder; source: NodeHolder }[] = [{ holder: normal, source: document }]
+  for (let entry = pending.pop(); entry !== undefined; entry = pending.pop()) {
+    const content = mergeAdjacentText(nodeContent(entry.source))
+    if (content.length === 0) continue
+    entry.holder.content = content.map((source) => {
+      const holder = normalNode(source)
+      pending.push({ holder, source })
+      return holder
+    })
+  }
+  return normal
+}
+
+function normalNode(node: AdfNode): AdfNode {
+  const normal: AdfNode = { type: node.type }
+  const attrs = normalAttributes(nodeAttrs(node))
+  if (attrs !== undefined) normal.attrs = attrs
+  const marks = nodeMarks(node).map(normalMark)
+  if (marks.length > 0) normal.marks = marks
+  if (node.text !== undefined) normal.text = node.text
+  return normal
+}
+
+function normalMark(mark: AdfMark): AdfMark {
+  const attrs = normalAttributes(nodeAttrs(mark))
+  return attrs === undefined ? { type: mark.type } : { attrs, type: mark.type }
+}
+
+function normalAttributes(attrs: AdfAttributes): AdfAttributes | undefined {
+  if (Object.keys(attrs).length === 0) return undefined
+  const normal = { ...attrs }
+  const pending: JsonContainer[] = [normal]
+  for (let held = pending.pop(); held !== undefined; held = pending.pop()) {
+    if (Array.isArray(held)) for (const [index, value] of held.entries()) held[index] = normalValue(value, pending)
+    else for (const [key, value] of Object.entries(held)) held[key] = normalValue(value, pending)
+  }
+  return normal
+}
+
+function normalValue(value: JsonValue, pending: JsonContainer[]): JsonValue {
+  if (Object.is(value, -0)) return 0
+  if (value === null || typeof value !== 'object') return value
+  const copy = Array.isArray(value) ? [...value] : { ...value }
+  pending.push(copy)
+  return copy
+}
+
+function mergesText(node: AdfNode): boolean {
+  return node.type === 'text' && Object.keys(nodeAttrs(node)).length === 0
+}
+
 function sameMarks(previous: AdfNode, node: AdfNode): boolean {
-  return marksKey(previous.marks ?? []) === marksKey(node.marks ?? [])
+  return marksKey(nodeMarks(previous)) === marksKey(nodeMarks(node))
 }
 
 function marksKey(marks: readonly AdfMark[]): string {
@@ -28,5 +86,5 @@ function marksKey(marks: readonly AdfMark[]): string {
 }
 
 function markKey(mark: AdfMark): string {
-  return `${mark.type} ${serializeCanonicalJson(mark.attrs ?? {}, 'compact')}`
+  return `${mark.type} ${serializeCanonicalJson(nodeAttrs(mark), 'compact')}`
 }

src/canonical-json.test.ts

@@ -1,6 +1,7 @@
 import assert from 'node:assert/strict'
 import test from 'node:test'
 
+import type { JsonValue } from './json-value.ts'
 import { serializeCanonicalJson } from './canonical-json.ts'
 
 test('sorts object keys recursively', () => {
@@ -39,3 +40,15 @@ test('leaves non-ASCII raw', () => {
 test('spells scalars in canonical JSON', () => {
   assert.equal(serializeCanonicalJson([null, true, false, 0, -1.5, 'a"b'], 'compact'), '[null,true,false,0,-1.5,"a\\"b"]')
 })
+
+test('spells a value nesting far past the levels a recursive walk survives', () => {
+  const levels = 200000
+  let array: JsonValue = 1
+  let object: JsonValue = 1
+  for (let level = 0; level < levels; level += 1) {
+    array = [array]
+    object = { a: object }
+  }
+  assert.equal(serializeCanonicalJson(array, 'compact'), `${'['.repeat(levels)}1${']'.repeat(levels)}`)
+  assert.equal(serializeCanonicalJson(object, 'compact'), `${'{"a":'.repeat(levels)}1${'}'.repeat(levels)}`)
+})

src/canonical-json.ts

@@ -2,28 +2,42 @@ import type { JsonValue } from './json-value.ts'
 
 export type JsonSpelling = 'compact' | 'two-space'
 
+type Member = { label: string; value: JsonValue }
+
+type Pending = string | { depth: number; value: JsonValue }
+
 export function serializeCanonicalJson(value: JsonValue, spelling: JsonSpelling): string {
-  return serialize(value, spelling === 'compact' ? '' : '  ', 0)
+  const indent = spelling === 'compact' ? '' : '  '
+  const text: string[] = []
+  const pending: Pending[] = [{ depth: 0, value }]
+  for (let next = pending.pop(); next !== undefined; next = pending.pop()) {
+    if (typeof next === 'string') {
+      text.push(next)
+      continue
+    }
+    const { depth, value: held } = next
+    if (Array.isArray(held)) schedule(pending, '[', held.map((item) => ({ label: '', value: item })), ']', indent, depth)
+    else if (held !== null && typeof held === 'object') schedule(pending, '{', objectMembers(held, indent), '}', indent, depth)
+    else text.push(JSON.stringify(held))
+  }
+  return text.join('')
 }
 
-function serialize(value: JsonValue, indent: string, depth: number): string {
-  if (Array.isArray(value)) {
-    if (value.length === 0) return '[]'
-    const items = value.map((item) => serialize(item, indent, depth + 1))
-    return `[${join(items, indent, depth)}]`
-  }
-  if (value !== null && typeof value === 'object') {
-    const keys = Object.keys(value).sort()
-    if (keys.length === 0) return '{}'
-    const separator = indent === '' ? ':' : ': '
-    const entries = keys.map((key) => `${JSON.stringify(key)}${separator}${serialize(value[key] ?? null, indent, depth + 1)}`)
-    return `{${join(entries, indent, depth)}}`
-  }
-  return JSON.stringify(value)
+function objectMembers(value: { [key: string]: JsonValue }, indent: string): Member[] {
+  const separator = indent === '' ? ':' : ': '
+  return Object.keys(value)
+    .sort()
+    .map((key) => ({ label: `${JSON.stringify(key)}${separator}`, value: value[key] ?? null }))
 }
 
-function join(parts: readonly string[], indent: string, depth: number): string {
-  if (indent === '') return parts.join(',')
-  const inner = `\n${indent.repeat(depth + 1)}`
-  return `${inner}${parts.join(`,${inner}`)}\n${indent.repeat(depth)}`
+function schedule(pending: Pending[], open: string, members: readonly Member[], close: string, indent: string, depth: number): void {
+  if (members.length === 0) {
+    pending.push(`${open}${close}`)
+    return
+  }
+  const inner = indent === '' ? '' : `\n${indent.repeat(depth + 1)}`
+  const scheduled: Pending[] = []
+  for (const [index, member] of members.entries()) scheduled.push(`${index === 0 ? open : ','}${inner}${member.label}`, { depth: depth + 1, value: member.value })
+  scheduled.push(indent === '' ? close : `\n${indent.repeat(depth)}${close}`)
+  for (const item of scheduled.reverse()) pending.push(item)
 }

src/corpus.test.ts

@@ -9,10 +9,12 @@ import { isAdfDocument } from './adf/document.ts'
 import { isJsonValue } from './json-value.ts'
 import { markdownToAdf } from './markdown/parse/markdown-to-adf.ts'
 import { serializeCanonicalJson } from './canonical-json.ts'
+import { toEditorNormal } from './adf/editor-normal.ts'
 
 const corpusRoot = join(dirname(fileURLToPath(import.meta.url)), '..', 'corpus')
 const errorsRoot = join(corpusRoot, 'errors')
 const normalizationRoot = join(corpusRoot, 'normalization')
+const realPayloadsRoot = join(corpusRoot, 'real-payloads')
 const roundTripRoot = join(corpusRoot, 'round-trip')
 
 const roundTripDirectories = ['block-nodes', 'combinations', 'commonmark-subset', 'inline-nodes', 'opaque-carry']
@@ -59,7 +61,7 @@ function corpusJsonPaths(): string[] {
 }
 
 test('every corpus directory is a kind the runner reads', () => {
-  assert.deepEqual(directoryNames(corpusRoot), ['commonmark-spec', 'errors', 'normalization', 'round-trip'])
+  assert.deepEqual(directoryNames(corpusRoot), ['commonmark-spec', 'errors', 'normalization', 'real-payloads', 'round-trip'])
 })
 
 test('every round-trip directory is a kind the runner reads', () => {
@@ -95,7 +97,7 @@ for (const directory of roundTripDirectories) {
       assert.ok(isAdfDocument(expected), `${name}.json is not an ADF document`)
       const result = markdownToAdf(readFileSync(join(roundTripRoot, directory, `${name}.md`), 'utf8'))
       assert.ok(result.ok, result.ok ? '' : `${result.error.code}: ${result.error.message}`)
-      assert.deepEqual(result.value, expected)
+      assert.deepEqual(toEditorNormal(result.value), expected)
     })
   }
 }
@@ -106,18 +108,6 @@ function roundTripFixtures(): { name: string; path: string }[] {
   )
 }
 
-test('no two round-trip documents share one markdown spelling', () => {
-  const spellings = new Map<string, string>()
-  for (const fixture of roundTripFixtures()) {
-    const parsed: unknown = JSON.parse(readFileSync(fixture.path, 'utf8'))
-    assert.ok(isAdfDocument(parsed), `${fixture.name} is not an ADF document`)
-    const result = adfToMarkdown(parsed)
-    assert.ok(result.ok, result.ok ? '' : `${result.error.code}: ${result.error.message}`)
-    assert.equal(spellings.get(result.value), undefined, `${fixture.name} and ${spellings.get(result.value)} share one markdown spelling`)
-    spellings.set(result.value, fixture.name)
-  }
-})
-
 test('no round-trip fixture repeats the document another holds', () => {
   const documents = new Map<string, string>()
   for (const fixture of roundTripFixtures()) {
@@ -184,12 +174,28 @@ for (const name of pairedNames(normalizationRoot, '.md', '.json')) {
     assert.ok(isAdfDocument(expected), `${name}.json is not an ADF document`)
     const result = markdownToAdf(readFileSync(join(normalizationRoot, `${name}.md`), 'utf8'))
     assert.ok(result.ok, result.ok ? '' : `${result.error.code}: ${result.error.message}`)
-    assert.deepEqual(result.value, expected)
+    assert.deepEqual(toEditorNormal(result.value), expected)
     const emitted = adfToMarkdown(result.value)
     assert.ok(emitted.ok, emitted.ok ? '' : `${emitted.error.code}: ${emitted.error.message}`)
     const again = markdownToAdf(emitted.value)
     assert.ok(again.ok, again.ok ? '' : `${again.error.code}: ${again.error.message}`)
-    assert.deepEqual(again.value, expected)
+    assert.deepEqual(toEditorNormal(again.value), expected)
+  })
+}
+
+test('real-payloads holds payloads', () => {
+  assert.ok(names(realPayloadsRoot, '.json').length > 0)
+})
+
+for (const name of names(realPayloadsRoot, '.json')) {
+  test(`real-payloads/${name} emits markdown that reads back to it`, () => {
+    const payload: unknown = JSON.parse(readFileSync(join(realPayloadsRoot, `${name}.json`), 'utf8'))
+    assert.ok(isAdfDocument(payload), `${name}.json is not an ADF document`)
+    const emitted = adfToMarkdown(payload)
+    assert.ok(emitted.ok, emitted.ok ? '' : `${emitted.error.code}: ${emitted.error.message}`)
+    const parsed = markdownToAdf(emitted.value)
+    assert.ok(parsed.ok, parsed.ok ? '' : `${parsed.error.code}: ${parsed.error.message}`)
+    assert.deepEqual(toEditorNormal(parsed.value), payload)
   })
 }
 

src/markdown-property.test.ts

@@ -0,0 +1,432 @@
+import fc from 'fast-check'
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+import type { AdfDocument } from './adf/document.ts'
+import type { Arbitrary, DepthIdentifier } from 'fast-check'
+import type { AttributeVocabulary } from './adf/attribute-vocabulary.ts'
+import type { JsonValue } from './json-value.ts'
+import type { Result } from './result.ts'
+import { adfDocument, attributes, jsonKey, jsonValue, markdownPieces, propertyRuns, propertyTimeout, textOf } from './property-harness.ts'
+import { adfToMarkdown } from './markdown/emit/adf-to-markdown.ts'
+import { blockArgument } from './markdown/block-directive-arguments.ts'
+import { blockDirectives } from './adf/block-directives.ts'
+import { carryName } from './markdown/opaque-carry.ts'
+import { fencedCodeBlock } from './markdown/backtick-runs.ts'
+import { inlineDirectives } from './adf/inline-directives.ts'
+import { listBreakName } from './markdown/list-break.ts'
+import { markAttributes } from './adf/mark-attributes.ts'
+import { markSpelling } from './markdown/mark-spellings.ts'
+import { markdownToAdf } from './markdown/parse/markdown-to-adf.ts'
+import { marksAttribute } from './markdown/block-directive-marks.ts'
+import { nodeContent, nodeMarks } from './adf/document.ts'
+import { serializeCanonicalJson } from './canonical-json.ts'
+import { spellAttributes, spellJsonAttribute, spellLeafDirective, spellStringAttribute, spellVocabulary } from './markdown/directive-syntax.ts'
+import { textDirectiveName } from './markdown/text-directive.ts'
+import { toEditorNormal } from './adf/editor-normal.ts'
+import { vocabularyPairs } from './adf/attribute-vocabulary.ts'
+
+type Choice = { arbitrary: Arbitrary<string>; hostile?: true; weight: number }
+
+type Edit = [at: number, removed: number, inserted: string]
+
+type InlineMarkdown = { destination: Arbitrary<string>; inlines: Arbitrary<string>; label: Arbitrary<string>; oneLine: Arbitrary<string>; text: Arbitrary<string>; word: Arbitrary<string> }
+
+type LeafMarkdown = { fencedCode: Arbitrary<string>; leafBlock: Arbitrary<string> }
+
+const commonMarkTypes = new Set(['blockquote', 'bulletList', 'codeBlock', 'hardBreak', 'heading', 'listItem', 'orderedList', 'paragraph', 'rule', 'text'])
+const directiveShapedFloor = 330
+const fixpointFloor = 600
+const gateRuns = 1000
+const markdownMarkTypes = new Set(Object.keys(markAttributes).filter((type) => markSpelling(type)?.kind !== 'directive'))
+
+const vocabularies = [...Object.values(blockDirectives).map((directive) => directive.attributes), ...Object.values(inlineDirectives).map((directive) => directive.attributes), ...Object.values(markAttributes)]
+const attributeKeys = [
+  ...new Set([...vocabularies.flatMap((vocabulary) => Object.keys(vocabulary)), ...Object.keys(blockDirectives).flatMap((type) => blockArgument(type) ?? []), marksAttribute, 'json', textDirectiveName]),
+]
+const directiveNames = [...Object.keys(blockDirectives), ...Object.keys(inlineDirectives), ...Object.keys(markAttributes), carryName, listBreakName, textDirectiveName]
+
+// Hostile generation reaches refusals; clean generation holds none a single piece would trip, so a whole document reaches the emitter.
+function choose(hostile: boolean, choices: readonly Choice[], depth?: { depthIdentifier: DepthIdentifier; maxDepth: number }): Arbitrary<string> {
+  const held = choices.filter((choice) => hostile || choice.hostile !== true).map(({ arbitrary, weight }) => ({ arbitrary, weight }))
+  return depth === undefined ? fc.oneof(...held) : fc.oneof({ ...depth, depthSize: 'small' }, ...held)
+}
+
+const bareToken = fc.stringMatching(/^[A-Za-z0-9_-]{1,8}$/)
+const prose = fc.stringMatching(/^[A-Za-z][a-z]{0,6}(?: [a-z]{1,6}){0,3}$/)
+const cleanText = fc.string({ maxLength: 12, unit: fc.constantFrom(...'aZ09 \t!"#$%&\'()*+,-./;=?@[\\]^_`{}~é\xa0🎉') })
+const syntaxTokens = fc.constantFrom(
+  ...[...String.fromCodePoint(0x0, 0xb, 0xc, 0x85, 0xa0, 0x200b, 0x2028, 0x3000, 0xfeff)],
+  '\n',
+  '\r\n',
+  '\r',
+  '\t',
+  '    ',
+  '  \n',
+  '\\\n',
+  '**',
+  '__',
+  '~~',
+  '***',
+  '```',
+  '~~~',
+  '![',
+  '](',
+  '{}',
+  '::',
+  ':::',
+  '> ',
+  '- ',
+  '* ',
+  '1. ',
+  '2) ',
+  '# ',
+  '---',
+  '===',
+  '| ',
+  ' |',
+  '<!--',
+  '-->',
+  '&amp;',
+  '&#',
+)
+const piece = fc.oneof(markdownPieces, syntaxTokens)
+
+const namedEntity = fc.constantFrom('&amp;', '&lt;', '&quot;', '&copy;', '&nbsp;', '&ouml;', '&bogus;', '&amp', '&#;', '&AMP;', '&ngE;')
+const numericEntity = fc
+  .tuple(fc.oneof(fc.integer({ max: 0x7f, min: 0 }), fc.integer({ max: 0xffff, min: 0 }), fc.integer({ max: 0x110000, min: 0 })), fc.boolean())
+  .map(([code, hex]) => (hex ? `&#x${code.toString(16)};` : `&#${code};`))
+const escape = fc.constantFrom(...'!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~a \n').map((escaped) => `\\${escaped}`)
+const backticks = fc.integer({ max: 3, min: 1 }).map((count) => '`'.repeat(count))
+const codeSpan = fc
+  .tuple(backticks, fc.oneof(prose, textOf(0)), fc.oneof({ arbitrary: fc.constant(undefined), weight: 4 }, { arbitrary: backticks, weight: 1 }))
+  .map(([opener, body, closer]) => `${opener}${body}${closer ?? opener}`)
+const autolink = fc.oneof(
+  fc.tuple(fc.constantFrom('http://', 'https://', 'mailto:', 'ab:', 'x+y.z-:'), prose).map(([scheme, rest]) => `<${scheme}${rest.replaceAll(' ', '/')}>`),
+  fc.stringMatching(/^<[a-z.+]{1,6}@[a-z-]{1,6}(?:\.[a-z]{1,4})?>$/),
+)
+const hostileAutolink = fc.tuple(fc.constantFrom('http://', 'ab:', 'a:'), textOf(0)).map(([scheme, rest]) => `<${scheme}${rest}>`)
+const inlineHtml = fc.constantFrom('<span>', '</span>', '<a href="x">', "<b class='y'/>", '<!-- c -->', '<!---->', '<?x?>', '<![CDATA[x]]>', '<!X y>', '<br/>', '<b', '<3', '< a>')
+const hardBreak = fc.constantFrom('\\\n', '  \n', '\n', ':hardBreak{}')
+const textDirective = fc.constantFrom(' ', '  ', '\t', '\n', '\n\n').map((held) => `:${textDirectiveName}{${textDirectiveName}=${spellStringAttribute(held)}}`)
+const hostileTextDirective = fc.constantFrom(' \n', 'a', '').map((held) => `:${textDirectiveName}{${textDirectiveName}=${spellStringAttribute(held)}}`)
+
+const url = fc.stringMatching(/^https?:\/\/[a-z]{1,6}\.[a-z]{2,3}(?:\/[a-z0-9()]{0,5})?$/)
+const title = (text: Arbitrary<string>) => fc.oneof(fc.constant(''), text.map((held) => ` "${held}"`), text.map((held) => ` '${held}'`), text.map((held) => ` (${held})`))
+
+const attributeValue = fc.oneof(
+  { arbitrary: bareToken, weight: 3 },
+  { arbitrary: fc.constantFrom('true', 'false', '0', '1', '3', '-1', '1.5', '1e2', '"1"', '01', 'null', '"[]"', '"{}"', '"#deebff"'), weight: 2 },
+  { arbitrary: textOf(0).map(spellStringAttribute), weight: 3 },
+  { arbitrary: jsonValue.map(spellJsonAttribute), weight: 2 },
+  { arbitrary: textOf(0).map((held) => JSON.stringify(held)), weight: 1 },
+  { arbitrary: textOf(0).map((held) => `"${held}`), weight: 1 },
+)
+const attributePairs = fc.uniqueArray(fc.tuple(fc.oneof({ arbitrary: fc.constantFrom(...attributeKeys), weight: 4 }, { arbitrary: bareToken, weight: 1 }), attributeValue), {
+  maxLength: 3,
+  minLength: 1,
+  selector: ([key]) => key,
+})
+const hostileAttributes = fc.oneof(
+  { arbitrary: fc.constant(''), weight: 3 },
+  {
+    arbitrary: fc.tuple(attributePairs, fc.boolean()).map(([pairs, sorted]) => {
+      const ordered = sorted ? pairs.toSorted(([left], [right]) => (left < right ? -1 : 1)) : pairs
+      return `{${ordered.map(([key, value]) => `${key}=${value}`).join(' ')}}`
+    }),
+    weight: 6,
+  },
+  { arbitrary: fc.constantFrom('{}', '{ }', '{a}', '{a=}', '{=b}', '{a=b', '{a=b  c=d}', '{a="}"}'), weight: 1 },
+)
+
+function tableAttributes(vocabulary: AttributeVocabulary, slot?: string): Arbitrary<string> {
+  return attributes(vocabulary).map((attrs) => spellAttributes(spellVocabulary(vocabularyPairs(attrs, vocabulary, slot === undefined ? [] : [slot]) ?? [])))
+}
+
+const directiveName = fc.oneof({ arbitrary: fc.constantFrom(...directiveNames), weight: 8 }, { arbitrary: fc.stringMatching(/^[A-Za-z0-9-]{1,6}$/), weight: 1 })
+const hostileArgument = fc.oneof(
+  { arbitrary: fc.constant(''), weight: 3 },
+  { arbitrary: fc.constantFrom(' info', ' warning', ' custom', ' DONE', ' TODO'), weight: 2 },
+  { arbitrary: fc.oneof(bareToken.map((held) => ` ${held}`), fc.constantFrom('  info', ' a b', ' "a"')), weight: 1 },
+)
+
+function directiveHeader(colons: number, name: string, argument: string, attrs: string): string {
+  return `${':'.repeat(colons)}${name}${argument}${attrs === '' ? '' : ` ${attrs}`}`
+}
+
+function container(header: (colons: number) => string, body: string, closer: number | null): string {
+  const colons = Math.max(2, ...[...body.matchAll(/:{2,}/g)].map(([run]) => run.length)) + 1
+  return [header(colons), ...(body === '' ? [] : [body]), ':'.repeat(closer ?? colons)].join('\n')
+}
+
+const carriedNode = fc.oneof(
+  fc.tuple(fc.constantFrom('mention', 'paragraph', 'status', 'widget'), fc.dictionary(jsonKey, jsonValue, { maxKeys: 2, noNullPrototype: true })).map(([type, attrs]): JsonValue => ({ attrs, type })),
+  textOf(1).map((held): JsonValue => ({ text: held, type: 'text' })),
+)
+const inlineCarry = carriedNode.map((node) => `:${carryName}{json=${spellStringAttribute(serializeCanonicalJson(node, 'compact'))}}`)
+const hostileInlineCarry = fc.oneof(carriedNode, jsonValue).map((node) => `:${carryName}{json=${spellStringAttribute(JSON.stringify(node, null, 1))}}`)
+const blockCarry = carriedNode.map((node) => fencedCodeBlock(carryName, serializeCanonicalJson(node, 'two-space')))
+const hostileBlockCarry = fc.oneof(carriedNode, jsonValue).map((node) => fencedCodeBlock(carryName, JSON.stringify(node)))
+
+function prefixLines(body: string, first: string, rest: (index: number) => string): string {
+  return body
+    .split('\n')
+    .map((line, index) => (index === 0 ? `${first}${line}` : line === '' ? rest(index).trimEnd() : `${rest(index)}${line}`))
+    .join('\n')
+}
+
+const separator = fc.oneof({ arbitrary: fc.constant('\n\n'), weight: 4 }, { arbitrary: fc.constant('\n'), weight: 3 }, { arbitrary: fc.constantFrom('\n\n\n', '\n \n', '\n\t\n'), weight: 1 })
+const quotePrefix = fc.oneof({ arbitrary: fc.constant('> '), weight: 6 }, { arbitrary: fc.constantFrom('>', ' > ', '>  ', '>\t', ''), weight: 1 })
+const listMarker = fc.oneof(
+  { arbitrary: fc.constantFrom('-', '*', '+'), weight: 3 },
+  {
+    arbitrary: fc
+      .tuple(fc.oneof({ arbitrary: fc.integer({ max: 3, min: 0 }), weight: 4 }, { arbitrary: fc.integer({ max: 1000000000, min: 0 }), weight: 1 }), fc.constantFrom('.', ')'))
+      .map(([start, delimiter]) => `${start}${delimiter}`),
+    weight: 2,
+  },
+)
+const indentDrift = fc.oneof({ arbitrary: fc.constant(0), weight: 6 }, { arbitrary: fc.integer({ max: 2, min: -2 }), weight: 1 })
+const closerDrift = fc.option(fc.integer({ max: 5, min: 2 }), { freq: 6 })
+
+function markdownOf(hostile: boolean): Arbitrary<string> {
+  const inline = inlineMarkdown(hostile)
+  return blockMarkdown(hostile, inline, leafBlocks(hostile, inline))
+}
+
+function inlineMarkdown(hostile: boolean): InlineMarkdown {
+  const inlineDepth = fc.createDepthIdentifier()
+  const text = hostile ? fc.oneof(cleanText, textOf(0)) : cleanText
+  const word = fc.oneof({ arbitrary: prose, weight: 3 }, { arbitrary: text.filter((held) => held !== ''), weight: 2 })
+  const destination = fc.oneof(url, text, fc.stringMatching(/^<[0-9.#][a-z0-9 ]{0,6}>$/), fc.constant(''), ...(hostile ? [text.map((held) => `<${held}>`)] : []))
+  const label = fc.oneof(prose, word)
+
+  const { inlines } = fc.letrec<{ inline: string; inlines: string }>((tie) => ({
+    inline: choose(
+      hostile,
+      [
+        { arbitrary: word, weight: 12 },
+        { arbitrary: fc.oneof(codeSpan, autolink, namedEntity, numericEntity, escape, hardBreak, textDirective, inlineCarry), weight: 8 },
+        { arbitrary: fc.oneof(hostileAutolink, hostileInlineCarry, hostileTextDirective, inlineHtml, piece), hostile: true, weight: 4 },
+        {
+          arbitrary: fc
+            .tuple(fc.constantFrom('*', '_', '**', '__', '***', '~~', '~'), fc.constantFrom('', '', ' '), tie('inlines'), fc.constantFrom('', '', ' '), fc.option(fc.constantFrom('*', '_', '**', '~~'), { freq: 4 }))
+            .map(([opener, inside, body, closing, closer]) => `${opener}${inside}${body}${closing}${closer ?? opener}`),
+          weight: 4,
+        },
+        {
+          arbitrary: fc
+            .tuple(fc.constantFrom('', '', hostile ? '!' : ''), tie('inlines'), fc.oneof(fc.tuple(destination, title(text)).map(([target, titled]) => `(${target}${titled})`), label.map((held) => `[${held}]`), fc.constantFrom('', '[]')))
+            .map(([image, content, target]) => `${image}[${content}]${target}`),
+          weight: 3,
+        },
+        {
+          arbitrary: fc.oneof(
+            ...Object.entries(inlineDirectives).map(([name, directive]) =>
+              fc
+                .tuple(directive.textAttribute === undefined ? fc.constant(null) : fc.option(hostile ? word : prose), tableAttributes(directive.attributes, directive.textAttribute))
+                .map(([slot, attrs]) => (slot === null ? spellLeafDirective(name, attrs) : `:${name}[${slot}]${attrs}`)),
+            ),
+            ...Object.entries(markAttributes)
+              .filter(([name]) => hostile || markSpelling(name)?.kind === 'directive')
+              .map(([name, vocabulary]) => fc.tuple(tie('inlines'), tableAttributes(vocabulary)).map(([content, attrs]) => `:${name}[${content}]${attrs}`)),
+          ),
+          weight: 2,
+        },
+        {
+          arbitrary: fc.tuple(directiveName, fc.option(tie('inlines'), { freq: 3 }), hostileAttributes).map(([name, content, attrs]) => `:${name}${content === null ? '' : `[${content}]`}${attrs}`),
+          hostile: true,
+          weight: 2,
+        },
+      ],
+      { depthIdentifier: inlineDepth, maxDepth: 3 },
+    ),
+    inlines: fc.array(tie('inline'), { depthIdentifier: inlineDepth, maxLength: 4, minLength: 1 }).map((parts) => parts.join('')),
+  }))
+  return { destination, inlines, label, oneLine: inlines.map((held) => held.replace(/[\n\r]/g, ' ')), text, word }
+}
+
+function leafBlocks(hostile: boolean, { destination, inlines, label, oneLine, text, word }: InlineMarkdown): LeafMarkdown {
+  const fencedCode = fc
+    .tuple(
+      fc.constantFrom('```', '```', '~~~', '````', '``'),
+      fc.oneof(fc.constant(''), bareToken, text),
+      fc.array(fc.oneof(prose, text, fc.constantFrom('```', '~~~', ':::', '    x')), { maxLength: 3 }),
+      fc.constantFrom('', '', '`', '~', 'none'),
+    )
+    .map(([fence, info, lines, closer]) => [`${fence}${info}`, ...lines, ...(closer === 'none' ? [] : [`${fence}${closer}`])].join('\n'))
+  const pipeTable = fc
+    .record({
+      body: fc.array(fc.array(oneLine, { maxLength: 3 }), { maxLength: 2 }),
+      delimiter: fc.array(fc.constantFrom('---', '-', ':--', '--:', ':-:', '', '==='), { maxLength: 3, minLength: 1 }),
+      header: fc.array(oneLine, { maxLength: 3, minLength: 1 }),
+      leading: fc.boolean(),
+      regular: hostile ? fc.boolean() : fc.constant(true),
+      trailing: fc.boolean(),
+    })
+    .map(({ body, delimiter, header, leading, regular, trailing }) => {
+      const row = (cells: readonly string[]) => (regular || leading ? `| ${cells.join(' | ')}` : cells.join(' | ')) + (regular || trailing ? ' |' : '')
+      const width = (cells: readonly string[]) => (regular ? header.map((_, index) => cells[index] ?? '') : cells)
+      return [row(header), row(regular ? header.map(() => '---') : delimiter), ...body.map((cells) => row(width(cells)))].join('\n')
+    })
+
+  const leafBlock = choose(hostile, [
+    {
+      arbitrary: fc
+        .tuple(fc.integer({ max: 7, min: 1 }), fc.constantFrom(' ', ' ', '', '\t'), oneLine, fc.constantFrom('', '', ' #', '#', ' ##  '))
+        .map(([level, gap, content, closer]) => `${'#'.repeat(level)}${gap}${content}${closer}`),
+      weight: 3,
+    },
+    {
+      arbitrary: fc.tuple(inlines, fc.constantFrom('=', '-'), fc.integer({ max: 4, min: 1 }), fc.constantFrom('', ' ')).map(([content, underline, length, trailing]) => `${content}\n${underline.repeat(length)}${trailing}`),
+      weight: 2,
+    },
+    { arbitrary: fc.constantFrom('---', '***', '___', '- - -', ' * * *', '_____', '--', '*-*'), weight: 1 },
+    { arbitrary: fencedCode, weight: 2 },
+    { arbitrary: blockCarry, weight: 1 },
+    {
+      arbitrary: fc.tuple(fc.constantFrom('    ', '\t', '     '), fc.array(fc.oneof(prose, text), { maxLength: 3, minLength: 1 })).map(([indent, lines]) => lines.map((line) => `${indent}${line}`).join('\n')),
+      weight: 1,
+    },
+    { arbitrary: pipeTable, weight: 2 },
+    { arbitrary: fc.tuple(label, destination, title(text)).map(([name, target, titled]) => `[${name}]: ${target}${titled}`), weight: 1 },
+    { arbitrary: fc.tuple(word, fc.oneof(url, fc.constant(''))).map(([alt, target]) => `![${alt}](${target})`), weight: 1 },
+    { arbitrary: hostileBlockCarry, hostile: true, weight: 1 },
+    {
+      arbitrary: fc.constantFrom('<div>\ntext\n</div>', '<!-- comment -->', '<pre>\nx\n</pre>', '<?php echo 1; ?>', '<!DOCTYPE html>', '<table>', '<custom-tag attr="1">', '</div>', '<![CDATA[\nx\n]]>'),
+      hostile: true,
+      weight: 1,
+    },
+    {
+      arbitrary: fc.tuple(fc.constantFrom(2, 2, 3, 1, 4), directiveName, hostileArgument, hostileAttributes).map(([colons, name, argument, attrs]) => directiveHeader(colons, name, argument, attrs)),
+      hostile: true,
+      weight: 1,
+    },
+    { arbitrary: fc.constantFrom(':::', '::', '::::', ':::panel', '::: panel', ':::panel info extra'), hostile: true, weight: 1 },
+  ])
+  return { fencedCode, leafBlock }
+}
+
+function blockMarkdown(hostile: boolean, { inlines, oneLine }: InlineMarkdown, { fencedCode, leafBlock }: LeafMarkdown): Arbitrary<string> {
+  const blockDepth = fc.createDepthIdentifier()
+  const { blocks } = fc.letrec<{ block: string; blocks: string }>((tie) => {
+    const bodyByModel = { block: fc.oneof(tie('blocks'), fc.constant('')), code: fencedCode, inline: fc.oneof(oneLine, fc.constant('')) }
+    const tableDirectives = Object.entries(blockDirectives).map(([name, directive]) => {
+      const argument =
+        blockArgument(name) === undefined
+          ? fc.constant('')
+          : fc.oneof({ arbitrary: fc.constantFrom(' DONE', ' TODO', ' custom', ' info', ' warning'), weight: 3 }, { arbitrary: bareToken.map((held) => ` ${held}`), weight: 1 })
+      const attrs = hostile ? fc.oneof({ arbitrary: tableAttributes(directive.attributes), weight: 4 }, { arbitrary: hostileAttributes, weight: 1 }) : tableAttributes(directive.attributes)
+      if (directive.contentModel === 'none') return fc.tuple(argument, attrs).map(([held, spelled]) => directiveHeader(2, name, held, spelled))
+      return fc
+        .tuple(argument, attrs, bodyByModel[directive.contentModel], hostile ? closerDrift : fc.constant(null))
+        .map(([held, spelled, body, closer]) => container((colons) => directiveHeader(colons, name, held, spelled), body, closer))
+    })
+    return {
+      block: choose(
+        hostile,
+        [
+          { arbitrary: fc.array(inlines, { maxLength: 3, minLength: 1 }).map((lines) => lines.join('\n')), weight: 10 },
+          { arbitrary: leafBlock, weight: 10 },
+          {
+            arbitrary: fc.tuple(tie('blocks'), fc.array(quotePrefix, { maxLength: 3, minLength: 1 })).map(([body, prefixes]) => prefixLines(body, '> ', (index) => prefixes[index % prefixes.length] ?? '')),
+            weight: 3,
+          },
+          {
+            arbitrary: fc
+              .tuple(listMarker, fc.array(fc.tuple(fc.option(listMarker, { freq: 4 }), fc.constantFrom(' ', ' ', ' ', '  ', '\t', '', '     '), tie('blocks'), indentDrift), { maxLength: 3, minLength: 1 }), separator)
+              .map(([listed, items, gap]) =>
+                items
+                  .map(([own, space, body, drift]) => {
+                    const marker = own ?? listed
+                    return prefixLines(body, `${marker}${space}`, () => ' '.repeat(Math.max(0, marker.length + space.length + drift)))
+                  })
+                  .join(gap === '\n\n' ? '\n\n' : '\n'),
+              ),
+            weight: 4,
+          },
+          { arbitrary: fc.oneof(...tableDirectives), weight: 3 },
+          {
+            arbitrary: fc
+              .tuple(directiveName, hostileArgument, hostileAttributes, tie('blocks'), fc.option(fc.integer({ max: 5, min: 3 }), { freq: 2 }), closerDrift)
+              .map(([name, argument, attrs, body, opener, closer]) => container((colons) => directiveHeader(opener ?? colons, name, argument, attrs), body, closer)),
+            hostile: true,
+            weight: 1,
+          },
+        ],
+        { depthIdentifier: blockDepth, maxDepth: 3 },
+      ),
+      blocks: fc
+        .array(fc.tuple(separator, tie('block')), { depthIdentifier: blockDepth, maxLength: 3, minLength: 1 })
+        .map((entries) => entries.map(([gap, block], index) => (index === 0 ? block : `${gap}${block}`)).join('')),
+    }
+  })
+  return blocks
+}
+
+const cleanMarkdown = markdownOf(false)
+const hostileMarkdown = markdownOf(true)
+
+const canonical = adfDocument
+  .map((document) => adfToMarkdown(document))
+  .filter((emitted): emitted is Extract<Result<string>, { ok: true }> => emitted.ok)
+  .map((emitted) => emitted.value)
+
+function edited(markdown: string, edits: readonly Edit[]): string {
+  let text = markdown
+  for (const [at, removed, inserted] of edits) {
+    const index = at % (text.length + 1)
+    text = `${text.slice(0, index)}${inserted}${text.slice(index + removed)}`
+  }
+  return text
+}
+
+const edit: Arbitrary<Edit> = fc.tuple(fc.nat(), fc.nat({ max: 3 }), fc.oneof(piece, fc.constant('')))
+
+const markdown = fc.oneof(
+  { arbitrary: cleanMarkdown, weight: 4 },
+  { arbitrary: hostileMarkdown, weight: 2 },
+  { arbitrary: canonical, weight: 2 },
+  { arbitrary: fc.tuple(fc.oneof(cleanMarkdown, canonical), fc.array(edit, { maxLength: 3, minLength: 1 })).map(([held, edits]) => edited(held, edits)), weight: 3 },
+  { arbitrary: fc.string({ maxLength: 40, unit: piece }), weight: 1 },
+)
+
+const document = fc
+  .tuple(markdown, fc.oneof({ arbitrary: fc.constant('\n'), weight: 8 }, { arbitrary: fc.constantFrom('\r\n', '\r'), weight: 1 }), fc.constantFrom('', '', '\n', '  \n'))
+  .map(([held, ending, trailing]) => `${held}${trailing}`.replaceAll('\n', ending))
+
+function holdsDirectiveShape(document: AdfDocument): boolean {
+  const pending = [...nodeContent(document)]
+  for (let node = pending.pop(); node !== undefined; node = pending.pop()) {
+    if (!commonMarkTypes.has(node.type) || nodeMarks(node).some((mark) => !markdownMarkTypes.has(mark.type))) return true
+    pending.push(...nodeContent(node))
+  }
+  return false
+}
+
+test('generated markdown refuses, or what it parses to refuses to emit, or its spelling reads back and spells itself', { timeout: propertyTimeout }, () => {
+  const parameters = propertyRuns(gateRuns)
+  let directiveShaped = 0
+  let fixpoints = 0
+  fc.assert(
+    fc.property(document, (input) => {
+      const parsed = markdownToAdf(input)
+      if (!parsed.ok) return
+      const emitted = adfToMarkdown(parsed.value)
+      if (!emitted.ok) return
+      fixpoints += 1
+      if (holdsDirectiveShape(parsed.value)) directiveShaped += 1
+      const read = markdownToAdf(emitted.value)
+      assert.ok(read.ok, read.ok ? '' : `${read.error.code}: ${read.error.message} — reading ${JSON.stringify(emitted.value)}`)
+      assert.deepEqual(toEditorNormal(read.value), toEditorNormal(parsed.value), `reading ${JSON.stringify(emitted.value)}`)
+      const respelled = adfToMarkdown(read.value)
+      assert.ok(respelled.ok, respelled.ok ? '' : `${respelled.error.code}: ${respelled.error.message} — spelling ${JSON.stringify(emitted.value)} again`)
+      assert.equal(respelled.value, emitted.value)
+    }),
+    parameters,
+  )
+  if (!parameters.gate) return
+  assert.ok(fixpoints >= fixpointFloor, `${fixpoints} of ${gateRuns} runs reached the fixpoint, under the floor of ${fixpointFloor}`)
+  assert.ok(directiveShaped >= directiveShapedFloor, `${directiveShaped} runs reaching the fixpoint held a node or mark outside CommonMark's own types, under the floor of ${directiveShapedFloor}`)
+})
+

src/markdown/block-directive-marks.ts

@@ -1,13 +1,13 @@
 import type { AdfMark } from '../adf/document.ts'
 import type { JsonValue } from '../json-value.ts'
-import { isAdfMark } from '../adf/document.ts'
+import { isAdfMark, nodeAttrs } from '../adf/document.ts'
 import { serializeCanonicalJson } from '../canonical-json.ts'
 
 export const marksAttribute = 'marks'
 
 export function markValues(marks: readonly AdfMark[]): JsonValue {
   return marks.map((mark) => {
-    const attrs = mark.attrs ?? {}
+    const attrs = nodeAttrs(mark)
     return Object.keys(attrs).length === 0 ? { type: mark.type } : { attrs, type: mark.type }
   })
 }

src/markdown/commonmark-grammar.ts

@@ -51,6 +51,7 @@ const htmlBlockConditions: HtmlBlockCondition[] = [
 ]
 const asciiPunctuation = /[!"#$%&'()*+,\-./:;<=>?@[\\\]^_`{|}~]/
 const atxHeadingOpener = /^(#{1,6})(?:[ \t]|$)/
+const blankLine = /^[ \t]*$/
 const codeFenceOpener = /^(`{3,}|~{3,})/
 const directiveClaim = /^:{2,}(?:[A-Za-z0-9]|[ \t]*$)/
 const pipeClaim = /^\|/
@@ -167,6 +168,10 @@ export function isAutolink(text: string): boolean {
   return autolink.test(text)
 }
 
+export function isBlankLine(line: string): boolean {
+  return blankLine.test(line)
+}
+
 export function isThematicBreak(line: string): boolean {
   return thematicBreak.test(line)
 }

src/markdown/directive-syntax.ts

@@ -56,6 +56,11 @@ export function attributeValue(text: string, kind: AttributeKind): AttributeRead
   return overNested(parsed) ? { refusal: 'nesting' } : { value: { kind, value: parsed } }
 }
 
+export function holdsInlineDirectiveOpener(text: string): boolean {
+  for (let index = text.indexOf(':'); index !== -1; index = text.indexOf(':', index + 1)) if (opensInlineDirective(text, index)) return true
+  return false
+}
+
 export function isBareToken(text: string): boolean {
   return bareToken.test(text)
 }

src/markdown/emit/adf-to-markdown.test.ts

@@ -6,6 +6,7 @@ import type { JsonValue } from '../../json-value.ts'
 import type { Result } from '../../result.ts'
 import { adfToMarkdown, markdownToAdf } from '../../index.ts'
 import { largestNesting } from '../../nesting.ts'
+import { toEditorNormal } from '../../adf/editor-normal.ts'
 
 function document(...content: AdfNode[]): AdfDocument {
   return { content, type: 'doc', version: 1 }
@@ -353,7 +354,9 @@ test('refuses marks and attributes nested deeper than the emitter carries', () =
   const roundTrips = (node: AdfNode): void => {
     const spelled = adfToMarkdown(document(node))
     assert.ok(spelled.ok, spelled.ok ? '' : spelled.error.message)
-    assert.deepEqual(markdownToAdf(spelled.value), { ok: true, value: document(node) })
+    const read = markdownToAdf(spelled.value)
+    assert.ok(read.ok, read.ok ? '' : read.error.message)
+    assert.deepEqual(toEditorNormal(read.value), document(node))
   }
 
   assert.equal(markdown(adfToMarkdown(document(paragraph({ marks: [{ attrs, type: 'em' }], text: 'x', type: 'text' })))), deeper('depth', 'em', largestNesting - 3))

src/markdown/emit/adf-to-markdown.ts

@@ -1,12 +1,12 @@
 import type { AdfDocument, AdfNode } from '../../adf/document.ts'
 import type { BlockDirective } from '../../adf/block-directives.ts'
-import { adfDocumentFault, carriesOnly } from '../../adf/document.ts'
+import { adfDocumentFault, carriesOnly, nodeAttrs, nodeContent, nodeMarks } from '../../adf/document.ts'
 import { blockDirective } from '../../adf/block-directives.ts'
 import { carriedBlock } from '../opaque-carry.ts'
 import { emitInlineLine } from './inline-line.ts'
 import { failure, faulted, success, type ConvertErrorPath, type Result } from '../../result.ts'
 import { fencedCodeBlock } from '../backtick-runs.ts'
-import { holdsNullCharacter, isThematicBreak, markerInterruptsParagraph } from '../commonmark-grammar.ts'
+import { holdsNullCharacter, isBlankLine, isThematicBreak, markerInterruptsParagraph } from '../commonmark-grammar.ts'
 import { languageSlot } from '../code-language.ts'
 import { largestNesting } from '../../nesting.ts'
 import { listBreakSpelling } from '../list-break.ts'
@@ -26,7 +26,7 @@ export function adfToMarkdown(document: AdfDocument): Result<string> {
   const fault = adfDocumentFault(document)
   if (fault !== undefined) return faulted(fault, [])
   if (document.version !== 1) return failure('unsupported-document-version', `no markdown spelling carries ADF version ${document.version}`, [])
-  const blocks = emitBlocks(document.content ?? [], 'document', [], 0)
+  const blocks = emitBlocks(nodeContent(document), 'document', [], 0)
   if (!blocks.ok) return blocks
   return success(blocks.value.text === '' ? '' : `${blocks.value.text}\n`)
 }
@@ -63,8 +63,8 @@ function separationBetween(previous: PlacedBlock, next: PlacedBlock, container:
 }
 
 function interruptsParagraph(node: AdfNode): boolean {
-  const items = node.content ?? []
-  const empty = (items[0]?.content ?? []).length === 0
+  const items = nodeContent(node)
+  const empty = items[0] === undefined || nodeContent(items[0]).length === 0
   if (node.type !== 'orderedList') return markerInterruptsParagraph(undefined, empty)
   return markerInterruptsParagraph(listStart(node, items.length) ?? 0, empty)
 }
@@ -110,7 +110,7 @@ function commonMarkText(text: string): EmittedBlock {
 
 function emitDirectiveBlock(node: AdfNode, directive: BlockDirective, path: ConvertErrorPath, depth: number): Result<EmittedBlock> {
   if (node.text !== undefined) return failure('unsupported-node-shape', `a ${node.type} carries no text: this one holds text`, path)
-  const content = node.content ?? []
+  const content = nodeContent(node)
   if (directive.contentModel === 'none' && content.length > 0) return failure('unsupported-node-shape', `a ${node.type} holds no content: this one holds some`, path)
   if (directive.contentModel === 'code') return emitCodeDirective(node, directive, path, depth)
   const header = spellDirectiveHeader(node, directive)
@@ -134,7 +134,7 @@ function emitInlineBody(content: readonly AdfNode[], path: ConvertErrorPath): Re
 
 function emitBlockquote(node: AdfNode, path: ConvertErrorPath, depth: number): Result<EmittedBlock> | undefined {
   if (!carriesOnly(node, [])) return undefined
-  const inner = emitBlocks(node.content ?? [], 'document', path, depth + 1)
+  const inner = emitBlocks(nodeContent(node), 'document', path, depth + 1)
   if (!inner.ok) return inner
   const text = inner.value.text
     .split('\n')
@@ -145,7 +145,7 @@ function emitBlockquote(node: AdfNode, path: ConvertErrorPath, depth: number): R
 
 function emitCodeBlock(node: AdfNode, path: ConvertErrorPath): Result<EmittedBlock> | undefined {
   if (!carriesOnly(node, ['language'])) return undefined
-  const slot = languageSlot(node.attrs?.['language'])
+  const slot = languageSlot(nodeAttrs(node)['language'])
   if (slot.kind === 'attribute') return undefined
   const text = codeBlockText(node, path)
   if (!text.ok) return text
@@ -153,7 +153,7 @@ function emitCodeBlock(node: AdfNode, path: ConvertErrorPath): Result<EmittedBlo
 }
 
 function emitCodeDirective(node: AdfNode, directive: BlockDirective, path: ConvertErrorPath, depth: number): Result<EmittedBlock> {
-  const slot = languageSlot(node.attrs?.['language'])
+  const slot = languageSlot(nodeAttrs(node)['language'])
   const header = spellDirectiveHeader(node, directive, slot.kind === 'attribute' ? [] : ['language'])
   if (header === undefined) return commonMarkLine(carriedBlock(node, path, depth))
   const text = codeBlockText(node, path)
@@ -164,15 +164,15 @@ function emitCodeDirective(node: AdfNode, directive: BlockDirective, path: Conve
 
 function codeBlockText(node: AdfNode, path: ConvertErrorPath): Result<string> {
   let text = ''
-  for (const [index, child] of (node.content ?? []).entries()) {
+  for (const [index, child] of nodeContent(node).entries()) {
     const childPath = [...path, 'content', index]
     if (
       child.type !== 'text' ||
       typeof child.text !== 'string' ||
       child.text === '' ||
-      (child.content ?? []).length > 0 ||
-      (child.marks ?? []).length > 0 ||
-      Object.keys(child.attrs ?? {}).length > 0
+      nodeContent(child).length > 0 ||
+      nodeMarks(child).length > 0 ||
+      Object.keys(nodeAttrs(child)).length > 0
     ) {
       return failure('unsupported-node-shape', `a codeBlock holds plain text nodes only: this ${child.type} node is not one`, childPath)
     }
@@ -185,10 +185,10 @@ function codeBlockText(node: AdfNode, path: ConvertErrorPath): Result<string> {
 
 function emitHeading(node: AdfNode, path: ConvertErrorPath): Result<EmittedBlock> | undefined {
   if (!carriesOnly(node, ['level'])) return undefined
-  const level = node.attrs?.['level']
+  const level = nodeAttrs(node)['level']
   if (typeof level !== 'number' || !Number.isInteger(level) || level < 1 || level > 6) return undefined
   const hashes = '#'.repeat(level)
-  const content = node.content ?? []
+  const content = nodeContent(node)
   if (content.length === 0) return success(commonMarkText(hashes))
   const line = emitInlineLine(content, 'heading', path)
   if (!line.ok) return line
@@ -198,7 +198,7 @@ function emitHeading(node: AdfNode, path: ConvertErrorPath): Result<EmittedBlock
 function emitList(node: AdfNode, path: ConvertErrorPath, depth: number): Result<EmittedBlock> | undefined {
   const ordered = node.type === 'orderedList'
   if (!carriesOnly(node, ordered ? ['order'] : [])) return undefined
-  const items = node.content ?? []
+  const items = nodeContent(node)
   const start = listStart(node, items.length)
   if (start === undefined || items.length === 0) return undefined
   if (items.some((item) => item.type !== 'listItem' || !carriesOnly(item, []))) return undefined
@@ -216,23 +216,25 @@ function emitList(node: AdfNode, path: ConvertErrorPath, depth: number): Result<
 
 function listStart(node: AdfNode, items: number): number | undefined {
   if (node.type !== 'orderedList') return 0
-  const start = node.attrs?.['order']
+  const start = nodeAttrs(node)['order']
   if (typeof start !== 'number' || !Number.isInteger(start) || start < 0 || start > largestListMarker) return undefined
   return start + items - 1 > largestListMarker ? undefined : start
 }
 
 function emitListItem(item: AdfNode, marker: string, path: ConvertErrorPath, depth: number): Result<EmittedBody> | undefined {
-  const inner = emitBlocks(item.content ?? [], 'list-item', path, depth + 1)
+  const inner = emitBlocks(nodeContent(item), 'list-item', path, depth + 1)
   if (!inner.ok) return inner
   if (inner.value.text === '') return success({ fenceColons: 0, text: marker.trimEnd() })
+  const body = inner.value.text.split('\n')
+  if (body.some((line) => line !== '' && isBlankLine(line))) return undefined
   const indent = ' '.repeat(marker.length)
-  const lines = inner.value.text.split('\n').map((line, index) => (index === 0 ? `${marker}${line}` : line === '' ? '' : `${indent}${line}`))
+  const lines = body.map((line, index) => (index === 0 ? `${marker}${line}` : line === '' ? '' : `${indent}${line}`))
   if (isThematicBreak(lines[0] ?? '')) return undefined
   return success({ fenceColons: inner.value.fenceColons, text: lines.join('\n') })
 }
 
 function emitParagraph(node: AdfNode, path: ConvertErrorPath): Result<EmittedBlock> | undefined {
-  const content = node.content ?? []
+  const content = nodeContent(node)
   if (content.length === 0 || !carriesOnly(node, [])) return undefined
   const line = emitInlineLine(content, 'paragraph', path)
   if (!line.ok) return line
@@ -240,6 +242,6 @@ function emitParagraph(node: AdfNode, path: ConvertErrorPath): Result<EmittedBlo
 }
 
 function emitRule(node: AdfNode): Result<EmittedBlock> | undefined {
-  if (!carriesOnly(node, []) || (node.content ?? []).length > 0) return undefined
+  if (!carriesOnly(node, []) || nodeContent(node).length > 0) return undefined
   return success(commonMarkText('---'))
 }

src/markdown/emit/block-directive-spelling.ts

@@ -3,6 +3,7 @@ import type { BlockDirective } from '../../adf/block-directives.ts'
 import { blockArgument } from '../block-directive-arguments.ts'
 import { isBareToken, spellAttributes, spellJsonAttribute, spellVocabulary } from '../directive-syntax.ts'
 import { markValues, marksAttribute } from '../block-directive-marks.ts'
+import { nodeAttrs, nodeMarks } from '../../adf/document.ts'
 import { vocabularyPairs } from '../../adf/attribute-vocabulary.ts'
 
 export function spellDirectiveHeader(node: AdfNode, directive: BlockDirective, spelledByBody: readonly string[] = []): string | undefined {
@@ -10,17 +11,17 @@ export function spellDirectiveHeader(node: AdfNode, directive: BlockDirective, s
   const argument = spellArgument(node, argumentAttribute)
   if (argument === undefined) return undefined
   const spelled = argumentAttribute === undefined ? spelledByBody : [argumentAttribute, ...spelledByBody]
-  const pairs = vocabularyPairs(node.attrs ?? {}, directive.attributes, spelled)
+  const pairs = vocabularyPairs(nodeAttrs(node), directive.attributes, spelled)
   if (pairs === undefined) return undefined
   const spelledPairs = spellVocabulary(pairs)
-  const marks = node.marks ?? []
+  const marks = nodeMarks(node)
   if (marks.length > 0) spelledPairs.push([marksAttribute, spellJsonAttribute(markValues(marks))])
   const attributes = spellAttributes(spelledPairs)
   return `${node.type}${argument}${attributes === '' ? '' : ` ${attributes}`}`
 }
 
 function spellArgument(node: AdfNode, argumentAttribute: string | undefined): string | undefined {
-  const value = argumentAttribute === undefined ? undefined : node.attrs?.[argumentAttribute]
+  const value = argumentAttribute === undefined ? undefined : nodeAttrs(node)[argumentAttribute]
   if (value === undefined) return ''
   if (typeof value !== 'string' || !isBareToken(value)) return undefined
   return ` ${value}`

src/markdown/emit/image.ts

@@ -1,5 +1,5 @@
 import type { AdfNode } from '../../adf/document.ts'
-import { carriesOnly } from '../../adf/document.ts'
+import { carriesOnly, nodeAttrs, nodeContent } from '../../adf/document.ts'
 import type { ConvertErrorPath } from '../../result.ts'
 import { serializeCanonicalJson } from '../../canonical-json.ts'
 import { tryImageLine } from './inline-line.ts'
@@ -14,11 +14,11 @@ export function tryImage(node: AdfNode, path: ConvertErrorPath): string | undefi
 }
 
 function imageShape(node: AdfNode): { alt: string | undefined; url: string } | undefined {
-  const content = node.content ?? []
+  const content = nodeContent(node)
   const media = content[0]
-  if (!carriesOnly(node, ['layout']) || serializeCanonicalJson(node.attrs ?? {}, 'compact') !== centeredMediaSingle) return undefined
-  if (media === undefined || content.length !== 1 || media.type !== 'media' || !carriesOnly(media, imageAttributes) || (media.content ?? []).length > 0) return undefined
-  const attrs = media.attrs ?? {}
+  if (!carriesOnly(node, ['layout']) || serializeCanonicalJson(nodeAttrs(node), 'compact') !== centeredMediaSingle) return undefined
+  if (media === undefined || content.length !== 1 || media.type !== 'media' || !carriesOnly(media, imageAttributes) || nodeContent(media).length > 0) return undefined
+  const attrs = nodeAttrs(media)
   const alt = attrs['alt']
   const url = attrs['url']
   if (attrs['type'] !== 'external' || typeof url !== 'string') return undefined

src/markdown/emit/inline-directive-spelling.ts

@@ -1,9 +1,10 @@
 import type { AdfNode } from '../../adf/document.ts'
 import type { InlineDirective } from '../../adf/inline-directives.ts'
+import { nodeAttrs } from '../../adf/document.ts'
 import { spellAttributes, spellVocabulary } from '../directive-syntax.ts'
 import { vocabularyPairs } from '../../adf/attribute-vocabulary.ts'
 
 export function spellInlineNodeAttributes(node: AdfNode, directive: InlineDirective): string | undefined {
-  const pairs = vocabularyPairs(node.attrs ?? {}, directive.attributes, directive.textAttribute === undefined ? [] : [directive.textAttribute])
+  const pairs = vocabularyPairs(nodeAttrs(node), directive.attributes, directive.textAttribute === undefined ? [] : [directive.textAttribute])
   return pairs === undefined ? undefined : spellAttributes(spellVocabulary(pairs))
 }

src/markdown/emit/inline-line.ts

@@ -1,17 +1,18 @@
 import type { AdfMark, AdfNode } from '../../adf/document.ts'
 import type { InlineDirective } from '../../adf/inline-directives.ts'
-import { assembleInlineLine, type InlineEscaping, type InlineSegment, type LineContainer, type NodeRange } from './line-escaping.ts'
+import { assembleInlineLine, isSyntax, type InlineEscaping, type InlineSegment, type LineContainer, type NodeRange } from './line-escaping.ts'
 import { carriedInline } from '../opaque-carry.ts'
 import { claimsLine, holdsNullCharacter, isAutolink } from '../commonmark-grammar.ts'
+import { escapeUnbalanced, spellDestination, spellLinkTarget } from '../link-syntax.ts'
 import { failure, faulted, success, type ConvertErrorPath, type Result } from '../../result.ts'
 import { holdsEntityReference } from '../entity-references.ts'
+import { holdsInlineDirectiveOpener, slotLineEndingFault, spellLeafDirective } from '../directive-syntax.ts'
 import { inlineDirective } from '../../adf/inline-directives.ts'
 import { largestNesting } from '../../nesting.ts'
 import { longestBacktickRun } from '../backtick-runs.ts'
 import { markSpelling, spellMarkAttributes } from '../mark-spellings.ts'
+import { nodeAttrs, nodeContent, nodeMarks } from '../../adf/document.ts'
 import { sameMark } from '../../adf/editor-normal.ts'
-import { slotLineEndingFault, spellLeafDirective } from '../directive-syntax.ts'
-import { spellDestination, spellTitle } from '../link-syntax.ts'
 import { spellInlineNodeAttributes } from './inline-directive-spelling.ts'
 import { spellTextDirective } from '../text-directive.ts'
 
@@ -40,7 +41,7 @@ export function emitInlineLine(nodes: readonly AdfNode[], container: LineContain
 export function tryPipeCell(nodes: readonly AdfNode[], path: ConvertErrorPath): string | undefined {
   const emitted = emitLine(nodes, 'table-cell', path)
   if (!emitted.ok) return undefined
-  if (emitted.value.segments.some((segment) => segment.escaping === 'none' && segment.text.includes('|'))) return undefined
+  if (emitted.value.segments.some((segment) => isSyntax(segment.escaping) && segment.text.includes('|'))) return undefined
   return emitted.value.line
 }
 
@@ -127,7 +128,7 @@ function syntax(text: string): InlineSegment {
 }
 
 function refuseContentAndText(node: AdfNode, path: ConvertErrorPath): Result<null> {
-  const holdsContent = (node.content ?? []).length > 0
+  const holdsContent = nodeContent(node).length > 0
   if (holdsContent || node.text !== undefined) {
     const held = holdsContent ? 'content' : 'text'
     return failure('unsupported-node-shape', `a ${node.type} node holds neither content nor text: this one holds ${held}`, path)
@@ -156,7 +157,7 @@ function inlineRuns(nodes: readonly AdfNode[], depth: number, firstIndex: number
   for (const [offset, node] of nodes.entries()) {
     const index = firstIndex + offset
     // spec/flavour.md, Marks.
-    const mark = carries(node, carried, index) ? undefined : (node.marks ?? [])[depth]
+    const mark = carries(node, carried, index) ? undefined : nodeMarks(node)[depth]
     if (mark === undefined) {
       runs.push({ index, kind: 'plain', node })
       continue
@@ -184,7 +185,7 @@ function emitLeaf(node: AdfNode, context: InlineContext, index: number): Result<
     if (!carried.ok) return carried
     return success({ segments: [syntax(carried.value)] })
   }
-  const types = (node.marks ?? []).map((mark) => mark.type)
+  const types = nodeMarks(node).map((mark) => mark.type)
   if (new Set(types).size !== types.length) return failure('unsupported-node-shape', `a ${node.type} node carries one mark type twice`, path)
   const directive = inlineDirective(node.type)
   if (directive === undefined) return emitText(node, context, index, path)
@@ -206,7 +207,7 @@ function emitInlineDirective(node: AdfNode, directive: InlineDirective, index: n
   if (!empty.ok) return empty
   const attributes = spellInlineNodeAttributes(node, directive)
   if (attributes === undefined) return success({ carry: { first: index, last: index } })
-  const slot = directive.textAttribute === undefined ? undefined : node.attrs?.[directive.textAttribute]
+  const slot = directive.textAttribute === undefined ? undefined : nodeAttrs(node)[directive.textAttribute]
   if (slot === undefined) return success({ segments: [syntax(spellLeafDirective(node.type, attributes))] })
   if (typeof slot !== 'string') return success({ carry: { first: index, last: index } })
   const spans = slotLineEndingFault(node.type, slot)
@@ -217,9 +218,9 @@ function emitInlineDirective(node: AdfNode, directive: InlineDirective, index: n
 }
 
 function emitText(node: AdfNode, context: InlineContext, index: number, path: ConvertErrorPath): Result<Emission> {
-  if (Object.keys(node.attrs ?? {}).length > 0) return success({ carry: { first: index, last: index } })
+  if (Object.keys(nodeAttrs(node)).length > 0) return success({ carry: { first: index, last: index } })
   if (typeof node.text !== 'string' || node.text === '') return failure('unsupported-node-shape', 'a text node holds text: this one has none', path)
-  if ((node.content ?? []).length > 0) return failure('unsupported-node-shape', 'a text node holds no content: this one holds some', path)
+  if (nodeContent(node).length > 0) return failure('unsupported-node-shape', 'a text node holds no content: this one holds some', path)
   if (/\r/.test(node.text)) return failure('unspellable-character', 'a text node holds a carriage return CommonMark rewrites', path)
   if (holdsNullCharacter(node.text)) return failure('unspellable-character', 'a text node holds a null character CommonMark replaces', path)
   const escaping: InlineEscaping = context.bracketed ? 'bracketed' : 'backslash'
@@ -260,9 +261,9 @@ function emitEmphasis(nodes: readonly AdfNode[], spelling: string, depth: number
 function emitCodeSpan(nodes: readonly AdfNode[], depth: number, range: NodeRange, path: ConvertErrorPath): Result<Emission> {
   let text = ''
   for (const node of nodes) {
-    if (node.type !== 'text' || (node.marks ?? []).length !== depth + 1) return success({ carry: range })
+    if (node.type !== 'text' || nodeMarks(node).length !== depth + 1) return success({ carry: range })
     if (typeof node.text !== 'string' || node.text === '') return failure('unsupported-node-shape', 'a text node holds text: this one has none', path)
-    if ((node.content ?? []).length > 0) return failure('unsupported-node-shape', 'a text node holds no content: this one holds some', path)
+    if (nodeContent(node).length > 0) return failure('unsupported-node-shape', 'a text node holds no content: this one holds some', path)
     text += node.text
   }
   if (/[\n\r]/.test(text)) return success({ carry: range })
@@ -278,19 +279,19 @@ function needsPadding(text: string): boolean {
 }
 
 function emitLink(nodes: readonly AdfNode[], mark: AdfMark, depth: number, range: NodeRange, context: InlineContext, path: ConvertErrorPath): Result<Emission> {
-  const href = mark.attrs?.['href']
-  const title = mark.attrs?.['title']
+  const href = nodeAttrs(mark)['href']
+  const title = nodeAttrs(mark)['title']
   if (typeof href !== 'string') return success({ carry: range })
   const node = nodes[0]
-  const bare = nodes.length === 1 && node !== undefined && node.type === 'text' && node.text === href && (node.marks ?? []).length === depth + 1
-  if (bare && title === undefined && isAutolink(href) && !holdsEntityReference(href)) return success({ segments: [syntax(`<${href}>`)] })
-  const destination = spellDestination(href, path)
-  if (!destination.ok) return destination
-  const spelledTitle = typeof title === 'string' ? spellTitle(title, path) : success('')
-  if (!spelledTitle.ok) return spelledTitle
+  const bare = nodes.length === 1 && node !== undefined && node.type === 'text' && node.text === href && nodeMarks(node).length === depth + 1
+  const autolinkHolds = !context.bracketed || (!href.includes('`') && !holdsInlineDirectiveOpener(href) && escapeUnbalanced(href, '[', ']') === href)
+  if (bare && autolinkHolds && title === undefined && isAutolink(href) && !holdsEntityReference(href)) return success({ segments: [syntax(`<${href}>`)] })
+  const target = spellLinkTarget(href, typeof title === 'string' ? title : undefined, path)
+  if (!target.ok) return target
   const inner = emitRun(nodes, depth + 1, range.first, { ...context, bracketed: true })
   if (!inner.ok) return inner
   if (inner.value.carry !== undefined) return inner
-  return success({ segments: [syntax('['), ...inner.value.segments, syntax(`](${destination.value}${spelledTitle.value})`)] })
+  const spelledTarget: InlineSegment = context.bracketed ? { escaping: 'bracketed-link-target', text: escapeUnbalanced(target.value, '[', ']') } : syntax(target.value)
+  return success({ segments: [{ escaping: 'none', nodes: range, text: '[' }, ...inner.value.segments, syntax(']('), spelledTarget, syntax(')')] })
 }
 

src/markdown/emit/line-escaping.ts

@@ -3,17 +3,19 @@ import { delimiterFlags, isWordCharacter, matchEmphasis, runLength } from '../em
 import { backslashEscape, escapesLineClaim, inlineHtmlConstruct, opensBracketedAutolink, opensEmailAutolink, type LinePosition } from '../commonmark-grammar.ts'
 import { isBareDelimiterRow } from '../pipe-table-syntax.ts'
 import { opensInlineDirective } from '../directive-syntax.ts'
+import { opensLinkDefinition } from '../link-reference-definitions.ts'
 import { readEntityReference } from '../entity-references.ts'
 
 export type EmphasisRole = 'close' | 'open'
 
-export type InlineEscaping = 'backslash' | 'bracketed' | 'none'
+export type InlineEscaping = 'backslash' | 'bracketed' | 'bracketed-link-target' | 'none'
 
 export type NodeRange = { first: number; last: number }
 
 export type InlineSegment =
   | { emphasis: EmphasisRole; escaping: 'none'; nodes: NodeRange; text: string }
-  | { emphasis?: undefined; escaping: InlineEscaping; text: string }
+  | { emphasis?: undefined; escaping: 'none'; nodes: NodeRange; text: string }
+  | { emphasis?: undefined; escaping: InlineEscaping; nodes?: undefined; text: string }
 
 export type AssembledLine = { line: string; unspellableRun: NodeRange | undefined }
 
@@ -27,8 +29,7 @@ type EmittedRun = { canClose: boolean; canOpen: boolean; character: string; deli
 
 const delimiters = ['*', '_', '`', '~']
 
-// The `:` keeps a `[label]: url` line escaped: unescaped, the parser swallows it as a link reference definition.
-const followsLinkText = /[([:]/
+const followsLinkText = /[([]/
 
 export function assembleInlineLine(segments: readonly InlineSegment[], container: LineContainer): AssembledLine {
   return escape(resolveEmphasis(segments), container)
@@ -67,9 +68,24 @@ function escape(segments: readonly InlineSegment[], container: LineContainer): A
   const scan = segments.map((segment) => segment.text).join('')
   const escapings: InlineEscaping[] = []
   for (const segment of segments) for (let index = 0; index < segment.text.length; index += 1) escapings.push(segment.escaping)
-  const escaped = new Set<number>()
+  const escaped = escapedIndexes(scan, escapings, container)
   const placements: number[] = []
   let output = ''
+  for (let index = 0; index < scan.length; index += 1) {
+    if (escaped.has(index)) output += '\\'
+    placements.push(output.length)
+    output += scan.charAt(index)
+  }
+  if (container === 'paragraph' && opensLinkDefinition(output)) {
+    const opener = segments[0]?.nodes
+    if (opener !== undefined) return { line: output, unspellableRun: opener }
+    return { line: `\\${output}`, unspellableRun: unspellableRun(segments, output, placements) }
+  }
+  return { line: output, unspellableRun: unspellableRun(segments, output, placements) }
+}
+
+function escapedIndexes(scan: string, escapings: readonly InlineEscaping[], container: LineContainer): Set<number> {
+  const escaped = new Set<number>()
   const linkClose = lastLinkClose(scan, escapings)
   let line = scanLine(scan, 0)
   for (let index = 0; index < scan.length; index += 1) {
@@ -77,18 +93,44 @@ function escape(segments: readonly InlineSegment[], container: LineContainer): A
     const escaping = escapings[index]
     const escapable = escaping === 'backslash' || escaping === 'bracketed'
     if (
-      escapable &&
-      (claimsLineStart(line, index, container) ||
-        mergesWithSyntax(scan, escapings, index) ||
-        opensConstruct(scan, linkClose, index, escaping === 'bracketed', container, escaped))
+      (escapable &&
+        (claimsLineStart(line, index, container) ||
+          mergesWithSyntax(scan, escapings, index) ||
+          opensConstruct(scan, linkClose, index, escaping === 'bracketed', container, escaped))) ||
+      (escaping === 'bracketed-link-target' &&
+        ((scan.charAt(index) === '`' && opensCodeSpan(scan, index, escaped)) || (scan.charAt(index) === ':' && opensInlineDirective(scan, index))))
     ) {
-      output += '\\'
       escaped.add(index)
     }
-    placements.push(output.length)
-    output += scan.charAt(index)
   }
-  return { line: output, unspellableRun: unspellableRun(segments, output, placements) }
+  escapeClosedRuns(scan, escapings, escaped)
+  return escaped
+}
+
+// CommonMark reads no escape inside a code span, so a backtick string an escape forms or splits off still closes one an earlier bare run opens.
+function escapeClosedRuns(scan: string, escapings: readonly InlineEscaping[], escaped: Set<number>): void {
+  const formed = new Set<number>()
+  let end = scan.length - 1
+  while (end >= 0) {
+    if (scan.charAt(end) !== '`') {
+      end -= 1
+      continue
+    }
+    let start = end
+    while (scan.charAt(start - 1) === '`') start -= 1
+    let segmentEnd = end
+    for (let index = end; index > start; index -= 1) {
+      if (!escaped.has(index)) continue
+      formed.add(segmentEnd - index + 1)
+      segmentEnd = index - 1
+    }
+    if (segmentEnd !== end || escaped.has(start)) formed.add(segmentEnd - start + 1)
+    else if (escapings[start] !== 'none' && formed.has(end - start + 1)) {
+      for (let index = start; index <= end; index += 1) escaped.add(index)
+      formed.add(1)
+    }
+    end = start - 1
+  }
 }
 
 function unspellableRun(segments: readonly InlineSegment[], output: string, placements: readonly number[]): NodeRange | undefined {
@@ -181,8 +223,8 @@ function touchesSyntax(scan: string, escapings: readonly (InlineEscaping | undef
   return scan.charAt(cursor) === character && isSyntax(escapings[cursor])
 }
 
-function isSyntax(escaping: InlineEscaping | undefined): boolean {
-  return escaping === 'none'
+export function isSyntax(escaping: InlineEscaping | undefined): boolean {
+  return escaping === 'none' || escaping === 'bracketed-link-target'
 }
 
 function opensConstruct(
@@ -245,6 +287,8 @@ function lastLinkClose(scan: string, escapings: readonly (InlineEscaping | undef
 }
 
 function opensCodeSpan(scan: string, index: number, escaped: ReadonlySet<number>): boolean {
+  // A run escapes whole: a rest left bare would be a raw run of another length for a closer.
+  if (scan.charAt(index - 1) === '`' && escaped.has(index - 1)) return true
   if (!startsRun(scan, index, escaped)) return false
   const opener = backtickRun(scan, index)
   return closingBacktickRun(scan, index + opener, opener) !== undefined

src/markdown/emit/pipe-table.ts

@@ -1,5 +1,5 @@
 import type { AdfNode } from '../../adf/document.ts'
-import { carriesOnly } from '../../adf/document.ts'
+import { carriesOnly, nodeContent } from '../../adf/document.ts'
 import { spellPipeDelimiter, spellPipeRow } from '../pipe-table-syntax.ts'
 import { tryPipeCell } from './inline-line.ts'
 import type { ConvertErrorPath } from '../../result.ts'
@@ -11,7 +11,7 @@ export function tryPipeTable(node: AdfNode, path: ConvertErrorPath): string | un
   for (const [rowIndex, row] of rows.entries()) {
     const cells: string[] = []
     for (const [cellIndex, paragraph] of row.entries()) {
-      const content = paragraph.content ?? []
+      const content = nodeContent(paragraph)
       const line = content.length === 0 ? '' : tryPipeCell(content, [...path, 'content', rowIndex, 'content', cellIndex, 'content', 0])
       if (line === undefined) return undefined
       cells.push(line)
@@ -23,12 +23,12 @@ export function tryPipeTable(node: AdfNode, path: ConvertErrorPath): string | un
 }
 
 function pipeRows(node: AdfNode): AdfNode[][] | undefined {
-  const rows = node.content ?? []
-  const columns = (rows[0]?.content ?? []).length
+  const rows = nodeContent(node)
+  const columns = rows[0] === undefined ? 0 : nodeContent(rows[0]).length
   if (!carriesOnly(node, []) || columns === 0) return undefined
   const grid: AdfNode[][] = []
   for (const [index, row] of rows.entries()) {
-    const cells = row.content ?? []
+    const cells = nodeContent(row)
     if (row.type !== 'tableRow' || !carriesOnly(row, []) || cells.length !== columns) return undefined
     const wanted = index === 0 ? 'tableHeader' : 'tableCell'
     const paragraphs: AdfNode[] = []
@@ -43,7 +43,7 @@ function pipeRows(node: AdfNode): AdfNode[][] | undefined {
 }
 
 function plainParagraph(cell: AdfNode): AdfNode | undefined {
-  const content = cell.content ?? []
+  const content = nodeContent(cell)
   const paragraph = content[0]
   if (paragraph === undefined || content.length !== 1 || paragraph.type !== 'paragraph' || !carriesOnly(paragraph, [])) return undefined
   return paragraph

src/markdown/link-reference-definitions.ts

@@ -1,10 +1,14 @@
-import type { LinkDefinition, LinkPart } from '../link-syntax.ts'
-import { normalizeLabel, readDestination, readLabel, readTitle, skipLinkWhitespace } from '../link-syntax.ts'
+import type { LinkDefinition, LinkPart } from './link-syntax.ts'
+import { normalizeLabel, readDestination, readLabel, readTitle, skipLinkWhitespace } from './link-syntax.ts'
 
 type ReadDefinition = { definition: LinkDefinition; label: string; length: number }
 
 const restOfLine = /^[ \t]*(?:\n|$)/
 
+export function opensLinkDefinition(text: string): boolean {
+  return readDefinition(text) !== undefined
+}
+
 export function readLinkDefinitions(definitions: Map<string, LinkDefinition>, text: string): string {
   let rest = text
   let read = readDefinition(rest)

src/markdown/link-syntax.ts

@@ -103,27 +103,35 @@ export function spellDestination(href: string, path: ConvertErrorPath): Result<s
     return success(`<${href}>`)
   }
   if (href.startsWith('<')) return failure('unspellable-link', 'a bare link destination cannot begin with an angle bracket', path)
-  return success(escapeUnbalanced(href))
+  return success(escapeUnbalanced(href, '(', ')'))
 }
 
-export function spellTitle(title: string, path: ConvertErrorPath): Result<string> {
+export function spellLinkTarget(href: string, title: string | undefined, path: ConvertErrorPath): Result<string> {
+  const destination = spellDestination(href, path)
+  if (!destination.ok || title === undefined) return destination
+  const spelledTitle = spellTitle(title, path)
+  if (!spelledTitle.ok) return spelledTitle
+  return success(`${destination.value === '' ? '<>' : destination.value}${spelledTitle.value}`)
+}
+
+export function escapeUnbalanced(spelling: string, opener: string, closer: string): string {
+  const open: number[] = []
+  const unbalanced = new Set<number>()
+  for (let index = 0; index < spelling.length; index += backslashEscape(spelling, index) === undefined ? 1 : 2) {
+    const character = spelling.charAt(index)
+    if (character === opener) open.push(index)
+    if (character === closer && open.pop() === undefined) unbalanced.add(index)
+  }
+  for (const index of open) unbalanced.add(index)
+  let spelled = ''
+  for (let index = 0; index < spelling.length; index += 1) spelled += (unbalanced.has(index) ? '\\' : '') + spelling.charAt(index)
+  return spelled
+}
+
+function spellTitle(title: string, path: ConvertErrorPath): Result<string> {
   if (/[\n\r\\]/.test(title)) {
     return failure('unspellable-link', 'no canonical escape spells a backslash or newline in a link title', path)
   }
   if (holdsEntityReference(title)) return failure('unspellable-link', 'a link title holds an entity reference that decodes on the way back', path)
   return success(` "${title.replaceAll('"', '\\"')}"`)
 }
-
-function escapeUnbalanced(href: string): string {
-  const open: number[] = []
-  const unbalanced = new Set<number>()
-  for (let index = 0; index < href.length; index += 1) {
-    const character = href.charAt(index)
-    if (character === '(') open.push(index)
-    if (character === ')' && open.pop() === undefined) unbalanced.add(index)
-  }
-  for (const index of open) unbalanced.add(index)
-  let spelled = ''
-  for (let index = 0; index < href.length; index += 1) spelled += (unbalanced.has(index) ? '\\' : '') + href.charAt(index)
-  return spelled
-}

src/markdown/mark-spellings.ts

@@ -2,6 +2,7 @@ import type { AdfMark } from '../adf/document.ts'
 import type { AttributeVocabulary } from '../adf/attribute-vocabulary.ts'
 import type { MarkType } from '../adf/mark-attributes.ts'
 import { isMarkType, markAttributes } from '../adf/mark-attributes.ts'
+import { nodeAttrs } from '../adf/document.ts'
 import { spellAttributes, spellVocabulary } from './directive-syntax.ts'
 import { vocabularyPairs } from '../adf/attribute-vocabulary.ts'
 
@@ -30,6 +31,6 @@ export function markSpelling(type: string): MarkSpelling | undefined {
 }
 
 export function spellMarkAttributes(mark: AdfMark, vocabulary: AttributeVocabulary): string | undefined {
-  const pairs = vocabularyPairs(mark.attrs ?? {}, vocabulary, [])
+  const pairs = vocabularyPairs(nodeAttrs(mark), vocabulary, [])
   return pairs === undefined ? undefined : spellAttributes(spellVocabulary(pairs))
 }

src/markdown/parse/blocks.ts

@@ -7,6 +7,7 @@ import {
   claimsPipeLine,
   closingCodeFence,
   decodeTextEscapes,
+  isBlankLine,
   isThematicBreak,
   listMarker,
   markerInterruptsParagraph,
@@ -17,7 +18,7 @@ import {
 } from '../commonmark-grammar.ts'
 import { directiveLineEscape, malformedDirective, readDirectiveLine } from '../directive-syntax.ts'
 import { barePipeCells, isDelimiterRow, isPipeAlignment, isPipeDelimiter, malformedPipeTable, pipeCells } from '../pipe-table-syntax.ts'
-import { readLinkDefinitions } from './link-reference-definitions.ts'
+import { readLinkDefinitions } from '../link-reference-definitions.ts'
 
 export type Block = { position: SourcePosition } & (
   | { argument: string | undefined; attributes: DirectiveAttributes; blocks: Block[] | undefined; kind: 'directive'; name: string }
@@ -61,7 +62,6 @@ type Line = { column: number; text: string }
 
 type Walk = ParsedBlocks & { leaf: OpenLeaf | undefined; position: SourcePosition; stack: OpenContainer[] }
 
-const blankLine = /^[ \t]*$/
 const indentedCodeColumns = 4
 const largestOpenerIndentation = 3
 const leafColons = 2
@@ -117,7 +117,7 @@ function continuesContainer(walk: Walk, container: OpenContainer, line: Line): L
   // A directive container has no continuation marker: only its own fence closes it.
   if (container.kind === 'directive') return line
   // A list item begins with at most one blank line: an empty one gives the second up.
-  if (blankLine.test(line.text)) {
+  if (isBlankLine(line.text)) {
     return container.blocks.length === 0 && walk.leaf === undefined ? undefined : { column: line.column, text: '' }
   }
   return leadingColumns(line) < container.indentation ? undefined : removeColumns(line, container.indentation)
@@ -155,7 +155,7 @@ function itemStart(line: Line, opener: Line, paragraphOpen: boolean, enclosing:
   const marker = listMarker(opener.text)
   if (marker === undefined) return undefined
   const after: Line = { column: opener.column + marker.width, text: opener.text.slice(marker.width) }
-  const blank = blankLine.test(after.text)
+  const blank = isBlankLine(after.text)
   if (paragraphOpen && !markerInterruptsParagraph(marker.start, blank)) return undefined
   const spaces = leadingColumns(after)
   const padding = blank || spaces > indentedCodeColumns ? 1 : spaces
@@ -268,7 +268,7 @@ function pushFault(walk: Walk, fault: ConvertFault): void {
 
 // A claimed line ends the lazy continuation CommonMark would fold it into (spec/flavour.md).
 function continuesLazily(walk: Walk, line: Line): boolean {
-  if (walk.leaf?.kind !== 'paragraph' || blankLine.test(line.text)) return false
+  if (walk.leaf?.kind !== 'paragraph' || isBlankLine(line.text)) return false
   if (leadingColumns(line) >= indentedCodeColumns) return true
   const opener = removeColumns(line, largestOpenerIndentation).text
   if (claimsDirectiveLine(opener) || claimsPipeLine(opener) || isThematicBreak(opener)) return false
@@ -283,7 +283,7 @@ function readBlockLine(walk: Walk, line: Line): void {
     return
   }
   if (leaf?.kind === 'html') {
-    if (leaf.closer === undefined ? blankLine.test(line.text) : leaf.closer.test(line.text)) closeLeaf(walk)
+    if (leaf.closer === undefined ? isBlankLine(line.text) : leaf.closer.test(line.text)) closeLeaf(walk)
     return
   }
   if (leaf?.kind === 'pipe-table') {
@@ -298,7 +298,7 @@ function readBlockLine(walk: Walk, line: Line): void {
     if (readIndentedCodeLine(leaf, line)) return
     closeLeaf(walk)
   }
-  if (blankLine.test(line.text)) {
+  if (isBlankLine(line.text)) {
     closeLeaf(walk)
     return
   }
@@ -310,7 +310,7 @@ function readBlockLine(walk: Walk, line: Line): void {
 }
 
 function readIndentedCodeLine(leaf: Extract<OpenLeaf, { kind: 'indented-code' }>, line: Line): boolean {
-  if (blankLine.test(line.text)) {
+  if (isBlankLine(line.text)) {
     leaf.held.push(removeColumns(line, indentedCodeColumns).text)
     return true
   }

src/markdown/parse/directive-nodes.ts

@@ -3,7 +3,7 @@ import type { BlockDirective } from '../../adf/block-directives.ts'
 import type { ConvertFault } from '../../result.ts'
 import type { DirectiveAttributes, DirectiveValue } from '../directive-syntax.ts'
 import type { Elsewhere } from './directive-attributes.ts'
-import { attributeNestingMessage } from '../../adf/document.ts'
+import { attributeNestingMessage, nodeMarks } from '../../adf/document.ts'
 import { attributeValue, directiveLineEscape, inlineDirectiveEscape, spellAttributeValue, unknownDirectiveFault } from '../directive-syntax.ts'
 import { blockArgument } from '../block-directive-arguments.ts'
 import { blockDirective } from '../../adf/block-directives.ts'
@@ -89,7 +89,7 @@ function blockSpellingFault(name: string): ConvertFault | undefined {
 function slotText(content: readonly AdfNode[]): string | undefined {
   if (content.length === 0) return ''
   const only = content.length === 1 ? content[0] : undefined
-  if (only?.type !== 'text' || (only.marks ?? []).length > 0 || typeof only.text !== 'string') return undefined
+  if (only?.type !== 'text' || nodeMarks(only).length > 0 || typeof only.text !== 'string') return undefined
   return only.text
 }
 

src/markdown/parse/inline-content.ts

@@ -8,6 +8,7 @@ import { delimiterFlags, matchEmphasis, runLength } from '../emphasis-matching.t
 import { failure, faulted, success, type ConvertErrorPath, type Result } from '../../result.ts'
 import { inlineDirective } from '../../adf/inline-directives.ts'
 import { mergeAdjacentText } from '../../adf/editor-normal.ts'
+import { nodeAttrs, nodeMarks } from '../../adf/document.ts'
 import { normalizeLabel, readInlineTarget, readLabel } from '../link-syntax.ts'
 import { readCarriedInline } from '../opaque-carry.ts'
 import { readDirectiveMark } from './directive-marks.ts'
@@ -337,7 +338,7 @@ function imageAlt(inner: readonly Piece[], path: ConvertErrorPath): Result<strin
 function altText(node: AdfNode): string {
   if (node.type === 'hardBreak') return ' '
   const slot = inlineDirective(node.type)?.textAttribute
-  const spelled = slot === undefined ? undefined : node.attrs?.[slot]
+  const spelled = slot === undefined ? undefined : nodeAttrs(node)[slot]
   return typeof spelled === 'string' ? spelled : (node.text ?? '')
 }
 
@@ -409,7 +410,7 @@ function markType(character: string, used: number): string {
 // A node cannot carry one mark type twice (AGENTS.md §14).
 function applyMark(nodes: readonly AdfNode[], mark: AdfMark): AdfNode[] {
   return nodes.map((node) => {
-    const marks = node.marks ?? []
+    const marks = nodeMarks(node)
     return marks.some((carried) => carried.type === mark.type) ? node : { ...node, marks: [mark, ...marks] }
   })
 }

src/markdown/parse/markdown-to-adf.ts

@@ -9,6 +9,7 @@ import { failure, faulted, positioned, success, type ConvertErrorPath, type Pars
 import { languageSlot } from '../code-language.ts'
 import { largestNesting } from '../../nesting.ts'
 import { listBreakName, listBreakSpelling } from '../list-break.ts'
+import { nodeAttrs } from '../../adf/document.ts'
 import { parseBlocks } from './blocks.ts'
 import { parseInlineContent } from './inline-content.ts'
 import { readBlockDirectiveNode } from './directive-nodes.ts'
@@ -106,7 +107,7 @@ function directiveBody(read: BlockDirectiveNode, blocks: Block[] | undefined, de
 function codeDirectiveNode(node: AdfNode, blocks: readonly Block[], path: ConvertErrorPath): Result<AdfNode> {
   const only = blocks.length === 1 ? blocks[0] : undefined
   if (only?.kind !== 'code') return failure('unsupported-node-shape', `${node.type} takes one code block as its body: this body is not one`, path)
-  const attribute = node.attrs?.['language']
+  const attribute = nodeAttrs(node)['language']
   const fromFence = only.language !== ''
   const slot = languageSlot(fromFence ? only.language : attribute)
   if ((slot.kind === 'fence') !== fromFence || (fromFence && attribute !== undefined)) {

src/property-harness.ts

@@ -0,0 +1,171 @@
+import fc from 'fast-check'
+import assert from 'node:assert/strict'
+import { env } from 'node:process'
+
+import type { AdfAttributes, AdfDocument, AdfMark, AdfNode } from './adf/document.ts'
+import type { Arbitrary } from 'fast-check'
+import type { AttributeKind, AttributeVocabulary } from './adf/attribute-vocabulary.ts'
+import type { JsonValue } from './json-value.ts'
+import { blockArgument } from './markdown/block-directive-arguments.ts'
+import { blockDirectives } from './adf/block-directives.ts'
+import { inlineDirectives } from './adf/inline-directives.ts'
+import { markAttributes } from './adf/mark-attributes.ts'
+import { toEditorNormal } from './adf/editor-normal.ts'
+
+type Positions = { block: AdfNode; inline: AdfNode }
+
+const deepRunsVariable = 'PROPERTY_RUNS'
+const gateSeed = 20260914
+// Bun's test runner stops a test after five seconds unless the test sets its own timeout.
+export const propertyTimeout = 600000
+
+const depthIdentifier = fc.createDepthIdentifier()
+const emptyCell: AdfNode = { content: [{ type: 'paragraph' }], type: 'tableCell' }
+const flatCommonMarkShapeWeight = 4
+export const markdownPieces = fc.constantFrom(...'aZ09 \t\n!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~é\xa0🎉', ':a[', ':a{', 'ab:', 'http://')
+const nestingCommonMarkShapeWeight = 21
+const spelledTypes = new Set(['text', ...Object.keys(blockDirectives), ...Object.keys(inlineDirectives), ...Object.keys(markAttributes)])
+
+export function textOf(minLength: number): Arbitrary<string> {
+  return fc.oneof(
+    { arbitrary: fc.string({ maxLength: 12, minLength, unit: markdownPieces }), weight: 4 },
+    { arbitrary: fc.string({ maxLength: 6, minLength, unit: 'grapheme' }), weight: 1 },
+  )
+}
+
+const text = textOf(1)
+const unknownType = fc.oneof(fc.stringMatching(/^[a-z][A-Za-z0-9]{0,7}$/), text).filter((type) => !spelledTypes.has(type))
+const numberValue = fc.oneof({ arbitrary: fc.integer({ max: 10, min: -1 }), weight: 3 }, { arbitrary: fc.double({ noDefaultInfinity: true, noNaN: true }), weight: 1 })
+
+// V8's JSON.parse returns a wrong key after parsing a key holding an escaped backslash (https://issues.chromium.org/issues/521080746); Bun is unaffected.
+const keyPiece = fc
+  .oneof({ arbitrary: markdownPieces, weight: 4 }, { arbitrary: fc.string({ maxLength: 1, minLength: 1, unit: 'grapheme' }), weight: 1 })
+  .filter((piece) => !/[\\"\x00-\x1f]/.test(piece))
+export const jsonKey = fc.string({ maxLength: 8, unit: keyPiece })
+
+export const { jsonValue } = fc.letrec<{ jsonValue: JsonValue }>((tie) => ({
+  jsonValue: fc.oneof(
+    { depthSize: 'small', maxDepth: 2 },
+    fc.oneof(fc.constant(null), fc.boolean(), numberValue, textOf(0)),
+    fc.array(tie('jsonValue'), { maxLength: 3 }),
+    fc.dictionary(jsonKey, tie('jsonValue'), { maxKeys: 3, noNullPrototype: true }),
+  ),
+}))
+
+const valueByKind: Readonly<Record<AttributeKind, Arbitrary<JsonValue>>> = {
+  boolean: fc.boolean(),
+  json: jsonValue,
+  number: numberValue,
+  string: textOf(0),
+}
+
+export function attributes(vocabulary: AttributeVocabulary): Arbitrary<AdfAttributes> {
+  const model = Object.fromEntries(
+    Object.entries(vocabulary).map(([key, kind]) => [key, fc.oneof({ arbitrary: fc.constant(undefined), weight: 2 }, { arbitrary: valueByKind[kind], weight: 1 })]),
+  )
+  return fc.record(model).map(heldAttributes)
+}
+
+function heldAttributes(held: Readonly<Record<string, JsonValue | undefined>>): AdfAttributes {
+  const attrs: AdfAttributes = {}
+  for (const [key, value] of Object.entries(held)) if (value !== undefined) attrs[key] = value
+  return attrs
+}
+
+function pipeTable({ body, header }: { body: AdfNode[][]; header: AdfNode[] }): AdfNode {
+  const rows = [header, ...body.map((cells) => header.map((_, index) => cells[index] ?? emptyCell))]
+  return { content: rows.map((content): AdfNode => ({ content, type: 'tableRow' })), type: 'table' }
+}
+
+const mark: Arbitrary<AdfMark> = fc.oneof(
+  { arbitrary: fc.oneof(...Object.entries(markAttributes).map(([type, vocabulary]) => attributes(vocabulary).map((attrs) => ({ attrs, type })))), weight: 9 },
+  { arbitrary: fc.record({ attrs: fc.dictionary(jsonKey, jsonValue, { maxKeys: 2, noNullPrototype: true }), type: unknownType }), weight: 1 },
+)
+const marks = fc.uniqueArray(mark, { maxLength: 3, selector: (held) => held.type })
+
+const textNode = fc.record({ marks, text }).map((held): AdfNode => ({ ...held, type: 'text' }))
+
+const backtickRunNode = fc
+  .record({ marks: fc.oneof(fc.constant<AdfMark[]>([]), fc.constant<AdfMark[]>([{ type: 'code' }]), marks), text: fc.string({ maxLength: 6, minLength: 1, unit: fc.constantFrom('`', '``', ' ', 'a') }) })
+  .map((held): AdfNode => ({ ...held, type: 'text' }))
+
+const autolinkTextNode = fc
+  .record({ href: fc.tuple(fc.constantFrom('ab:', 'http://'), textOf(0)).map(([scheme, rest]) => `${scheme}${rest}`), marks })
+  .map(({ href, marks: held }): AdfNode => ({ marks: [...held.filter((outer) => outer.type !== 'link'), { attrs: { href }, type: 'link' }], text: href, type: 'text' }))
+
+const inlineNodes = Object.entries(inlineDirectives).map(([type, directive]) =>
+  fc.record({ attrs: attributes(directive.attributes), marks }).map((held): AdfNode => ({ ...held, type })),
+)
+
+function weighted(arbitraries: readonly Arbitrary<AdfNode>[], weight: number): { arbitrary: Arbitrary<AdfNode>; weight: number }[] {
+  return arbitraries.map((arbitrary) => ({ arbitrary, weight }))
+}
+
+const positions = fc.letrec<Positions>((tie) => {
+  const blockContent = fc.array(tie('block'), { depthIdentifier, maxLength: 3 })
+  const inlineContent = fc.array(tie('inline'), { depthIdentifier, maxLength: 4 })
+  const contentByModel = {
+    block: blockContent,
+    code: fc.array(text.map((held): AdfNode => ({ text: held, type: 'text' })), { maxLength: 2 }),
+    inline: inlineContent,
+    none: fc.constant<AdfNode[]>([]),
+  }
+  const blockMarks = fc.oneof({ arbitrary: fc.constant<AdfMark[]>([]), weight: 4 }, { arbitrary: marks, weight: 1 })
+  const blockNodes = Object.entries(blockDirectives).map(([type, directive]) => {
+    const argument = blockArgument(type)
+    const vocabulary: AttributeVocabulary = argument === undefined ? directive.attributes : { ...directive.attributes, [argument]: 'string' }
+    const node = fc.record({ attrs: attributes(vocabulary), content: contentByModel[directive.contentModel], marks: blockMarks }).map((held): AdfNode => ({ ...held, type }))
+    return { leaf: directive.contentModel === 'code' || directive.contentModel === 'none', node }
+  })
+  const unknownNode = fc
+    .record({ attrs: fc.dictionary(jsonKey, jsonValue, { maxKeys: 2, noNullPrototype: true }), content: fc.array(tie('inline'), { depthIdentifier, maxLength: 2 }), marks, type: unknownType })
+    .map((held): AdfNode => held)
+  const leafBlocks = blockNodes.filter((entry) => entry.leaf).map((entry) => entry.node)
+  const containerBlocks = blockNodes.filter((entry) => !entry.leaf).map((entry) => entry.node)
+  const misplacedWeight = 7
+  const paragraph = fc.oneof({ arbitrary: inlineContent, weight: 3 }, { arbitrary: fc.array(backtickRunNode, { maxLength: 4, minLength: 2 }), weight: 1 }).map((content): AdfNode => ({ content, type: 'paragraph' }))
+  const cell = (type: string) => paragraph.map((held): AdfNode => ({ content: [held], type }))
+  const listItems = fc.array(
+    blockContent.map((content): AdfNode => ({ content, type: 'listItem' })),
+    { depthIdentifier, maxLength: 3, minLength: 1 },
+  )
+  const flatCommonMarkShapes = [
+    fc.record({ content: inlineContent, level: fc.integer({ max: 6, min: 1 }) }).map(({ content, level }): AdfNode => ({ attrs: { level }, content, type: 'heading' })),
+    paragraph,
+    fc.record({ body: fc.array(fc.array(cell('tableCell'), { maxLength: 3 }), { maxLength: 2 }), header: fc.array(cell('tableHeader'), { maxLength: 3, minLength: 1 }) }).map(pipeTable),
+  ]
+  const nestingCommonMarkShapes = [
+    blockContent.map((content): AdfNode => ({ content, type: 'blockquote' })),
+    listItems.map((content): AdfNode => ({ content, type: 'bulletList' })),
+    fc
+      .record({ content: listItems, order: fc.oneof({ arbitrary: fc.integer({ max: 3, min: 0 }), weight: 4 }, { arbitrary: fc.integer({ max: 999999999, min: 0 }), weight: 1 }) })
+      .map(({ content, order }): AdfNode => ({ attrs: { order }, content, type: 'orderedList' })),
+  ]
+  const flatBlocks = [...weighted(leafBlocks, 2), ...weighted(flatCommonMarkShapes, flatCommonMarkShapeWeight)]
+  return {
+    block: fc.oneof(
+      { depthIdentifier, depthSize: 'small', maxDepth: 4 },
+      { arbitrary: fc.oneof(...flatBlocks), weight: flatBlocks.reduce((sum, entry) => sum + entry.weight, 0) },
+      { arbitrary: fc.oneof(...containerBlocks), weight: containerBlocks.length * 2 },
+      { arbitrary: fc.oneof(textNode, ...inlineNodes, unknownNode), weight: misplacedWeight },
+      { arbitrary: fc.oneof(...nestingCommonMarkShapes), weight: nestingCommonMarkShapes.length * nestingCommonMarkShapeWeight },
+    ),
+    inline: fc.oneof(
+      { depthIdentifier, depthSize: 'small', maxDepth: 4 },
+      { arbitrary: textNode, weight: 12 },
+      { arbitrary: autolinkTextNode, weight: 2 },
+      { arbitrary: backtickRunNode, weight: 3 },
+      { arbitrary: fc.oneof(...inlineNodes), weight: 7 },
+      { arbitrary: fc.oneof(...blockNodes.map((entry) => entry.node), unknownNode), weight: 2 },
+    ),
+  }
+})
+
+export const adfDocument = fc.array(positions.block, { depthIdentifier, maxLength: 4, minLength: 1 }).map((content): AdfDocument => toEditorNormal({ content, type: 'doc', version: 1 }))
+
+export function propertyRuns(gateRuns: number): { gate: boolean; numRuns: number; seed?: number } {
+  const deepRuns = env[deepRunsVariable]
+  if (deepRuns === undefined) return { gate: true, numRuns: gateRuns, seed: gateSeed }
+  assert.ok(/^[1-9]\d*$/.test(deepRuns), `${deepRunsVariable} is a run count in digits, such as ${deepRunsVariable}=10000: found ${JSON.stringify(deepRuns)}`)
+  return { gate: false, numRuns: Number(deepRuns) }
+}

todo-history.md

@@ -416,6 +416,73 @@ The done `todo.md` items in full, as they were written. `todo.md` keeps a one-li
         and 3h landed their answers and emptied it. The permanent ones — a link destination or
         title no escape spells, a paragraph opening with a code span — are the exceptions, named
         by AGENTS.md §2.
+- [x] **4 — Round-trip property tests (`0.2.0`)**, widening 3j's corpus round-trip past the
+      documents a human wrote — the thing that proves 2 and 3 beyond them.
+      **Settled** (the maintainer, 2026-09-13): `fast-check` generates and shrinks. The gate runs a
+      fixed seed, the properties together adding about five seconds per engine; an environment
+      variable raises the runs and randomizes the seed for local digging, and a counterexample
+      found becomes a round-trip fixture. The generators draw from the node tables — each node's
+      content model and attribute vocabulary as `adf/` records them, which 11 holds to Atlassian's
+      schema — and misplace a share of nodes so the carry (§3) is exercised; no JSON Schema walker
+      enters the tests. `toEditorNormal` stays internal. 2e5's collision test goes, since a
+      collision already fails the round-trip on the same fixtures; the fixture-duplicate test
+      stays.
+  - [x] **4.1 — Editor-normal and the node accessors.** `toEditorNormal(doc)` in
+        `src/adf/editor-normal.ts`, on 3i's merging: adjacent text nodes carrying identical marks and
+        no attributes merged, an empty `attrs`, `marks` or `content` the absent key, `-0` read as `0`
+        (§2); the round-trip tests compare the parser's output through it, and `serializeCanonicalJson`
+        beneath it walks iteratively. `nodeContent`/`nodeAttrs`/`nodeMarks` replace the 46 inline
+        `?? []`/`?? {}` reads in `src/` (23 `content`, 12 `marks`, 11 `attrs`) and the `attrs?.[key]`
+        reads, and the branch floor rises to the integer floor of what the suite then measures.
+        **Settled** (the maintainer, 2026-09-14): a text node carrying attributes never merges —
+        `0.1.0` merged a carried one into its neighbour on read-back — and the fix lands here, as does
+        the iterative serializer.
+  - [x] **4.2 — The ADF property.** `fast-check` joins `devDependencies`, AGENTS.md §5 naming what
+        it earns — shrinking a failing document to the nodes that break it — and §10 the properties
+        beside the corpus. A generated editor-normal document either refuses in `adfToMarkdown`
+        with a `ConvertError` or reads back through `markdownToAdf` to an equal document, and
+        nothing throws, under Node, Deno and Bun alike. 2e5's collision test is deleted.
+        **Settled** (the maintainer, 2026-09-14): about half the block positions draw attribute-less
+        CommonMark shapes — single-type lists, headings, blockquotes, pipe-table-shaped tables — where
+        the escaping lives. A round-trip break the property finds is fixed inside 4.2, one commit per
+        break with its round-trip fixture seen red first, and 4.2 lands when a deep run of about
+        10,000 per engine passes clean; a break needing design goes to the maintainer. The first two,
+        both shipped in `0.1.0`: an empty `href` with a title spelled `[a]( "")`, which reads back as
+        the href `""`, and a `[` or `]` in a link's destination or title inside a directive mark,
+        refused as the emitter's own output or, with `]`, losing the link. Later, settled the same
+        day: an autolink whose href holds a backtick takes the `[text](url)` form inside a
+        directive's content; and a V8 fault the deep runs hit — once `JSON.parse` has read a key
+        holding an escaped backslash, a later escaped quote or newline key comes back as that
+        backslash, on Node and Deno but not Bun — is accepted rather than worked around, since the
+        library only refuses such a document, so the generators' JSON keys avoid those characters; the
+        fault is reported upstream (https://issues.chromium.org/issues/521080746, nodejs/node#63785),
+        where the maintainer added to both on 2026-09-14. The review found one more break of the
+        same class, fixed the same way: a would-be inline directive in a link target inside a
+        directive's content.
+  - [x] **4.3 — The markdown property.** Generated markdown through `markdownToAdf` never throws,
+        and the runs fit the budget; where it parses and `adfToMarkdown` spells the result, that
+        spelling parses and emits to itself byte for byte (§2).
+        **Settled** (the maintainer, 2026-09-15): the generators and run parameters 4.2 and 4.3
+        share live in one test-only module in `src/`, kept out of the build and coverage, with
+        10c's properties as its third user. Under the gate seed the property asserts floors on the
+        runs reaching the fixpoint and on the directive-shaped ones. It lands when hunts of several
+        hundred thousand runs per engine pass clean, since the breaks hit once per ~150,000 runs,
+        past a 10,000-run bar. Two breaks, both shipped in `0.1.0`, are fixed inside it. A backtick
+        string an escape formed closed an earlier bare run's code span, since CommonMark reads no
+        escape inside one: an escaped backtick alone or, as the review found, one joined to the bare
+        run after it. A backtick run now escapes whole, and a bare run escapes wherever a later
+        string of its length forms around an escape in the same inline content: the generalized pass
+        the maintainer chose (2026-09-15). A paragraph's opening read as a link
+        reference definition across a `]` the emitter spelled: the emitter now escapes the opening
+        `[` exactly when the parser's own definition reader accepts the paragraph, and a link
+        opening it rides the carry until 13b.
+  - [x] **4.4 — The real payloads.** `corpus/real-payloads/` holds ADF Atlassian's editor wrote,
+        each round-tripped ADF→markdown→ADF with no expected markdown.
+        **Settled** (the maintainer, 2026-09-15): the chunk authors the payloads itself on the
+        maintainer's Atlassian test site — invented content, so nothing needs sanitizing — driving the
+        editor with Playwright, and reads the ADF back over REST. Only the documents are committed; no
+        client or fetch script enters the repo (§7). Later, settled the same day: the mentions keep
+        the test user's real account id (the maintainer, 2026-09-15).
 - [x] **5a — Rename to `@larvit/adf-codec` (`0.1.0`).** Before the first publish, the name being
       the published identity: `package.json` `name` and `repository`, the Gitea repo and its
       remote, the README title, §6's published-as line, the checkout directory.
@@ -562,6 +629,32 @@ The done `todo.md` items in full, as they were written. `todo.md` keeps a one-li
       `instrumentisto/geckodriver`, currency over size — the leg's whole worth is a real
       SpiderMonkey, which decays the moment the pin stops moving, and the smaller image was four
       Firefox majors behind with a publisher that may go quiet while Renovate stays silent.
+- [x] **11 — Atlassian's ADF schema as the tables' truth (`0.2.0`).** `@atlaskit/adf-schema`'s two
+      JSON Schemas vendored rather than the package installed (AGENTS.md §5), and the node tables
+      gated against them (§10). **Settled** (the maintainer, 2026-09-13): vendored at
+      `spec/adf-schema/` and re-pinned by hand when a need shows; the gate compares attribute names
+      and kinds, never value sets, over `full.json` and `stage-0.json` together.
+  - [x] **11a — The vendored schema.** `full.json` and `stage-0.json`, byte-exact from
+        `@atlaskit/adf-schema@57.4.9`'s `dist/json-schema/v1/`, at `spec/adf-schema/`, each pinned
+        by its SHA-256 in a test the way `spec.json` is. The version, the source and the Apache-2.0
+        attribution sit beside them with the licence text; no gate re-serializes either file.
+  - [x] **11b — The gate.** For each node and mark type the tables spell, the attribute names and
+        kinds equal the union over every definition in both files whose `type` enum names it,
+        `anyOf`/`allOf` branches included, the argument slot (`panelType`, `state`) counting as
+        spelled. Kinds: `string`; `number`, `integer` included; `boolean`; `json` for an object, an
+        array or an untyped value; an `enum`-only attribute takes its values' kind. What the schema
+        holds past the tables is pinned in two exact lists — an entry the schema no longer needs is
+        red, like a difference neither list names: gaps, attributes of a spelled type (57.4.9:
+        `link` `collection` `id` `occurrenceKey`, `rule` `color` `style` `weight`, `layoutSection`
+        `columnRuleStyle`), emptied by 13; and carried, types the tables do not spell (`alignment`
+        `annotation` `backgroundColor` `blockCard` `bodiedRule` `breakout` `dataConsumer`
+        `embedCard` `fontSize` `fragment` `indentation` `inlineExtension` `placeholder`), `doc` and
+        `text` counting as the grammar's own.
+- [ ] **12 — The `!adf:` re-spelling (`0.2.0`).**
+  - [x] **12a — The spec and the decision.** `spec/flavour.md` rewritten to the `!adf:` grammar and
+        the settled answers above, no colon directive form left in it; AGENTS.md §4's directive
+        bullet and prior-art line, and §8's escape hints and `::adf`/`::listBreak` examples, name
+        the new forms, §8 gaining the frozen content model.
 
 ## 5 — Ship `0.1.0`
 

todo.md

@@ -5,9 +5,11 @@ milestone. A done item shrinks to its title here; its full text moves to `todo-h
 
 ## Milestones
 
-Shipping order: 3h, 3i, 3j, 5a, 5b, 5c, 5d, 5 → `0.1.0` (shipped 2026-09-05); 5e before 2027-01; 3k, 4, 4b, 4c, 5g, 10, 11, 12 → `0.2.0`; 4d, 5f → `0.2.1`;
-6, 7 → `0.3.0`; 9 → TBD.
-The numbering is the order the work was planned in, not the order it ships.
+Shipping order: 3h, 3i, 3j, 5a, 5b, 5c, 5d, 5 → `0.1.0` (shipped 2026-09-05); 3k, 11, 4, 12, 13, 4b, 4c, 10, 5g → `0.2.0`; 4d, 5f → `0.2.1`;
+6, 7 → `0.3.0`; 9 → TBD; 5e last.
+The numbering is the order the work was planned in, not the order it ships. `0.2.0`'s order is settled
+(the maintainer, 2026-09-13): 11 makes the tables 4 generates from answer to Atlassian's schema, 4
+proves 12, 13 spells 11's gaps in 12's grammar, and 12 rewrites code 4b and 4c change.
 
 - [x] **0 — Scaffold.**
 - [x] **1a — The directive grammar.**
@@ -41,20 +43,11 @@ The numbering is the order the work was planned in, not the order it ships.
   - [x] **3i — The inline nodes and the marks.**
   - [x] **3j — The carry and the combinations.**
   - [x] **3k — The CommonMark spec suite.**
-- [ ] **4 — Round-trip property tests (`0.2.0`)**, widening 3j's corpus round-trip past the
-      documents a human wrote — the thing that proves 2 and 3 beyond them. Editor-normal (§2) is
-      finished here, on 3i's merging — `toEditorNormal(doc)` and the equality the round-trip
-      asserts, which over normalized input is the canonical serializer's compact spelling —
-      rather than staying spelled inline as `?? []` at every reader. The
-      reading half is `nodeContent`/`nodeAttrs`/`nodeMarks` over the ~28 sites spelling it
-      inline today, which also lifts the branch floor §10 keeps below 100 for exactly those
-      halves.
-      Generators emit editor-normal ADF (§2). Real sanitized ADF from live Atlassian APIs lands
-      here too (§10), in `corpus/real-payloads/`: an ADF→markdown→ADF check with no expected
-      markdown, the payloads supplied by the maintainer. This subsumes 2e5's collision property —
-      a document that round-trips proves no other document shares its spelling — so decide here
-      whether that gate stays as the parser-free, faster-failing signal or goes; the half holding
-      no fixture duplicates is hygiene rather than a round-trip claim, and stays either way.
+- [x] **4 — Round-trip property tests.**
+  - [x] **4.1 — Editor-normal and the node accessors.**
+  - [x] **4.2 — The ADF property.**
+  - [x] **4.3 — The markdown property.**
+  - [x] **4.4 — The real payloads.**
 - [ ] **4b — The block walk's retry (`0.2.0`).** `emitBlock` walks a subtree twice wherever
       `readableBlock` reads it whole and then gives up — a list item whose first line reads back
       as a thematic break — and the walk below does the same, so the cost doubles per level:
@@ -98,15 +91,18 @@ The numbering is the order the work was planned in, not the order it ships.
       timing is what turns "slow or hung" from a guess into a reading; the browser leg's own
       5.4–7.9s against a 17s warm gate is the number that made it obviously cheap.
 - [x] **5 — Ship `0.1.0`.**
-- [ ] **5e — The publish token's deadline (before 2027-01).** `0.1.0` published only once the npm
+- [ ] **5e — The publish token's deadline.** `0.1.0` published only once the npm
       token carried **Bypass 2FA**: the account requiring no 2FA on writes was not enough, and npm
       answered `EOTP` until the token itself bypassed. npm retires bypass-2FA tokens for direct
-      publishing around January 2027, and its replacement — trusted publishing over OIDC —
-      supports GitHub Actions, GitLab CI, CircleCI and Buildkite, not Gitea or self-hosted
-      runners. So the release path has an expiry date and no drop-in successor yet. Revisit before
-      the deadline: whether npm has added Gitea or self-hosted OIDC, and otherwise whether the
-      release moves to a human-approved staged publish — which fits badly with publish-on-merge,
+      publishing around January 2027, leaving them `npm stage publish`, which a maintainer
+      approves with 2FA; its replacement — trusted publishing over OIDC — supports GitHub-hosted
+      Actions, GitLab.com's shared runners and CircleCI's cloud, self-hosted runners planned
+      without a date. So the release path has an expiry date and no drop-in successor yet. Revisit:
+      whether npm has added Gitea or self-hosted OIDC, and otherwise whether the
+      release moves to the staged publish — which fits badly with publish-on-merge,
       and is the trade to weigh rather than discover on a red release run.
+      **Settled** (the maintainer, 2026-09-13): last of the known work, clear of `0.2.0`, placed
+      there knowing the cutoff may land before `0.2.0` ships.
 - [ ] **5f — Publish the bundle size (`0.2.1`).** Measure the shipped artifact and put the number in the
       README, kept honest by the release pipeline rather than by a human re-reading it. The
       quantity is what a consumer downloads and loads: the tarball `npm pack` produces, its
@@ -120,12 +116,15 @@ The numbering is the order the work was planned in, not the order it ships.
 - [ ] **5g — Reweight the README for the reader (`0.2.0`).** It opens with the pre-launch rationale —
       Atlassian's REST APIs, `pf-editor-service/convert` being decommissioned, a link to
       JRACLOUD-77436 — where a shipped package should answer what it is, what it does and for whom
-      first, then the shortest runnable example; the reader's top seconds go to "why this exists"
-      instead of "what I can do with it". Demote the Jira/endpoint background to a later "why
-      losslessness" note or drop it — the internal references (the `jira.atlassian.com` URL,
-      `pf-editor-service/convert`) don't belong in published text at all, no ticket IDs or internal
-      URLs. The `0.3.0` HTML future should read as an aside, not the lede: the package reads as a
-      shipped `0.1.0`, not a work-in-progress.
+      first, then the shortest runnable example.
+      **Settled** (the maintainer, 2026-09-13): the background goes entirely, no endpoint, ticket or
+      "why" note left. The top follows the package-README order: an npm version badge and the Gitea
+      Actions badge, a tagline that is also `package.json`'s `description`, a feature list and a
+      one-line table of contents, then install and the shortest runnable example; a table of
+      everything exported sits near the bottom. The HTML directions are one aside line under the API
+      until `0.3.0` ships them, the `// 0.3.0` signatures and the `0.3.0` guarantee going until then.
+      The tagline and `description` read "Lossless conversion between Atlassian Document Format and
+      extended markdown" until 7 restores HTML.
 - [x] **5a — Rename to `@larvit/adf-codec`.**
 - [x] **5b — The consumer's error surface.**
   - [x] **5b1 — The error's source position.**
@@ -137,11 +136,77 @@ The numbering is the order the work was planned in, not the order it ships.
 - [ ] **6 — The HTML dialect spec (`0.3.0`).** Element-by-element mapping, the `data-*` fidelity
       scheme, the opaque-carry form, and the documented foreign-element set `htmlToAdf` accepts.
 - [ ] **7 — HTML, ship `0.3.0`.** `adfToHtml`, `htmlToAdf`, the composed `markdownToHtml` /
-      `htmlToMarkdown`. CommonMark spec suite runs against `markdownToHtml` from here (§10).
+      `htmlToMarkdown`. CommonMark spec suite runs against `markdownToHtml` from here (§10). The
+      README's tagline and `package.json`'s `description` regain HTML (5g).
 - [ ] **8 — CLI.** A later goal, shaped around the personas once the library exists.
 - [ ] **9 — The online sandbox.** A web page with two textboxes converting back and forth between ADF and markdown, powered by the library's browser build.
-- [ ] **10 — Lossy conversion (`0.2.0`).** A direction that only converts what Markdown actually supports, keeping the ADF's data while dropping what markdown cannot hold — format, design and the richer nodes.
-- [ ] **11 — Evaluate `@atlaskit/adf-schema` (`0.2.0`).** Whether to add `@atlaskit/adf-schema` as a dev dependency to use as truth for the ADF schema.
+- [ ] **10 — Lossy conversion (`0.2.0`).** Markdown other tools render readably, to and from ADF,
+      keeping the content while dropping what markdown cannot hold — format, design and the richer
+      nodes.
+      **Settled** (the maintainer, 2026-09-14): two exports composed around the lossless pair, so §1's
+      four conversions stay four. `adfToPlainMarkdown(doc)` reduces the document ADF→ADF and hands it
+      to `adfToMarkdown`; `plainMarkdownToAdf(markdown)` hands the markdown to `markdownToAdf` and
+      lifts the result ADF→ADF. Both carry markdown conventions, so the reduction sits in
+      `src/markdown/emit/`, the lift in `src/markdown/parse/` and what both read in `src/markdown/`
+      (§11). The markdown is the flavour without directives — CommonMark, the pipe table and `~~` —
+      plus the conventions below, chosen for readability from a survey of GitHub, GitLab, Gitea,
+      Obsidian, Pandoc, MkDocs, Docusaurus, Typora, Joplin, Logseq, Bear, Notion, Azure DevOps and
+      Discord, GitHub's renderer confirming each shape. Writing refuses only what the document guard
+      refuses (`not-an-adf-document`, `unsupported-document-version`, `unsupported-nesting-depth`)
+      and degrades every other shape; reading refuses what `markdownToAdf` refuses. A lifted node
+      carries no `localId`. The lift also reads other tools' spellings — type words in any case,
+      Obsidian's aliases, `[X]` — since it reads their output and never writes those spellings.
+      - A `panel` is an alert: the marker alone on the quote's first line, a blank `>`, then the body
+        (`> [!WARNING]`), in GitHub's five words by colour — info `NOTE`, note `IMPORTANT`, tip and
+        success `TIP`, warning `WARNING`, error `CAUTION`, custom `NOTE`. The lift reads those words
+        back (`NOTE` info, `IMPORTANT` note, `TIP` tip, `WARNING` warning, `CAUTION` error) and
+        Obsidian's by meaning (hint tip; success, check and done success; attention warning; danger,
+        failure, fail, missing and bug error; any other word info). Text after a marker in its
+        paragraph is the panel's first body paragraph.
+      - An `expand` or `nestedExpand` is Obsidian's folded callout, `> [!NOTE]- Title`, a blank `>`,
+        then the body. The lift reads a fold sign (`-` or `+`) as an expand whatever the word, the
+        rest of the marker's paragraph as its title, and an expand inside an expand as a
+        `nestedExpand`.
+      - A `taskList` is a bullet list whose items lead with `[x]` or `[ ]` (`- [x] Write the spec`).
+        The lift reads a list whose every item is so marked back as a `taskList` — a `blockTaskItem`
+        where an item holds more than one block, a nested task list moved beside its item — and
+        leaves mixed and ordered lists plain. A `decisionList` is a plain bullet list.
+      - `backgroundColor` is `==text==`, and the lift gives `==text==` the Atlassian editor's default
+        highlight colour.
+      - `layoutSection`/`layoutColumn`, `bodiedExtension`, `bodiedSyncBlock`, `multiBodiedExtension`
+        and `extensionFrame` unwrap to their body blocks in order; the CommonMark blocks keep their
+        spelling, attributes dropped.
+      - `mention` and `status` become their text, the mention's `@` kept; `emoji` its text or else its
+        `shortName`; `date` its ISO date in UTC (`2026-09-13`); `inlineCard`, `blockCard` and
+        `embedCard` a link to their `url`, dropped when they carry only `data`; a `mediaSingle`
+        holding an external image stays `![alt](url)`; `media`, `mediaGroup` and `mediaInline` their
+        `alt` text or nothing; `caption` its text as a paragraph; `extension`, `inlineExtension` and
+        `syncBlock` their `text` attribute or nothing; `placeholder` nothing; a node no row names, or
+        one standing where no spelling holds it, its blocks or its text.
+      - A table stays a pipe table: the first row becomes the header, a cell's blocks join on one line
+        with spaces, and spans and the cells they cover drop.
+      - `code`, `em`, `link`, `strike` and `strong` stay and every other mark drops, keeping its text —
+        `subsup` too, since `~2~` is a strike on GitHub; a link no CommonMark escape writes becomes its
+        text, and a mark run CommonMark's flanking or matching cannot spell drops its mark.
+      - A newline in text becomes a hard break and edge whitespace is trimmed; carriage returns and
+        null characters are removed; a paragraph line opening with a code span whose backticks would
+        read as a fence loses the code mark; an empty paragraph drops, and adjacent lists of one type
+        merge.
+      - Rejected in the survey: `~sub~` and `^sup^`, underline and colour spellings, raw HTML
+        (`<details>`, `<mark>`), MkDocs `!!!` and the `:::` admonition family, footnotes, definition
+        lists, wikilinks, embeds, tags, comments, TOC tokens, spoilers, task states past `[x]`/`[ ]`,
+        and lifting bare URLs, `@name`, `:shortcode:` or ISO dates into nodes.
+  - [ ] **10a — The reduction.** `adfToPlainMarkdown`'s ADF→ADF reduction, tests first, a test per
+        row above.
+  - [ ] **10b — The lift.** `plainMarkdownToAdf`'s ADF→ADF lift, tests first, a test per row it reads,
+        other tools' spellings included; the editor's default highlight colour looked up and cited.
+  - [ ] **10c — The exports.** `adfToPlainMarkdown` and `plainMarkdownToAdf` exported with their README
+        sections, and two properties over 4.2's generators: writing refuses only the guard's codes,
+        and markdown `adfToPlainMarkdown` wrote reads back through `plainMarkdownToAdf` and writes
+        again byte for byte. AGENTS.md §1 records the pair as composed around the lossless one.
+- [x] **11 — Atlassian's ADF schema as the tables' truth.**
+  - [x] **11a — The vendored schema.**
+  - [x] **11b — The gate.**
 - [ ] **12 — The `!adf:` re-spelling (`0.2.0`).** Replace the colon directive grammar with the
       namespaced prefix, a breaking change to the emitted contract (shipped `0.1.0`, so §8 makes it
       `0.2.0`). Forms: block container `!adf:name arg {attrs}` … `!adf:/name` — the `/` parts open
@@ -149,29 +214,72 @@ The numbering is the order the work was planned in, not the order it ships.
       length rule go and every container opens the constant `!adf:`; block leaf `!adf:name arg
       {attrs}` with no closer; inline node `!adf:name[content]{attrs}`; directive marks
       `!adf:border`/`subsup`/`textColor`/`underline` `[content]{attrs}`. Attributes and their
-      escaping stay `{key=value}`; the literal escape is `\!adf:`; a line opening `!adf:` claims as
-      today's colon-run does. Leaf vs container is decided by the node's content model rather than
-      syntax — the `::`/`:::` split and §4's name-set-independent recognition go, a simplification
-      the carry makes safe (an unknown *block* node already rides the fence, not the directive).
-      The carry's reserved name becomes `carry`, both spellings — the block fence info string
-      `` `carry` `` and the inline `!adf:carry{json="…"}` — named for what it does: it carries a node
-      verbatim, never "unknown-node", since a known node no section spells where it stands rides it
-      too. A spelling change, not a semantic one: no `ConvertErrorCode` is added, removed or renamed,
-      the round-trip guarantee and the carry both hold through it. Mechanical surface: the grammar in
-      `spec/flavour.md`, `src/adf/block-directives.ts` + `inline-directives.ts`, `src/markdown/`'s
+      escaping stay `{key=value}`; the literal escape is `\!adf:`. Leaf vs container is decided by
+      the node's content model rather than syntax — the `::`/`:::` split goes, a simplification the
+      carry makes safe (an unknown *block* node already rides the fence, not the directive). The
+      carry's reserved name becomes `carry`, both spellings — the block fence info string `carry`
+      and the inline `!adf:carry{json="…"}` — named for what it does: it carries a node verbatim,
+      never "unknown-node", since a known node no section spells where it stands rides it too. No
+      `ConvertErrorCode` is added, removed or renamed, and the round-trip guarantee and the carry
+      both hold through it. Mechanical surface: the grammar in `spec/flavour.md`,
+      `src/adf/block-directives.ts` + `inline-directives.ts`, `src/markdown/`'s
       `directive-syntax.ts`, `opaque-carry.ts` and the `emit/` + `parse/` readers, every corpus
-      fixture (round-trip, normalization and `errors/`), `spec.test.ts`'s prose reader, and the
-      README's examples.
-  - [ ] **12a — The spec and the decision.** Rewrite `spec/flavour.md` to the `!adf:` grammar, and
-        record the departures in `AGENTS.md` §4 (leaf/container by content model, carry renamed
-        `carry`).
-  - [ ] **12b — The emit side.** `adfToMarkdown` spells `!adf:` / `!adf:/name` / `!adf:carry`; its
-        fixtures re-spelled, green.
-  - [ ] **12c — The parse side and the round-trip.** `markdownToAdf` reads it back; the round-trip
-        corpus, the `errors/` fixtures and the CommonMark spec suite re-spelled,
-        `markdownToAdf(adfToMarkdown(doc))` still equals `doc`.
-  - [ ] **12d — The README and the sweep.** The README's examples follow; sweep docs and fixtures
-        for any stale `::`/`:name` spelling.
+      fixture (round-trip, normalization and `errors/`), the prose reader over `spec/flavour.md`,
+      the markdown property's generator, and the README's examples.
+      **Settled** (the maintainer, 2026-09-13):
+      - A line opening `!adf:name` is a block line when a space or the line's end follows the name,
+        and a paragraph when `[` or `{` does. Claiming stays syntactic and structure comes from the
+        tables: an unknown name is `unknown-directive-name` at the opener, whatever follows it.
+      - An unescaped `!adf:` claims on its own anywhere inline: one completing no directive is
+        `malformed-directive`, the emitter escapes every literal `!adf:`, and `!adf:hardBreak{}`
+        keeps its braces. Block and inline share the one `\!adf:` escape hint.
+      - A closer names the innermost open container, crosses no list-item or blockquote edge,
+        indents as a fence does and carries nothing after the name; anything else is
+        `malformed-directive`.
+      - A node holding no content whose content model takes some is an empty opener–closer pair,
+        never a leaf.
+      - A spelled node's content model is frozen with its spelling: changing it is MAJOR (§8).
+      - The colon spellings are dropped, not refused: `0.1.0` markdown reads back as prose, `adf`
+        is no longer a reserved language, and `MIGRATION.md` tells a consumer to convert stored
+        markdown through `0.1.0`'s parser and `0.2.0`'s emitter.
+      - Inputs moving between codes ride the break: a leaf given a body, a container missing its
+        closer and `listBreak` with a body are `malformed-directive`, and an empty inline-body
+        container parses.
+      - Split by construct, each sub-item both directions: 55 of 78 round-trip fixtures feed both
+        the emit and the read-back test, so an emit-only chunk cannot land green.
+  - [x] **12a — The spec and the decision.**
+  - [ ] **12b — The inline form.** Inline nodes, directive marks, `text` and the inline carry
+        `!adf:carry{json=…}` spelled and read as `!adf:name[content]{attrs}`, with the prefix claim
+        and its escape; the round-trip, normalization and `errors/` fixtures holding inline forms
+        re-spelled, and the gate green. The content slot of `emoji`, `mention` and `status` refuses a
+        text node carrying attributes as `unsupported-node-shape`, which it drops silently today (the
+        maintainer, 2026-09-14).
+  - [ ] **12c — The block form.** Openers and `!adf:/name` closers, leaf vs container by content
+        model, empty pairs, `listBreak` and the `carry` fence, spelled and read; the fence-length
+        rule and the corpus test's fence nesting check deleted; the remaining fixtures re-spelled
+        and `errors/` re-derived under the shifted codes, and the gate green.
+  - [ ] **12d — The README, `MIGRATION.md` and the sweep.** The README's examples and error tables
+        follow, `MIGRATION.md` linked from one README line; docs and fixtures swept for any stale
+        `::`/`:name` spelling.
+- [ ] **13 — The schema's gap attributes (`0.2.0`).** Spell the attributes 11b pins as gaps, in
+      12's grammar, and empty the list.
+      **Settled** (the maintainer, 2026-09-13): a link `[text](url "title")` cannot hold takes the
+      directive mark `!adf:link[text]{attrs}` — one carrying `collection`, `id` or `occurrenceKey`,
+      or an `href` or `title` no CommonMark escape writes — and a directive link CommonMark could
+      spell is `unsupported-node-shape`. That leaves `unspellable-link` no cause, so it leaves
+      `ConvertErrorCode` in `0.2.0`, §8 recording the removal.
+  - [ ] **13a — `rule` and `layoutSection`.** `rule`'s `color`, `style` and `weight` and
+        `layoutSection`'s `columnRuleStyle` join their tables and `spec/flavour.md` bullets, with
+        round-trip fixtures; their gap entries go.
+  - [ ] **13b — The directive link.** `link` spelled as above in both directions, with a round-trip
+        fixture per trigger, `spec/flavour.md`'s Marks section following; `unspellable-link` removed
+        from the code list, its `errors/` fixtures and the CommonMark suite's `unspellable`
+        exceptions it cures re-derived, and the README's code table and its "not every document
+        converts back" guarantee following; the gap list is empty. A round-trip fixture holds the
+        shape 4.2's review left refused until then: an autolink-shaped link under a directive mark
+        whose href holds `\:name{`. A link opening a paragraph whose opening reads as a link
+        reference definition, which 4.3 leaves riding the carry, takes the directive link too, with
+        its round-trip fixture (the maintainer, 2026-09-15).
 
 ## The ADF inventory to cover
 

tsconfig.build.json

@@ -27,6 +27,6 @@
     "forceConsistentCasingInFileNames": true,
     "skipLibCheck": true
   },
-  "exclude": ["src/**/*.test.ts"],
+  "exclude": ["src/**/*.test.ts", "src/property-harness.ts"],
   "include": ["src"]
 }