20 - the prefix is the set, and §11 drops the list it enumerated

.oxlintrc.json

@@ -1,7 +1,7 @@
 {
   "$schema": "./node_modules/oxlint/configuration_schema.json",
   "categories": { "correctness": "off" },
-  "ignorePatterns": ["src/**/*.test.ts", "src/conformance/property-harness.ts"],
+  "ignorePatterns": ["src/**/*.test.ts", "src/property-harness.ts"],
   "rules": {
     "eslint/max-lines-per-function": ["error", { "IIFEs": true, "max": 52, "skipBlankLines": false, "skipComments": false }]
   }

AGENTS.md

@@ -1,89 +1,246 @@
 # Working in this repo
 
-The rules for every collaborator, human or agent, and an index of the decisions a reader would
-otherwise relitigate. Using the library: `README.md`. What is still to build: `todo.md`.
+Decisions a reader would otherwise relitigate, and the rules for every collaborator, human or
+agent. Using the library: `README.md`. What is still to build: `todo.md`.
 
-## Decisions
+## 1. Three formats, ADF is the hub
 
-In `docs/decisions.md`:
+ADF, one markdown flavour, one HTML dialect. Six directions exposed, but markdown↔HTML compose
+through ADF: four conversions exist to keep correct — never write a fifth. No fourth format, ever;
+each one doubles the directions.
 
-- Plain markdown is a flavour of the grammar
-- The round-trip is the product
-- Markdown in is a canonical fixpoint
-- Equality is deep
-- `!adf:textBreak{}` parts text CommonMark would join
-- An empty key spells `empty`
-- `-0` is spelled `-0`
-- Empty markdown is a document of no blocks
-- Unknown nodes ride the carry
-- The carry fence names the node type
-- A code block is a fence per text node
-- Foreign HTML sorts three ways
-- Names stay text
-- Directives under `!adf:`
-- CommonMark is a subset
-- Tables
-- Links
-- Ids stay site-local
-- Plain task ids come from position
-- A callout title keeps its link targets
-- The plain flavour's spellings
-- The HTML dialect
-- No runtime dependencies
-- Standards ship as data
-- fast-check
-- Any ES2022 engine
-- ESM only
-- One built entrypoint
-- Public on npm
-- The formats are API
-- The code list
-- Which code a cause takes
-- `message` and `path`
-- Publish on a version bump
-- Docs describe the release being built
-- No schema validation
-- The gate runs on Deno and Bun
-- The gate installs the tarball
-- Firefox reads the build
-- The coverage floors
-- The size ratchet
-- Properties on a fixed seed
-- The CommonMark suite checks three ways
-- The flavour spec is read as a source
-- The node tables answer to Atlassian's schema
-- Nothing recurses unbounded
-- Nothing spreads an unbounded array
-- A retry loop checks its own termination
-- Readers scan by index
-- The spelling memo
-- Cost fixes are measured, never timed
-- Only the hard break holds a raw newline
-- Emphasis follows CommonMark's matching
-- Readable spellings take the `try` prefix
-- The attribute vocabulary is ADF's
-- The source parts by ADF and format
+## 2. The round-trip is the product
 
-## 1. Nothing about any consumer
+`markdownToAdf(adfToMarkdown(doc))` and `htmlToAdf(adfToHtml(doc))` must equal `doc` — anything
+less silently destroys content an editor could not represent, in a document it did not author.
+When losslessness and readability conflict, losslessness wins.
+
+The other direction is a canonical fixpoint, not byte-identity: human markdown normalizes, the way
+back yields the library's canonical spelling, and that spelling round-trips byte-identically —
+where there is a way back. CommonMark spells some things the flavour has no escape for — a
+paragraph opening with a code span whose backticks read back as a fence — so a parse succeeding
+does not imply a spellable document;
+`corpus/commonmark-spec/exceptions.json` names those.
+
+"Equals" is structural equality over editor-normal ADF — adjacent text nodes with identical marks
+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.
+
+## 3. Unknown input policy
+
+- Unknown ADF node: carried opaquely — raw JSON rides a dedicated syntax in both formats and
+  restores to a deep-equal node. The round-trip holds for documents newer than the library. So
+  does a known node no section spells where it stands: a markdown serializer spells a node by type
+  without checking its position, and refusing loses a document ADF itself keeps in an
+  `unsupportedBlock`. Where a container's own spelling cannot hold the child it has — a
+  `bulletList` outside `listItem`, a `codeBlock` outside text — the error result names that
+  instead.
+- Unmappable foreign HTML element: error result naming the element — never a silent drop.
+- Bare `@name` / `:smile:` in typed text: stays a text node. Only directives produce
+  mention/emoji/media nodes; resolving names to ids needs I/O, which is the consumer's job.
+
+## 4. The flavour
+
+- 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.
+- Links: `[text](url "title")`, or `<url>` for a bare autolink-shaped text, wherever CommonMark
+  spells the mark; `!adf:link[text]{attrs}` where it does not — an attribute CommonMark cannot
+  hold, an `href` or `title` no canonical escape spells, a paragraph opening whose CommonMark
+  spelling would read as a link reference definition — and a directive link CommonMark could spell
+  is refused (the maintainer, 2026-09-13). No link wraps a link — the bracket form goes literal,
+  the directive form refused — which is CommonMark's prose where its reference implementation
+  nests one `<a>` in another (the maintainer, 2026-09-17).
+- Identity-bearing nodes carry their ids in attributes; a document is only portable within its
+  site — accepted.
+- The HTML dialect mirrors this: semantic elements, stable `adf-*` classes, `data-*` for what HTML
+  cannot express, text always escaped. No stylesheet ships.
+
+## 5. Dependencies
+
+`dependencies` is empty. A runtime dependency enters only through a decision entry here stating
+why ~20 lines of own code cannot do the job, who maintains it, and what auditing it costs. So the
+CommonMark and HTML parsers are written in this repo. A table a standard fixes is data rather than
+a dependency: HTML5's 2125 semicolon-terminated character references ship packed in their own
+module, so entity decoding is complete without one. The CommonMark spec suite is the same shape of
+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. 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`: `fast-check` earns its place shrinking a failing generated document to the nodes
+that break it, `oxlint` measuring §10's size ratchet — TypeScript 7 is a native compiler publishing
+no in-process parser, only the `unstable/` AST surface an out-of-process handshake reaches.
+
+## 6. The package contract
+
+- Runs on any ES2022 engine, not only Node — a browser as readily as a server. The shipped source
+  is ECMAScript and nothing else: no host import, no host global, no DOM. `tsconfig.build.json` is
+  that gate, typechecking and emitting the shipped files alone, so `node:fs`, `process` and an
+  ES2024 method are compile errors here rather than a consumer's crash there. The standard is the line, never an
+  engine list: one implementing it in part — Hermes is the live doubt, on §10's property escapes
+  and on lookbehind — is out of scope rather than a bug. Node's test runner, the corpus reads and
+  the build are the repo's own,
+  never the library's, and `engines.node` states the floor the shipped JavaScript needs — `>=18` —
+  never the higher one those repo-only tools want.
+- ESM only — no CommonJS build, no dual-package hazard.
+- One entrypoint: built JavaScript, `.d.ts` beside it. Do not add a TypeScript-source entrypoint —
+  Node refuses to type-strip under `node_modules` (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`),
+  so it cannot serve an npm consumer.
+- Published to public npmjs as `@larvit/adf-codec`. Public source: the Gitea repo
+  goes public, LICENSE in place, before the first publish.
+- Exact versions: `save-exact=true` in `.npmrc`.
+
+## 7. Nothing about any consumer
 
 No Jira client, no HTTP, no REST shapes, no issue keys, no actual consumer named anywhere. Design
 against the README's personas.
 
-## 2. Release automation
+## 8. Semver: the formats are API
 
-- The bump commit renames `CHANGELOG.md`'s `## Unreleased` to the version.
-- Exact versions: `save-exact=true` in `.npmrc`.
+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. 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: `\!adf:` for a directive, block line and inline
+alike, `\|` for every pipe row.
+Adding, removing or renaming a code is breaking, so a new cause takes an existing code whose
+name reads true of it in both directions; where none does and a plain name exists, a new code — in
+any 0.x minor, and after 1.0 only in a MAJOR (the maintainer, 2026-09-18). A refusal whose cause is
+this library's own invariant rather than the input takes the existing code nearest what the consumer
+sees — a document that does not convert is `unsupported-node-shape` — since a code no input reaches
+is one no consumer can switch on (the maintainer, 2026-09-20). A code names the
+cause; where one cause recurs across node types, across one mark's attributes or across
+directions, one code covers them all and
+`path` and `message` say which — `unsupported-nesting-depth` is the 500-level guard whichever
+direction hits it, `unspellable-character` the text node and the code block alike. Where two codes stay
+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 `!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
+for — `unspellable-link` went at `0.2.0`, the directive link spelling the `href` and `title` it
+refused and the attributes the carry held (the maintainer, 2026-09-13). A cause the carry answers gets no code: a mark no
+spelling writes rides the carry with its node. A directive whose name reads back to no node is
+`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: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, and a leaf given a body is refused
+at its opener, as a container missing its closer is (the maintainer, 2026-09-16); a well-formed
+directive the node tables refuse — an attribute a node does not hold or spells elsewhere, a value
+outside its kind or its canonical spelling, an argument, or a body of a shape its content model does
+not take — is
+`unsupported-node-shape`, the emitter's code for the same mismatch read the other way — one code
+across both directions for good, since the call site knows which direction it called and parting
+them after `0.1.0` is MAJOR. `unmappable-html` names the version rather than the element: this one
+converts no raw HTML, so at `0.2.0` the mapped elements stop erroring and the code stays for what
+no ADF node carries. A refusal found before its path is known — the block walk's, a directive
+reader's — is a `ConvertFault`, the code and message alone; the node walk attaches the path as it
+descends, so a document reports its first error in document order. `not-an-adf-document` carries
+the document's own path throughout: eight of the guard's nine branches read the document's own
+shape, and threading a path to the ninth — a malformed node anywhere in the tree — wants the
+manual stack §11's no-recursion rule forces, whose empty half no input reaches. The message names
+the violation instead. Depth is not one of the nine: `adfDocumentFault` returns the code with the
+message, so an attribute value past 500 levels is `unsupported-nesting-depth` from the emitter as
+it already is from the parser, both directions refusing the same value. A node's attribute is
+counted from the value itself, never from the `attrs` object holding it; a mark's is counted three
+levels in, because the block directive spells the whole mark set as one JSON attribute and the
+parser reads the value at the bottom of array, mark and `attrs`. `isAdfDocument` is true for a depth fault:
+a deep document is a document, as the 2000-level blocks and the 600-deep marks the guard already
+waves through are, and depth is the walks' answer rather than the shape's. A non-finite number
+stays parted where depth is joined: the parse says `unsupported-node-shape` because the markdown is
+at fault, the emit `not-an-adf-document` because the input is, and unlike depth nothing round-trips
+inconsistently between them.
+
+`position` is the parse side's alone: an emitter reads no source, so an emit error carries `path`
+and nothing more. It is `{ line, offset }` at the start of the line the block holding the refusal
+begins on — the offset indexing the string the caller passed, the line counted from 1 — minted by
+the block walk and attached as results return, so the innermost block wins, the emitter's own
+refusals the parser re-enters for the CommonMark spelling included.
+
+A parse names a position for every refusal it returns, so the type says so rather than the prose:
+`Result<T, E extends ConvertError = ConvertError>`, and a direction reading a source returns
+`Result<T, ParseError>` — `ConvertError` with `position` required. An optional field a direction
+always fills is a branch a consumer cannot take, and the `!` §11 bans is how they take it anyway.
+`htmlToAdf` inherits this at `0.2.0`; the composed `markdownToHtml` and `htmlToMarkdown` keep the
+wide `Result<T>`, since half their refusals come from an emit stage that read no source.
+
+## 9. Release automation
+
+- `package.json` version on `main` is the source of truth. CI on `main`: tests green and version
+  differs from npm → publish and tag `vX.Y.Z`. No bump, no deploy; the bump is each shipping PR's
+  deliberate semver judgment. `publish.sh` is that job, and `private: true` stops it before it
+  reads the token, so the pipeline is live and silent until the maintainer's first bump drops the
+  field.
+- Docs on `main` describe the release being built rather than the version npm holds, so they match
+  it the moment the bump publishes; add no interim note marking the gap (the maintainer,
+  2026-09-16).
+- The publish and the tag each observe their own end state — the version on npm, the tag on the
+  remote — and neither gates the other, so a run that dies between them converges on the next push
+  to `main` rather than leaving npm ahead of the tags. An unanswered registry reads the same as an
+  unpublished version, which npm's own duplicate rejection is what catches. The job rebuilds rather
+  than taking the gate's `dist`: the lockfile is committed, the image is patch-pinned and `tsc` is
+  deterministic, so the two builds agree, and promoting an artifact would make the release path
+  depend on a store that the gate would then have to keep.
 - Renovate watches devDependencies, Docker pins and action tags; automerges everything on green CI.
 - Docker images pin the full patch version (`node:24.19.0-alpine3.24`, never `node:24`), as
   specific as the publisher tags: `oven/bun:1.4.0-alpine` pins Bun's patch and leaves the base
   floating because Bun publishes nothing narrower. Actions pin semver tags.
 
-## 3. Tests first, in Docker
+## 10. Tests first, in Docker
 
 Test for the behaviour wanted first, then implement until green. `node --test`, beside the code.
-Node, tsc and npm never run on the host — only via the pinned images (§2). Tests are independent,
-containers are torn down after a run. A test reaches only for what Node's, Deno's and Bun's `node:`
-shims all carry.
+Node, tsc and npm never run on the host — only via the pinned images (§9). Tests are independent,
+containers are torn down after a run.
+
+The gate runs that same suite under Deno and Bun as well as Node, the three images pinned alike,
+and neither extra leg is Node's proof twice. Deno refuses an extensionless or directory specifier,
+so it holds the module graph to the fully-spelled form a browser can load; Bun runs
+JavaScriptCore, the one engine of the three that is not V8, where the Unicode property escapes
+emphasis matching leans on can disagree. Both refuse a run matching no test, so Node's is the only
+vacuous-green guard, and a test may reach only for what all three `node:` shims carry — the price
+of proving those engines over the corpus rather than over a smoke import.
+
+The gate then packs the build and installs the tarball under `package-tests/`, so `files`,
+`exports` and `types` are proved on the artifact that ships rather than on the source tree a
+self-reference would resolve against. `consumer.ts` typechecks the emitted `.d.ts` from outside
+`tsconfig.build.json` — declaration emit leaves the `.ts` specifiers
+`rewriteRelativeImportExtensions` rewrites in the JavaScript, and this is what says a consumer's
+resolver maps them, under `NodeNext` alone; a `.d.ts` reader that is not `tsc` stays unproven.
+`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 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.
+The leg re-checks the conversions and nothing else — each fixture's emitted markdown, its parsed
+document, its error code — leaving the corpus's pairing, uniqueness, source positions and
+byte-level equality to the Node suite that owns them.
 
 Every leg announces its name and, where a container is in play, the image, before it runs and its
 elapsed time after, `publish.sh` alongside `ci.sh`, so a long run reads as progress rather than as
@@ -91,97 +248,208 @@ a hang. A leg added later owes the same marker, and a function a leg reaches cha
 with `&&`, because the `||` that captures the leg's status suspends `set -e` for everything it
 calls. A leg whose output is both streamed and grepped keeps the copy in a `mktemp`
 file: `tee /dev/stderr` reopens fd 2, and under `./ci.sh > log 2>&1` the two offsets punch NUL
-holes through each other's lines.
+holes through each other's lines (4d).
 
-`PROPERTY_RUNS=<runs>` raises the property runs and randomizes the seed for local digging. The
-generators and run parameters properties share live in `src/conformance/property-harness.ts`,
-outside the build and coverage.
+The floors live in the `test` script, so `npm test` and the gate are one path: 100% of lines and
+functions, and a branch floor that only ever moves upward. It sits below 100 because the guards
+`noUncheckedIndexedAccess` and ADF's optional keys force — `?? []`, `?? {}`, `?.`, an index
+compared against `undefined` — have a half no valid document reaches.
 
-Each `- ` bullet in `spec/flavour.md`'s `## Block nodes`, `## Inline nodes` and `## Marks` declares
-the nodes named before its first em dash, with the attributes following `Attributes: ` — a
-parenthesized value set reading `string`; fenced examples are skipped. Keep prose out of a bullet.
+The size ratchet is the other such number, `.oxlintrc.json`'s single rule over the files
+`tsconfig.build.json` builds: a per-function line ceiling, set at that set's worst and moving only
+downward. It covers the built files alone, since one ceiling over the tests too would have to be
+their worst, loosening the guard over the shipped code. It guards against drift and never drives a
+refactor, so no cyclomatic rule and no second lint rule join it: neither measure picked out what
+nine readers found hard (the comprehension panel, 2026-09-20). Three switches guard a silent green:
+`IIFEs: true`, since oxlint exempts an IIFE otherwise; an explicit `-c`, so a config gone missing
+fails the leg instead of falling back to oxlint's own defaults; and `--deny-warnings`, since a rule
+from a category this config never names arrives as a warning it exits 0 on.
 
-## 4. Code rules
+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`.
 
-- Two-space indent, English everywhere. Alphabetical order wherever order carries no meaning,
-  keyed on the name a line introduces: an import sorts on its first binding, type imports ahead of
-  value imports, so moving or renaming a module reorders nothing.
+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
+named before its first em dash, with the attributes following `Attributes: ` — a parenthesized
+value set reading `string` — and must equal the tables in `adf/`. Keep prose in those sections out
+of a bullet; fenced examples are skipped. It guards the attributes alone: nodes that differ in
+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
+  carries no meaning, keyed on the name a line introduces rather than where it came from: an
+  import sorts on its first binding, type imports ahead of value imports, so moving or renaming a
+  module reorders nothing (the maintainer, 2026-09-18).
+- Failures are values: everything returns
+  `Result<T>` — `{ ok: true; value } | { ok: false; error: ConvertError }` — nothing throws.
+  `try/catch` only wrapped tightly around a call that genuinely throws, converted to a result on
+  the spot. A reader with no path to name returns `Read<T>` instead, the same two arms over a
+  `ConvertFault`, and `faulted` attaches the path where the walk knows it.
+- Only the hard break's inline segment holds a raw newline — every other spelling escapes one or
+  refuses it — which is how the whitespace carry finds a line edge.
+- Emphasis is spelled against CommonMark's matching, never flanking alone: a delimiter run in text
+  escapes wherever CommonMark could open or close with it, leaving the emitter's own delimiters the
+  only ones in play, and a pair that matching hands to another delimiter rides the carry instead.
+  `matchEmphasis` transcribes the reference `process_emphasis` line for line, and its closer walk and
+  opener search stay whole: broken into named steps they drift from the algorithm being faithful is
+  the whole point of.
+- A readable spelling tried ahead of a general one takes the `try` prefix and fails only where the
+  general form fails on the same node (20): refusing there refuses a document the general form
+  spells, so a refusal the general form does not share belongs in the general form or nowhere. A
+  readable spelling that must spell its subtree before it can give way — the list, whose
+  thematic-break first line and blank lines exist only spelled — hands that one walk to the general
+  form instead: giving way after the walk walks again at every level, doubling per level (4b).
+- Nothing recurses unbounded: the guards walk iteratively, and blocks, marks and JSON values — an
+  attribute's and a carried node's alike — are all held to 500 levels, so a deep document is a
+  `Result` rather than the stack overflow that waits near 2000. A level is one block-list
+  recursion in either direction: a readable list's items sit one below it, its directive
+  spelling's two. So a list giving way after its walk owes the directive form a level the walk
+  did not count, and the walk reports its headroom — the least slack any depth guard below it
+  has — for the fallback to refuse at zero rather than walk again; counting every list twice
+  halved the list limit, counting the directive form once doubled the parser's frames per level
+  (the maintainer, 2026-09-18).
+- Nothing spreads an unbounded array into a call — a node's siblings, a code block's held lines, a
+  mark run's segments: the argument list caps near 125k and throws a `RangeError` where a `Result`
+  is owed. A walk pushes one at a time. A literal spread (`[...value]`) is not the same thing and
+  is fine (4c).
+- A loop retrying an input until a fallback spells it refuses the pass taking no fallback, so its
+  termination is the loop's own check (28).
+- A reader takes the text and an index — a sticky regex whose `lastIndex` the caller sets on the
+  line before it reads, `indexOf` — never a fresh slice per character, and a per-character walk
+  hoists the scan that does not vary with the character. The pipeline persona feeds documents
+  nobody typed, and a megabyte through a quadratic walk is a minute rather than a millisecond. A
+  scan may keep what it read for a later walk of the same text, and the fallback where it kept
+  nothing must be the same reader over the same text at the same index, so the two cannot disagree
+  — which is what makes the kept value a memo rather than a second spelling (4c).
+- The parse keeps each node's readable spelling in a memo, so the `commonMarkSpelling` ask stops
+  spelling a node once per level above it (18). The node reference is the key, which holds
+  because the parse builds one object per position; `adfToMarkdown` passes no memo, where a
+  consumer's document may hold one node at two positions (4b). `text` and `spelling` carry no depth
+  and `headroom` is affine in it, so a read at or above the depth that filled the entry rebases; a
+  read below re-spells, because a hit skips the depth guards the walk it replaces runs and an
+  ordered list past the marker cap gives way, spending two emitter levels where the parser spent
+  one. A give-way is kept too and serves any depth, reading the node's shape alone. Only what
+  succeeded is kept, so no path minted at another position is ever read.
 - No casts: `as`, `as unknown as`, non-null `!`. A boundary owes a type guard validating the
   fields it claims (`isAdfDocument`); past it everything is typed. Make invalid states
   unrepresentable.
-- Failures are values: everything returns `Result<T>`, nothing throws. `try/catch` only wrapped
-  tightly around a call that genuinely throws, converted to a result on the spot. A reader with no
-  path to name returns `Read<T>`, and the walk attaches the path where it knows it.
+- `src/adf/` holds ADF's own knowledge, imports no format, and is where a construct both formats
+  read lives: the question is answered in ADF's vocabulary — a node type, an attribute kind, a
+  content model — and no delimiter, element name or escape reaches it. A helper that cannot answer
+  that way is two constructs, the ADF question there and the spelling in each format, the seam
+  `markAttributes` and `markSpellings` already draw; one that cannot be split is a gap to ask (§15).
+  `markdown/` and `html/` are peers: neither imports the other, and no third directory sits between
+  them. A primitive knowing neither ADF nor a format — `result.ts`, `json-value.ts`, `nesting.ts`,
+  `canonical-json.ts` — stays at `src/` root. A construct rises to `adf/` on its second consumer,
+  not in anticipation of one (the maintainer, 2026-09-21).
+- Each format directory (`markdown/`, `html/`) parts into `emit/` (ADF→format) and `parse/`
+  (format→ADF), the rest of it holding what both directions read. A construct's reader lives there
+  beside the regex the emitter escapes against, so the two cannot drift; a reader with no emit
+  counterpart goes in `parse/`, unless it is part of a construct that side already holds — a grammar
+  stays in one file rather than splitting across the seam. A rule both directions must answer
+  alike — whether a list marker interrupts a paragraph — is one function there too, never a copy
+  per direction, however conservative the copy would be. Where the rule is the emitter's own
+  choice, input consults it rather than restating it: the parser asks `commonMarkSpelling` which
+  form the emitter picks, and `openingLinkTakesDirective` whether the line a paragraph's opening
+  link starts forces the directive link, so no fixture the emitter writes can be refused, and a
+  spelling the emitter refuses gives its own error rather than a second name for it.
+- The attribute vocabulary is ADF's: `adf/` walks it and narrows each value to its kind, and a
+  format spells the narrowed value. A spelling that re-checks the type is the check's second copy.
+  Reading a spelling back is the format's own: the reader sits beside the spelling it inverts, so
+  decode-respell-compare cannot drift, and each format writes its own — canonical JSON for a
+  number is the markdown flavour's choice, not ADF's.
+- Explicit over implicit; descriptive names; no catch-all files (`utils`, `helpers`, `misc`); a
+  file does not repeat its directory in its name — `adf/document.ts`, never
+  `adf/adf-document.ts`. A name is the noun `spec/flavour.md` or ADF's schema uses for the
+  thing; a directory follows a split the spec draws; a placement these rules leave open goes
+  beside its only reader, or in what both read where there are two (the maintainer, 2026-09-18).
 - Reuse before adding; the smallest sufficient diff is the benchmark; no speculative generality —
   a second consumer, or it goes.
-- Explicit over implicit; descriptive names; no catch-all files (`utils`, `helpers`, `misc`); a file
-  does not repeat its directory in its name — `adf/document.ts`, never `adf/adf-document.ts`. A name
-  is the noun `spec/flavour.md` or ADF's schema uses for the thing.
 
-## 5. Prose to a minimum
+## 12. Prose to a minimum
 
 Applies everywhere: comments, every markdown file in this repo (this one included), PR text.
 
 - Default is no comment. One earns its single line only by naming an invariant, footgun or
   external constraint the code cannot show — never restatement, history, absence or arrangement.
-  A second line belongs in the commit message or a `docs/decisions.md` entry.
+  A second line belongs in the commit message or a decision entry here.
 - A doc paragraph says what the repo cannot say for itself, or it goes. The fix for a redundant
   one is deletion, not trimming. A false claim in any doc is a bug, fixed where found.
 - Published text — npm README, error messages, API docs — never references internal systems,
   tickets or repos.
 
-## 6. Commits and PRs
+## 13. Commits and PRs
 
 One-line commit messages and PR titles; short PR summaries. No AI-attribution markers, ever.
 
-## 7. The working loop
+## 14. Non-goals
 
-A session works one chunk, starting from the first item in `todo.md` not waiting on an unmet "Lands
-after", and stops when that chunk merges, whatever it was asked to finish: a release is a chain of
-sessions, so an instruction to work until a release is done names the chain, not the session. An
-open PR is a chunk already in flight, and finishing it is the session.
+No wiki markup (§1), no network or filesystem I/O, no name→id resolution (§3), no ADF schema
+validation or exported validator — a refusal that keeps the round-trip is not schema validation,
+so the one a spelled node carrying the same mark type twice earns stays, and input nesting a
+spelling inside its own kind (`*(*a*)*`) names that mark once, no shipped CSS (§4), no
+streaming APIs, no performance budget past §11's scanning rule — nothing here is tuned, and no
+figure is promised. A CLI is a later goal (`todo.md`), not a non-goal.
+
+## 15. The working loop
+
+One unchecked `todo.md` item per session, in the smallest PR-able chunk — split a big milestone
+into sub-items in `todo.md` before starting it. A chunk running a little over or under that is not
+worth deliberating; what matters is that nothing is left undone in the end. The session stops there
+whatever it was asked to finish: a release is a chain of sessions, and `todo.md`'s "Next session" is
+the handover, so an instruction to work until a release is checked names the chain, not the session.
 Per chunk:
 
-1. Fresh worktree off updated `origin/main`; implement tests-first (§3).
+1. Fresh worktree off updated `origin/main`; implement tests-first (§10).
 2. Run the larv-review flow until it passes and CI is green. A reviewer launch states the latest
    gate result (commit and outcome); a reviewer does not re-run `ci.sh` or the tests when a
    result exists for the commit under review, or when the diff since that result cannot affect
    it (docs-only) — re-run only what its own findings or fixes invalidate.
-3. Merge the PR (standing authorization, this repo only, granted by the maintainer through the
-   `0.2.0` release), report, stop.
+3. Merge the PR (standing authorization, this repo only, granted through the `0.2.0` release —
+   the maintainer, 2026-09-13), check the box in `todo.md` and move the item's text to
+   `todo-history.md`, leaving its title behind, report, stop.
 
 Reserved for the maintainer whatever any rule here says: changing `version` in `package.json` (a
-bump on `main` publishes, `docs/decisions.md` §Publish on a version bump — every release is the
-maintainer's) and the `NPM_TOKEN` secret.
+bump on `main` publishes, §9 — every release is the maintainer's) and the `NPM_TOKEN` secret.
 
 ### Ask, don't guess
 
-Any choice where what the maintainer would pick is not near-certain gets asked. The confidence bar
-is very high — asking too often is the accepted cost, guessing wrong is not.
+Any choice where what the maintainer would pick is not near-certain gets asked, and the answer
+lands as a decision in this file. The confidence bar is very high — asking too often is the
+accepted cost, guessing wrong is not.
 
-An ask is a gap in `docs/decisions.md`, and its answer is the entry that closes it, landing there —
-never the instance alone; an answer that is a goal lands in the README, one that is a working rule
-here. Before asking, name the class the question belongs to and the entries of that class; where
-one already decides it, apply it without asking, and where it reads two ways on this input, that
-reading is the ask. Never ask "A or B?": state the gap, the earlier entries of its class, the
-nearest text, a candidate entry in that file's voice, and the instance it yields. An entry that
-keeps collecting instances is wrong: rewrite it.
+An ask is a gap in this file, and its answer is the rule that closes the gap, never the instance
+alone. Before asking, name the class the question belongs to and the earlier `(the maintainer, …)`
+entries of that class; where a rule already decides it, apply it without asking, and where the rule
+reads two ways on this input, that reading is the ask. Never ask "A or B?": state the gap, the
+earlier asks of its class, the nearest text here, a candidate rule in this file's voice and section,
+and the instance it yields, and ask for the rule. The maintainer answers the rule, the rule lands
+here, and the instance follows from it in the chunk. A rule that keeps collecting instances is
+wrong: rewrite it rather than append to it.
 
-Which output the audience expects — README goal 5 — is settled by a reader panel rather than
-asked: three fresh-context readers, one per README persona the question serves, each given only
-`## Audience` and the input, writing what they expect before picking among outputs the goals
-allow, rendered, shuffled, with no rationale and nothing saying what is implemented. Three agreeing
-settle it; otherwise four more read, five of seven settle it, and less is a missing goal, asked.
-The verdict lands in `docs/decisions.md`.
+### Rules the loop has settled (the maintainer, 2026-09-18)
 
-Every new or changed markdown or HTML spelling goes to such a panel, seated by the people who read
-and write that format (README `## Audience`); a question about what an app relies on seats the
-developer personas.
-
-### Stated numbers
-
-A stated number — 500 levels, the branch floor — is kept; a chunk that cannot keep it asks, naming
-the number it can reach. A number the code needs and no entry states is a gap.
+- A finding inside the chunk's item is fixed in the chunk. Outside it, a new `todo.md` item, always
+  in a release, weighed against every item on that release by the personas and §1–§3 — an item it
+  outweighs moves later. A weighing no rule decides is asked as a gap.
+- A stated number — 500 levels, the branch floor — is kept; a chunk that cannot keep it asks,
+  naming the number it can reach. A number the code needs and no rule states is a gap.
+- Where the shipping order names no release for the next unchecked item, the chunk is planning that
+  release: every unscheduled item weighed as above, the order written in `todo.md`, and the
+  maintainer's approval taken before any code.
 
 ### The continuous loop
 

CHANGELOG.md

@@ -1,38 +0,0 @@
-# Changelog
-
-## Unreleased
-
-- **Breaking:** directives, the inline opaque carry among them (now `!adf:carry{json="…"}`), are
-  spelled under an `!adf:` prefix (`!adf:name … !adf:/name`, `!adf:name[content]{attrs}`,
-  `!adf:name arg {attrs}`) in place of the `:::`/`::`/`:name` forms, and the block carry is a code
-  fence whose info string `adf:<type>` names the node's type, its body the node's JSON without
-  `type`: text holding an unescaped `!adf:` and a code fence whose info string opens `adf:` are
-  claimed, and `adf` is an ordinary code block language. Convert stored markdown per `MIGRATION.md`.
-- **Breaking:** `markdownToAdf` reads markdown holding no block as a document whose `content` is
-  empty, as Atlassian's schema requires; `!adf:doc {content=none}` spells a document holding no
-  `content` key.
-- `markdownToAdf(adfToMarkdown(doc))` deep-equals `doc`: two adjacent text nodes a reader would
-  join are parted by `!adf:textBreak{}`, an empty `attrs`, `content` or `marks` is spelled
-  `{attrs=empty}`, `{content=empty}` or `{marks=empty}`, `-0` is spelled `-0`, and a `codeBlock`
-  of several text nodes is a fence per node. A `codeBlock` holding other than plain text nodes
-  rides the block carry, where it was refused.
-- **Breaking:** `unspellable-link` leaves `ConvertErrorCode`; a link whose `href` or `title` no
-  CommonMark escape spells is written as `!adf:link[text]{attrs}`.
-- **Breaking:** some directive refusals carry `malformed-directive` where they carried
-  `unsupported-node-shape`, and an empty node's leaf and closed spellings swap which one parses;
-  `MIGRATION.md` lists each.
-- **Breaking:** a link whose text holds another link keeps the inner link and leaves the outer
-  brackets literal text, where `0.1.0` split the outer link around it; see `MIGRATION.md`.
-- Add `adfToPlainMarkdown` and `plainMarkdownToAdf`, a lossy pair converting ADF to and from
-  markdown GitHub, GitLab and Obsidian render: alerts, callouts, task lists, `==highlights==` and
-  pipe tables.
-- Spell `rule`'s `color`, `style` and `weight`, `layoutSection`'s `columnRuleStyle` and a link's
-  `collection`, `id` and `occurrenceKey` directly where they rode the opaque carry.
-- Fix an image inside another image's description: it flattens into the alt text, where it was
-  refused.
-
-## 0.1.0
-
-- First release: lossless conversion between ADF and an extended markdown flavour —
-  `adfToMarkdown`, `markdownToAdf` and `isAdfDocument`. Nothing throws, and every error carries a `code` from a
-  closed list.

MIGRATION.md

@@ -22,8 +22,7 @@ import { markdownToAdf as markdownToAdf010 } from 'adf-codec-0.1'
 
 function migrateMarkdown(stored: string) {
   const parsed = markdownToAdf010(stored)
-  // 0.1.0's reader was editor-normal, so a document with no content key always meant an empty one.
-  return parsed.ok ? adfToMarkdown({ ...parsed.value, content: parsed.value.content ?? [] }) : parsed
+  return parsed.ok ? adfToMarkdown(parsed.value) : parsed
 }
 ```
 
@@ -41,12 +40,12 @@ function migrateMarkdown(stored: string) {
 | `::media {id=a type=file}` | `!adf:media {id=a type=file}` |
 | `::taskItem TODO {localId=i}`: an empty `caption`, `decisionItem`, `paragraph` or `taskItem`, or an empty `heading` carrying `localId` | `!adf:taskItem TODO {localId=i}` then `!adf:/taskItem` |
 | `:mention[@Mikael]{id=5b10a2}` | `!adf:mention[@Mikael]{id=5b10a2}` |
-| the `adf` code fence and `:adf{json="…"}` | the `adf:<type>` code fence, its JSON without `type`, and `!adf:carry{json="…"}` |
+| the `adf` code fence and `:adf{json="…"}` | the `carry` code fence and `!adf:carry{json="…"}` |
 | `\:` keeps a directive literal | `\!adf:` keeps a directive literal |
 | `:adf{json="…"}` carrying a link for its `collection`, `id` or `occurrenceKey` | `!adf:link[text]{attrs}` |
 
 A colon run and `:name[` are plain text now, and `adf` an ordinary code block language; text
-holding an unescaped `!adf:` and a code fence whose info string opens `adf:` are claimed instead.
+holding an unescaped `!adf:` and a `carry` fence are claimed instead.
 
 ### Readings
 
@@ -55,8 +54,6 @@ Markdown the spelling table leaves alone, which `0.2.0` reads as a different doc
 | Input | `0.1.0` | `0.2.0` |
 | --- | --- | --- |
 | a link whose text already holds one (`[a<https://example.com/>b](/v)`) | marks every node the inner link does not, splitting the outer link around it | leaves the outer brackets literal text; write the pieces as separate links to keep them |
-| markdown holding no block (`markdownToAdf("")`) | `{ type: 'doc', version: 1 }` | `{ content: [], type: 'doc', version: 1 }`; `!adf:doc {content=none}` reads as the former |
-| a code fence whose info string opens `adf:` (```` ```adf:x ````) | a `codeBlock` with that language | the block carry; write `!adf:codeBlock {language="adf:x"}` around a bare fence to keep the code block |
 
 ### Error codes
 
@@ -66,7 +63,6 @@ it named converts.
 | Input | `0.1.0` | `0.2.0` |
 | --- | --- | --- |
 | a link whose `href` or `title` no CommonMark escape spells, on emit | `unspellable-link` | spells `!adf:link[text]{attrs}` |
-| a `codeBlock` holding other than plain text nodes, on emit | `unsupported-node-shape` | rides the block carry |
 | a leaf node given a body (`media`, `listBreak`) | `unsupported-node-shape` | `malformed-directive` |
 | a node with a block body written as a leaf (`panel`) | `unsupported-node-shape` | `malformed-directive` |
 | an empty node the `::taskItem` spelling row names, written as a leaf | parses | `malformed-directive` |

README.md

@@ -5,10 +5,7 @@ an HTML dialect.
 
 **Status: published — the markdown round-trip (`adfToMarkdown`, `markdownToAdf`); HTML at
 `0.2.0`.**
-Plan:
-[`todo.md`](https://gitea.larvit.se/larvit/adf-codec/src/branch/main/todo.md). Decisions:
-[`docs/decisions.md`](https://gitea.larvit.se/larvit/adf-codec/src/branch/main/docs/decisions.md). Changes:
-[`CHANGELOG.md`](https://gitea.larvit.se/larvit/adf-codec/src/branch/main/CHANGELOG.md). The lossless flavour's grammar:
+Plan: `todo.md`. Decisions: `AGENTS.md`. The flavour's grammar:
 [`spec/flavour.md`](https://gitea.larvit.se/larvit/adf-codec/src/branch/main/spec/flavour.md).
 Upgrading from `0.1.0`: [convert your markdown first](https://gitea.larvit.se/larvit/adf-codec/src/branch/main/MIGRATION.md).
 
@@ -24,37 +21,39 @@ represent.
 
 ## Goals
 
-The most useful ADF conversion library available, judged by these goals, in priority order:
+In priority order.
 
-1. **Lossless, and every call returns a result, never a throw.**
-2. **ADF is the hub.**
-3. **Each format reads and writes as its standard says.**
-4. **Our markdown is CommonMark, extended only where CommonMark has no spelling.**
-5. **No surprises: output reads and edits the way its audience expects.**
-6. **Lossy conversion drops form, never content.**
-7. **Runs in any JavaScript engine, with no runtime dependencies and nothing to configure or connect.**
-8. **Fast, and linear in the document's size.**
-9. **Easy to find, and clear at a glance what it does.**
+1. **Lossless first.** The round-trip holds for every document, node types this version does not
+   know included; one that has no spelling is refused and says where, never silently reduced.
+   Every goal below gives way to this one.
+2. **Three formats, ADF the hub.** ADF, one markdown flavour, one HTML dialect, markdown↔HTML
+   composing through ADF — four conversions to keep correct, never a fifth, and never a fourth
+   format.
+3. **Plain CommonMark is input.** Markdown written for something else converts — the exceptions
+   below are the whole of them — and every spelling the flavour claims on top of CommonMark is
+   escapable, so the flavour is opt-in.
+4. **Output a person can edit.** A node CommonMark can spell gets that spelling; the directive
+   form carries only what CommonMark cannot hold.
+5. **Failures are values.** Nothing throws, and `code` is a closed list — as much a contract as
+   the emitted formats are.
+6. **Nothing in the way.** No runtime dependencies, no I/O, no configuration, no host API: ESM on
+   any ES2022 engine, in a browser as readily as on a server.
 
 ## Audience
 
-Application developers embedding the library, in four personas. All four rely on the guarantees
-below and on an error's `code` being a closed list; none may rely on an error message's wording,
-which is free text.
+Application developers embedding the library, addressed as personas rather than named consumers
+(AGENTS.md §7). All four rely on the guarantees below and on `code` being a closed list; none may
+rely on an error message's wording, which is free text.
 
 - **Viewer/editor app** — shows a document, lets a human edit, posts it back. Relies on the
   round-trip holding for whatever the site's editor wrote, unknown node types included, and on a
   refusal arriving before the save rather than after.
 - **Bot posting content** — turns generated markdown into ADF. Relies on plain CommonMark being
-  valid input, so nothing upstream has to learn a flavour.
+  valid input, so nothing upstream has to learn the flavour.
 - **Export/indexing tool** — converts ADF to markdown or HTML in bulk. Relies on readable output
   and on every refusal being deterministic, so a document that fails fails the same way next run.
 - **LLM/agent pipeline** — hands documents to a model as markdown and writes the edits back.
-  Relies on the round-trip and on markdown a reader half-knowing the lossless flavour can still edit.
-
-Behind those apps, the people who read and write the markdown, and later the HTML: product
-managers, engineers and support agents working in Atlassian products through a plugin or another
-UI. They know markdown and not ADF, and rely on every spelling saying what it means to them.
+  Relies on the round-trip and on markdown a reader half-knowing the flavour can still edit.
 
 ## The shape
 
@@ -74,84 +73,25 @@ if (result.ok) {
 }
 ```
 
-Serves Goals 1, 2 and 7. Pure functions, each taking a whole document and returning a whole
-result; no I/O, no configuration. `markdownToHtml` and `htmlToMarkdown` convert through ADF:
-they keep only what ADF holds, and refuse what `markdownToAdf` or `htmlToAdf` refuses.
+Pure functions, no I/O, no configuration. ADF is the hub: markdown↔HTML compose through it.
 
 ```ts
 adfToMarkdown(doc: AdfDocument): Result<string>
 markdownToAdf(markdown: string): Result<AdfDocument, ParseError>
 isAdfDocument(v: unknown): v is AdfDocument
 
-adfToPlainMarkdown(doc: AdfDocument): Result<string>
-plainMarkdownToAdf(markdown: string): Result<AdfDocument, ParseError>
-
 adfToHtml(doc: AdfDocument): Result<string>               // 0.2.0
 htmlToAdf(html: string): Result<AdfDocument, ParseError>  // 0.2.0
-markdownToHtml(markdown: string): Result<string>          // 0.2.0
-htmlToMarkdown(html: string): Result<string>              // 0.2.0
+markdownToHtml(markdown: string): Result<string>          // 0.2.0, via ADF
+htmlToMarkdown(html: string): Result<string>              // 0.2.0, via ADF
 ```
 
 `Result<T>` is `{ ok: true; value: T } | { ok: false; error: ConvertError }` — nothing throws.
 
-## Plain markdown
-
-Serves Goal 6. Plain markdown is a second flavour of the same grammar. `adfToPlainMarkdown` writes
-markdown other tools render — GitHub, GitLab, Obsidian and the like — keeping the content and
-dropping the rest: attributes, colours, layout, identity. Content is what a reader of the rendered
-document sees or follows: its text, images and link targets. It refuses only
-`not-an-adf-document`, `unsupported-document-version` and `unsupported-nesting-depth`, and writes
-no directive.
-
-`plainMarkdownToAdf` reads what `markdownToAdf` reads and refuses what it refuses, and reads the
-conventions below as nodes, taking other tools' spellings too; a backslash keeps a marker as text:
-`\==x==`, `> \[!NOTE]`, `- \[x]`. Markdown `adfToPlainMarkdown` wrote reads back and writes again
-byte for byte; the document it came from does not come back.
-
-To edit a document and save it back, use `adfToMarkdown` and `markdownToAdf`: saving what this pair
-read replaces mentions, attachments and macros with text.
-
-| ADF | Written | Read back |
-| --- | --- | --- |
-| `panel` | a GitHub alert, `> [!WARNING]`: info `NOTE`, note `IMPORTANT`, tip and success `TIP`, warning `WARNING`, error `CAUTION`, custom `NOTE` | `NOTE` info, `IMPORTANT` note, `TIP` tip, `WARNING` warning, `CAUTION` error, and Obsidian's: hint tip; success, check, done success; attention warning; danger, failure, fail, missing, bug, error error; any other word info — in any case; the rest of the marker's line is the first paragraph |
-| `expand`, `nestedExpand` | Obsidian's folded callout, `> [!NOTE]- Title` | `-` or `+` after any word, the rest of the marker's line the title; a link reads `text (target)`, or its text alone where the text is the target with or without `mailto:`; an expand inside an expand is a `nestedExpand` |
-| `taskList` | `- [x] Done`, `- [ ] Todo` | a bullet list whose every item is so marked, `[X]` too |
-| `backgroundColor` | `==text==` | `==text==` on one line, the text touching both delimiters, bounded outside by whitespace, punctuation or a line edge, or touching a Han, Hangul, Hiragana, Katakana, Thai, Lao, Khmer or Myanmar character on either side, in the editor's default highlight `#f8e6a0` |
-| `table` | a pipe table: the first row its header, a cell's blocks on one line, a span kept under its header by empty cells | — |
-| `decisionList` | a bullet list | — |
-| `mention`, `status`, `emoji`, `date` | their text: `@` kept, a mention with none `@` and its id, an emoji its `shortName` without, a date `2026-09-13` in UTC | — |
-| `inlineCard`, `blockCard`, `embedCard` | a link to the card's URL, else its name | — |
-| external `media` | `![alt](url)` in a block, `[alt](url)` inline | — |
-| stored `media`, `mediaInline`, `extension`, `inlineExtension` | their `alt` or `text` | — |
-| `layoutSection`, `bodiedExtension`, `bodiedSyncBlock`, `multiBodiedExtension`, `extensionFrame`, `caption`, a node this version does not know | its blocks or its text | — |
-| `placeholder` | nothing | — |
-
-- Content the document only references, with no text of its own to keep, leaves an italic note
-  naming it where it stood: `_(image not included)_` for stored media with no `alt`,
-  `_(link card not included)_` for a card with neither URL nor name, an extension with no `text`
-  its key, `_(jira-issues-table not included)_`, or `_(extension not included)_` without one, and
-  `_(synced block not included)_` for a `syncBlock`.
-- `backgroundColor`, `code`, `em`, `link`, `strike` and `strong` stay; every other mark drops,
-  keeping its text, and so does a mark the flavour cannot spell where it stands.
-- A newline in text is a hard break and in an expand's title a space, edge whitespace outside a
-  link or code span is trimmed, carriage returns and null characters are removed, and an empty
-  paragraph drops.
-- An ordered list numbered past `999999999`, or adjacent ordered lists whose numbering does not
-  continue, is one bullet list keeping its numbers as text.
-- A task list beside a bullet or decision list, or holding a block other than a task, joins one
-  bullet list keeping its states as text: `- \[x] Done`.
-- Text that would read as a marker takes a backslash: `==` wherever it could open or close a
-  highlight, `[!…]` opening a quote, and `[x]` or `[ ]` opening any list item, since GitHub reads
-  that marker per item.
-- A node read back carries no `localId` except a `taskList`, `taskItem` or `blockTaskItem`, which
-  Atlassian's schema requires one on: each gets a UUID v4 hashed from the whole markdown and its
-  position, the same on every read. Join markdown bound for one document and read it once: the same
-  markdown read twice into one document repeats its ids.
-
 ## The errors
 
-Serves Goal 1. An ADF node type this version does not know is not an error: the lossless pair
-carries it opaquely and restores it unchanged ([`docs/decisions.md`](https://gitea.larvit.se/larvit/adf-codec/src/branch/main/docs/decisions.md#unknown-nodes-ride-the-carry)).
+An ADF node type this version does not know is not an error: it is carried opaquely and restores
+unchanged (AGENTS.md §3).
 
 `ConvertError` is `{ code, message, path, position? }`. `code` is the exported `ConvertErrorCode`,
 stable across minors and safe to `switch` on exhaustively with no `default`; `message` is free text
@@ -171,14 +111,14 @@ UTF-16 code unit, a JavaScript string index rather than a codepoint or a byte of
 or before the refusal — currently the start of the line the enclosing block begins on; a later
 minor may narrow that, never widen it.
 
-Parsing — `markdownToAdf` and `plainMarkdownToAdf`, and `htmlToAdf` at `0.2.0`:
+Parsing — `markdownToAdf`, and `htmlToAdf` at `0.2.0`:
 
 | Code | Fires when | What you can do |
 | --- | --- | --- |
-| `malformed-directive` | an `!adf:` the grammar cannot read — a prefix completing no directive, an unclosed container, `[content]` or `{attrs}`, a closer with no container of its name open, a leaf given a body, `{attrs}` out of order or duplicated, invalid JSON in an opaque carry | write the spelling the message names, or escape the prefix — `\!adf:`, block and inline alike — to keep it literal text |
+| `malformed-directive` | an `!adf:` the grammar cannot read — a prefix completing no directive, an unclosed container, `[content]` or `{attrs}`, a closer with no container of its name open, a leaf given a body, `{attrs}` out of order or duplicated, invalid JSON in a `carry` | write the spelling the message names, or escape the prefix — `\!adf:`, block and inline alike — to keep it literal text |
 | `malformed-pipe-table` | a pipe row that is no pipe table — a missing or ragged `---` delimiter row, an alignment colon in it, or a row not opening with a pipe | open every row with a pipe and give the delimiter row the header's cell count; to keep the lines literal text instead, escape the leading pipe of every one — escaping a single row leaves the next to open a fresh table and fail the same way |
 | `unknown-directive-name` | a directive whose name is no node or mark this version spells | check the name in `spec/flavour.md`, or escape the prefix as `\!adf:`; the spelling itself is well formed, so a later minor may give the name meaning |
-| `unmappable-html` | the input holds an HTML construct the documented element set does not map, a comment and a processing instruction among them — at this version that is every raw HTML construct in markdown, the element set landing at `0.2.0` | remove the construct, or write what it holds in the lossless flavour |
+| `unmappable-html` | the input holds an HTML construct the documented element set does not map, a comment and a processing instruction among them — at this version that is every raw HTML construct in markdown, the element set landing at `0.2.0` | remove the construct, or write what it holds in the flavour |
 | `unmappable-image` | an image sits inside other content that is not another image's description, or carries a title | give the image a paragraph of its own and drop the title |
 
 Emitting — `adfToMarkdown`, and `adfToHtml` at `0.2.0`:
@@ -198,19 +138,12 @@ emit refuses:
 | `unspellable-line-start` | a paragraph line begins with a code span whose backticks would read back as a code fence | put any text before the code span |
 | `unspellable-whitespace` | an `emoji`, `mention` or `status` holds a newline in the text its inline directive spells in the content slot | replace it with a space — an inline directive never spans lines |
 | `unsupported-nesting-depth` | blocks, marks, an attribute's JSON or a carried node's JSON nest past 500 levels | keep the ADF and pass the document over, or show it read-only; flatten the input where you are the one who wrote it |
-| `unsupported-node-shape` | a node carries an attribute, value, argument or body its type does not take, or lacks one it needs — or markdown writes as a directive a node or mark the lossless flavour spells as CommonMark | write the shape the message names; `spec/flavour.md` lists every type's attributes and body |
+| `unsupported-node-shape` | a node carries an attribute, value, argument or body its type does not take, or lacks one it needs — or markdown writes as a directive a node or mark the flavour spells as CommonMark | write the shape the message names; `spec/flavour.md` lists every type's attributes and body |
 
 ## The guarantees
 
-Serves Goals 1, 3 and 4.
-
-- `markdownToAdf(adfToMarkdown(doc))` deep-equals `doc` — every key and value as `doc` holds it,
-  adjacent text nodes, an empty `attrs`, `content` or `marks` and `-0` included, and unknown node
-  types carried opaquely
-  ([`docs/decisions.md`](https://gitea.larvit.se/larvit/adf-codec/src/branch/main/docs/decisions.md#unknown-nodes-ride-the-carry)).
-- Markdown this library reads, and markdown it writes, means what the CommonMark spec says; from
-  `0.2.0`, well-formed HTML means what the HTML standard says, read or written. The bullets below
-  name every exception.
+- `markdownToAdf(adfToMarkdown(doc))` equals `doc` — unknown node types included, carried opaquely
+  (AGENTS.md §3).
 - Plain CommonMark is valid input to `markdownToAdf` apart from the raw HTML `unmappable-html`
   names, with three carve-outs — literal text matching directive, pipe-table or strikethrough
   syntax is claimed (escapable — `spec/flavour.md`) — and one gap: a CommonMark image fits only as
@@ -236,20 +169,17 @@ Serves Goals 1, 3 and 4.
   error too — ADF holds no column alignment. The trailing pipe is canonical output, optional in
   input.
 - Past that and `~~`, no GFM: an autolink literal and a `- [ ]` marker stay text, and a checklist
-  is the `taskList` directive — `plainMarkdownToAdf` turns the marker into a `taskList`.
-- A document nested deeper than 500 levels is an error result, not a stack overflow, and no input
-  makes a call loop forever.
-- The emitted formats are semver surface
-  ([`docs/decisions.md`](https://gitea.larvit.se/larvit/adf-codec/src/branch/main/docs/decisions.md#the-formats-are-api)).
-- **`0.2.0`** — `htmlToAdf(adfToHtml(doc))` deep-equals `doc`; fidelity HTML cannot express rides
+  is the `taskList` directive.
+- A document nested deeper than 500 levels is an error result, not a stack overflow.
+- The emitted formats are semver surface (AGENTS.md §8).
+- **`0.2.0`** — `htmlToAdf(adfToHtml(doc))` equals `doc`; fidelity HTML cannot express rides
   `data-*` attributes. Foreign HTML maps a documented element set, which markdown's raw HTML reads
   through as well, and a construct outside it is an error; well-formed HTML only — no tag-soup
   recovery.
 
 ## The package
 
-Serves Goal 7. ESM only, no runtime dependencies, public npm. Built JavaScript with `.d.ts`
-beside it. Pure ECMAScript at an ES2022 baseline, reaching for no host API; the test suite runs
-under Node, Deno and Bun, and a headless Firefox converts the corpus through the built entrypoint.
-Contract: [`docs/decisions.md`](https://gitea.larvit.se/larvit/adf-codec/src/branch/main/docs/decisions.md#any-es2022-engine), §Any
-ES2022 engine to §Public on npm.
+ESM only, no runtime dependencies, public npmjs. Built JavaScript with `.d.ts` beside it.
+Pure ECMAScript at an ES2022 baseline, reaching for no host API; the test suite runs under Node,
+Deno and Bun, and a headless Firefox converts the corpus through the built entrypoint.
+Contract: `AGENTS.md` §5–6.

browser-tests/convert-corpus.js

@@ -1,19 +1,16 @@
 try {
   const { adfToMarkdown, isAdfDocument, markdownToAdf } = await import('/dist/index.js')
-  const { serializeCanonicalJson } = await import('/dist/canonical-json.js')
-  // WebDriver's JSON reads -0 back as 0, so a document crosses as its canonical spelling.
-  const spelled = (result) => (result.ok ? { ok: true, value: `${serializeCanonicalJson(result.value, 'two-space')}\n` } : result)
   window.convertCorpus = (corpus) => ({
     errors: corpus.errors.map(({ markdown, name }) => ({ name, parsed: markdownToAdf(markdown) })),
-    normalization: corpus.normalization.map(({ markdown, name }) => ({ name, parsed: spelled(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 ? spelled(markdownToAdf(emitted.value)) : undefined }
+      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: spelled(markdownToAdf(markdown)) }
+      return { emitted: adfToMarkdown(adf), isDocument: isAdfDocument(adf), name, parsed: markdownToAdf(markdown) }
     }),
   })
 } catch (cause) {

browser-tests/run.js

@@ -2,6 +2,7 @@ import assert from 'node:assert/strict'
 import { createServer } from 'node:http'
 import { extname, join } from 'node:path'
 import { readFileSync, readdirSync } from 'node:fs'
+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'
@@ -106,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.equal(result.parsed.value, json)
+    assert.deepEqual(toEditorNormal(result.parsed.value), JSON.parse(json))
   })
 }
 
@@ -114,7 +115,7 @@ 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.equal(result.parsed.value, fixture(name, '.json'))
+    assert.deepEqual(toEditorNormal(result.parsed.value), JSON.parse(fixture(name, '.json')))
   })
 }
 
@@ -124,7 +125,7 @@ for (const [index, { json, name }] of corpus.realPayloads.entries()) {
     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.equal(result.parsed.value, json)
+    assert.deepEqual(toEditorNormal(result.parsed.value), JSON.parse(json))
   })
 }
 

corpus/README.md

@@ -1,10 +1,10 @@
 # The corpus
 
-One directory per contract kind:
+One directory per contract kind, each landing with its milestone:
 
 - `round-trip/` — `<name>.json` + `<name>.md`: the markdown `adfToMarkdown` must emit for that
-  document, byte for byte, and that `markdownToAdf` must read back to it (`docs/decisions.md` §The
-  round-trip is the product). Grouped by what the fixture exercises.
+  document, byte for byte, and that `markdownToAdf` must read back to it (AGENTS.md §2). Grouped
+  by what the fixture exercises.
 - `normalization/` — `<name>.md` + `<name>.json`: markdown input, and the document
   `markdownToAdf` must build from it, which must in turn emit and read back to itself. The
   markdown is not canonical.
@@ -16,10 +16,11 @@ One directory per contract kind:
   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
   `reason`. `kind` is `mark-model` (the permanent count divergence from ADF's mark-per-text-node
-  model), `unspellable` (parses but the flavour has no spelling) or `pending` (a parser gap).
+  model), `unspellable` (parses but the flavour has no spelling) or `pending` (a parser gap a later
+  milestone may close).
 
-JSON is two-space indent, keys sorted, and a document read back must deep-equal the fixture's
-(`docs/decisions.md` §Equality is deep). `spec.json` is the vendored, upstream machine-readable suite, byte-exact from
+JSON is editor-normal (AGENTS.md §2), two-space indent, keys sorted. `spec.json` is the vendored,
+upstream machine-readable suite, byte-exact from
 [spec.commonmark.org](https://spec.commonmark.org/0.31.2/spec.json) (CommonMark 0.31.2, © John
 MacFarlane, [CC-BY-SA-4.0](https://creativecommons.org/licenses/by-sa/4.0/)), and is not
 re-serialized by the corpus gate.

corpus/errors/carry-fence-type-spellable.error

@@ -1 +0,0 @@
-unsupported-node-shape

corpus/errors/carry-fence-type-spellable.md

@@ -1,5 +0,0 @@
-```adf:
-{
-  "type": "blockCard"
-}
-```

corpus/errors/carry-fence-type-unspellable.error

@@ -1 +0,0 @@
-unsupported-node-shape

corpus/errors/carry-fence-type-unspellable.md

@@ -1,3 +0,0 @@
-```adf:\\
-{}
-```

corpus/errors/carry-fence-type.error

@@ -1 +0,0 @@
-unsupported-node-shape

corpus/errors/carry-fence-type.md

@@ -1,5 +0,0 @@
-```adf:blockCard
-{
-  "type": "blockCard"
-}
-```

corpus/errors/carry-invalid-json.md

@@ -1,3 +1,3 @@
-```adf:blockCard
-{"attrs":
+```carry
+{"type":
 ```

corpus/errors/code-block-fence-languages.error

@@ -1 +0,0 @@
-unsupported-node-shape

corpus/errors/code-block-fence-languages.md

@@ -1,8 +0,0 @@
-!adf:codeBlock
-```js
-a
-```
-```ts
-b
-```
-!adf:/codeBlock

corpus/errors/document-directive-bare.error

@@ -1 +0,0 @@
-unsupported-node-shape

corpus/errors/document-directive-bare.md

@@ -1 +0,0 @@
-!adf:doc

corpus/errors/document-directive-misplaced.error

@@ -1 +0,0 @@
-unsupported-node-shape

corpus/errors/document-directive-misplaced.md

@@ -1,3 +0,0 @@
-!adf:doc {content=none}
-
-Text.

corpus/errors/empty-attrs-with-attributes.error

@@ -1 +0,0 @@
-unsupported-node-shape

corpus/errors/empty-attrs-with-attributes.md

@@ -1,3 +0,0 @@
-!adf:panel info {attrs=empty}
-Text.
-!adf:/panel

corpus/errors/empty-content-with-body.error

@@ -1 +0,0 @@
-unsupported-node-shape

corpus/errors/empty-content-with-body.md

@@ -1,3 +0,0 @@
-!adf:paragraph {content=empty}
-Text.
-!adf:/paragraph

corpus/errors/empty-key-value.error

@@ -1 +0,0 @@
-unsupported-node-shape

corpus/errors/empty-key-value.md

@@ -1,3 +0,0 @@
-!adf:paragraph {attrs=none}
-Text.
-!adf:/paragraph

corpus/errors/empty-marks-wrapped.error

@@ -1 +0,0 @@
-unsupported-node-shape

corpus/errors/empty-marks-wrapped.md

@@ -1 +0,0 @@
-**!adf:date{marks=empty}**

corpus/errors/text-break-attributes.error

@@ -1 +0,0 @@
-unsupported-node-shape

corpus/errors/text-break-attributes.md

@@ -1 +0,0 @@
-a!adf:textBreak{x=y}b

corpus/errors/text-break-content.error

@@ -1 +0,0 @@
-unsupported-node-shape

corpus/errors/text-break-content.md

@@ -1 +0,0 @@
-a!adf:textBreak[x]b

corpus/errors/text-break-marks-differ.error

@@ -1 +0,0 @@
-unsupported-node-shape

corpus/errors/text-break-marks-differ.md

@@ -1 +0,0 @@
-**a**!adf:textBreak{}b

corpus/errors/text-break-misplaced.error

@@ -1 +0,0 @@
-unsupported-node-shape

corpus/errors/text-break-misplaced.md

@@ -1 +0,0 @@
-!adf:textBreak{}Hello

corpus/round-trip/block-nodes/code-block-carry.json

@@ -14,19 +14,7 @@
     },
     {
       "attrs": {
-        "language": "adf:blockCard"
-      },
-      "content": [
-        {
-          "text": "{\n  \"attrs\": {}\n}",
-          "type": "text"
-        }
-      ],
-      "type": "codeBlock"
-    },
-    {
-      "attrs": {
-        "language": "adf:"
+        "language": "carry"
       },
       "content": [
         {

corpus/round-trip/block-nodes/code-block-carry.md

@@ -1,18 +1,12 @@
-```carry
+!adf:codeBlock {language=carry}
+```
 {
   "type": "blockCard"
 }
 ```
-
-!adf:codeBlock {language="adf:blockCard"}
-```
-{
-  "attrs": {}
-}
-```
 !adf:/codeBlock
 
-!adf:codeBlock {language="adf:"}
+!adf:codeBlock {language=carry}
 ````
 ```
 ````

corpus/round-trip/block-nodes/code-block-text-nodes.json

@@ -1,56 +0,0 @@
-{
-  "content": [
-    {
-      "attrs": {
-        "language": "js"
-      },
-      "content": [
-        {
-          "text": "const a = 1\n",
-          "type": "text"
-        },
-        {
-          "text": "const b = 2",
-          "type": "text"
-        }
-      ],
-      "type": "codeBlock"
-    },
-    {
-      "content": [
-        {
-          "text": "a",
-          "type": "text"
-        },
-        {
-          "text": "```",
-          "type": "text"
-        },
-        {
-          "text": "\n",
-          "type": "text"
-        }
-      ],
-      "type": "codeBlock"
-    },
-    {
-      "attrs": {
-        "language": "has`tick",
-        "wrap": true
-      },
-      "content": [
-        {
-          "text": "x",
-          "type": "text"
-        },
-        {
-          "text": " y ",
-          "type": "text"
-        }
-      ],
-      "type": "codeBlock"
-    }
-  ],
-  "type": "doc",
-  "version": 1
-}

corpus/round-trip/block-nodes/code-block-text-nodes.md

@@ -1,31 +0,0 @@
-!adf:codeBlock
-```js
-const a = 1
-
-```
-```js
-const b = 2
-```
-!adf:/codeBlock
-
-!adf:codeBlock
-```
-a
-```
-````
-```
-````
-```
-
-
-```
-!adf:/codeBlock
-
-!adf:codeBlock {language="has\u0060tick" wrap=true}
-```
-x
-```
-```
- y 
-```
-!adf:/codeBlock

corpus/round-trip/block-nodes/document-without-content.json

@@ -1,4 +0,0 @@
-{
-  "type": "doc",
-  "version": 1
-}

corpus/round-trip/block-nodes/document-without-content.md

@@ -1 +0,0 @@
-!adf:doc {content=none}

corpus/round-trip/block-nodes/empty-keys.json

@@ -1,89 +0,0 @@
-{
-  "content": [
-    {
-      "content": [],
-      "type": "paragraph"
-    },
-    {
-      "attrs": {},
-      "content": [
-        {
-          "text": "Plain words.",
-          "type": "text"
-        }
-      ],
-      "type": "paragraph"
-    },
-    {
-      "content": [],
-      "type": "rule"
-    },
-    {
-      "attrs": {
-        "level": 2
-      },
-      "content": [
-        {
-          "text": "Title",
-          "type": "text"
-        }
-      ],
-      "marks": [],
-      "type": "heading"
-    },
-    {
-      "attrs": {
-        "panelType": "info"
-      },
-      "content": [],
-      "type": "panel"
-    },
-    {
-      "content": [
-        {
-          "attrs": {},
-          "content": [
-            {
-              "content": [
-                {
-                  "text": "Item",
-                  "type": "text"
-                }
-              ],
-              "type": "paragraph"
-            }
-          ],
-          "type": "listItem"
-        },
-        {
-          "content": [
-            {
-              "content": [
-                {
-                  "text": "Next",
-                  "type": "text"
-                }
-              ],
-              "type": "paragraph"
-            }
-          ],
-          "type": "listItem"
-        }
-      ],
-      "type": "bulletList"
-    },
-    {
-      "content": [],
-      "type": "codeBlock"
-    },
-    {
-      "attrs": {
-        "language": "js"
-      },
-      "marks": [],
-      "type": "codeBlock"
-    }
-  ],
-  "type": "doc",
-  "version": 1
-}

corpus/round-trip/block-nodes/empty-keys.md

@@ -1,32 +0,0 @@
-!adf:paragraph {content=empty}
-!adf:/paragraph
-
-!adf:paragraph {attrs=empty}
-Plain words.
-!adf:/paragraph
-
-!adf:rule {content=empty}
-
-!adf:heading {level=2 marks=empty}
-Title
-!adf:/heading
-
-!adf:panel info {content=empty}
-!adf:/panel
-
-!adf:bulletList
-!adf:listItem {attrs=empty}
-Item
-!adf:/listItem
-!adf:listItem
-Next
-!adf:/listItem
-!adf:/bulletList
-
-!adf:codeBlock {content=empty}
-!adf:/codeBlock
-
-!adf:codeBlock {marks=empty}
-```js
-```
-!adf:/codeBlock

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

@@ -1,4 +1,4 @@
-```adf:panel
+```carry
 {
   "attrs": {
     "rounded": true
@@ -13,11 +13,12 @@
       ],
       "type": "paragraph"
     }
-  ]
+  ],
+  "type": "panel"
 }
 ```
 
-```adf:panel
+```carry
 {
   "attrs": {
     "panelType": "extra info"
@@ -32,7 +33,8 @@
       ],
       "type": "paragraph"
     }
-  ]
+  ],
+  "type": "panel"
 }
 ```
 

corpus/round-trip/combinations/negative-zero.json

@@ -1,83 +0,0 @@
-{
-  "content": [
-    {
-      "attrs": {
-        "order": -0
-      },
-      "content": [
-        {
-          "content": [
-            {
-              "content": [
-                {
-                  "text": "First",
-                  "type": "text"
-                }
-              ],
-              "type": "paragraph"
-            }
-          ],
-          "type": "listItem"
-        }
-      ],
-      "type": "orderedList"
-    },
-    {
-      "attrs": {
-        "level": -0
-      },
-      "content": [
-        {
-          "text": "Title",
-          "type": "text"
-        }
-      ],
-      "type": "heading"
-    },
-    {
-      "attrs": {
-        "extensionKey": "toc",
-        "extensionType": "com.atlassian.confluence.macro.core",
-        "parameters": {
-          "maxLevel": -0
-        }
-      },
-      "type": "extension"
-    },
-    {
-      "content": [
-        {
-          "attrs": {
-            "data": [
-              -0
-            ],
-            "url": "https://example.com/"
-          },
-          "type": "inlineCard"
-        },
-        {
-          "marks": [
-            {
-              "attrs": {
-                "color": "#000000",
-                "size": -0
-              },
-              "type": "border"
-            }
-          ],
-          "text": "x",
-          "type": "text"
-        }
-      ],
-      "type": "paragraph"
-    },
-    {
-      "attrs": {
-        "x": -0
-      },
-      "type": "blockCard"
-    }
-  ],
-  "type": "doc",
-  "version": 1
-}

corpus/round-trip/combinations/negative-zero.md

@@ -1,21 +0,0 @@
-!adf:orderedList {order=-0}
-!adf:listItem
-First
-!adf:/listItem
-!adf:/orderedList
-
-!adf:heading {level=-0}
-Title
-!adf:/heading
-
-!adf:extension {extensionKey=toc extensionType="com.atlassian.confluence.macro.core" parameters="{\"maxLevel\":-0}"}
-
-!adf:inlineCard{data="[-0]" url="https://example.com/"}!adf:border[x]{color="#000000" size=-0}
-
-```adf:blockCard
-{
-  "attrs": {
-    "x": -0
-  }
-}
-```

corpus/round-trip/commonmark-subset/document-empty.json

@@ -1,5 +1,4 @@
 {
-  "content": [],
   "type": "doc",
   "version": 1
 }

corpus/round-trip/inline-nodes/empty-keys.json

@@ -1,98 +0,0 @@
-{
-  "content": [
-    {
-      "content": [
-        {
-          "attrs": {},
-          "type": "date"
-        },
-        {
-          "text": " ",
-          "type": "text"
-        },
-        {
-          "content": [],
-          "type": "date"
-        }
-      ],
-      "type": "paragraph"
-    },
-    {
-      "content": [
-        {
-          "text": "a",
-          "type": "text"
-        },
-        {
-          "marks": [],
-          "type": "hardBreak"
-        },
-        {
-          "text": "b",
-          "type": "text"
-        }
-      ],
-      "type": "paragraph"
-    },
-    {
-      "content": [
-        {
-          "attrs": {
-            "id": "x",
-            "text": "@M"
-          },
-          "content": [],
-          "type": "mention"
-        }
-      ],
-      "type": "paragraph"
-    },
-    {
-      "content": [
-        {
-          "text": "bare",
-          "type": "text"
-        },
-        {
-          "marks": [],
-          "text": "marked",
-          "type": "text"
-        }
-      ],
-      "type": "paragraph"
-    },
-    {
-      "content": [
-        {
-          "marks": [
-            {
-              "attrs": {},
-              "type": "em"
-            }
-          ],
-          "text": "x",
-          "type": "text"
-        },
-        {
-          "text": " and ",
-          "type": "text"
-        },
-        {
-          "attrs": {
-            "shortName": ":a:"
-          },
-          "marks": [
-            {
-              "attrs": {},
-              "type": "strong"
-            }
-          ],
-          "type": "emoji"
-        }
-      ],
-      "type": "paragraph"
-    }
-  ],
-  "type": "doc",
-  "version": 1
-}

corpus/round-trip/inline-nodes/empty-keys.md

@@ -1,9 +0,0 @@
-!adf:date{attrs=empty} !adf:date{content=empty}
-
-a!adf:hardBreak{marks=empty}b
-
-!adf:mention[@M]{content=empty id=x}
-
-bare!adf:carry{json="{\"marks\":[],\"text\":\"marked\",\"type\":\"text\"}"}
-
-!adf:carry{json="{\"marks\":[{\"attrs\":{},\"type\":\"em\"}],\"text\":\"x\",\"type\":\"text\"}"} and !adf:carry{json="{\"attrs\":{\"shortName\":\":a:\"},\"marks\":[{\"attrs\":{},\"type\":\"strong\"}],\"type\":\"emoji\"}"}

corpus/round-trip/inline-nodes/text-break.json

@@ -1,154 +0,0 @@
-{
-  "content": [
-    {
-      "content": [
-        {
-          "text": "Hello, ",
-          "type": "text"
-        },
-        {
-          "text": "world",
-          "type": "text"
-        }
-      ],
-      "type": "paragraph"
-    },
-    {
-      "content": [
-        {
-          "marks": [
-            {
-              "type": "strong"
-            }
-          ],
-          "text": "Hello, ",
-          "type": "text"
-        },
-        {
-          "marks": [
-            {
-              "type": "strong"
-            }
-          ],
-          "text": "world",
-          "type": "text"
-        }
-      ],
-      "type": "paragraph"
-    },
-    {
-      "content": [
-        {
-          "marks": [
-            {
-              "type": "code"
-            }
-          ],
-          "text": "a",
-          "type": "text"
-        },
-        {
-          "marks": [
-            {
-              "type": "code"
-            }
-          ],
-          "text": "b",
-          "type": "text"
-        }
-      ],
-      "type": "paragraph"
-    },
-    {
-      "content": [
-        {
-          "marks": [
-            {
-              "attrs": {
-                "href": "https://example.com/"
-              },
-              "type": "link"
-            }
-          ],
-          "text": "a",
-          "type": "text"
-        },
-        {
-          "marks": [
-            {
-              "attrs": {
-                "href": "https://example.com/"
-              },
-              "type": "link"
-            }
-          ],
-          "text": "b",
-          "type": "text"
-        }
-      ],
-      "type": "paragraph"
-    },
-    {
-      "content": [
-        {
-          "text": "Line\n",
-          "type": "text"
-        },
-        {
-          "text": "next",
-          "type": "text"
-        }
-      ],
-      "type": "paragraph"
-    },
-    {
-      "content": [
-        {
-          "marks": [
-            {
-              "type": "underline"
-            }
-          ],
-          "text": "a",
-          "type": "text"
-        },
-        {
-          "marks": [
-            {
-              "type": "underline"
-            }
-          ],
-          "text": "b",
-          "type": "text"
-        }
-      ],
-      "type": "paragraph"
-    },
-    {
-      "content": [
-        {
-          "marks": [
-            {
-              "attrs": {},
-              "type": "underline"
-            }
-          ],
-          "text": "a",
-          "type": "text"
-        },
-        {
-          "marks": [
-            {
-              "type": "underline"
-            }
-          ],
-          "text": "b",
-          "type": "text"
-        }
-      ],
-      "type": "paragraph"
-    }
-  ],
-  "type": "doc",
-  "version": 1
-}

corpus/round-trip/inline-nodes/text-break.md

@@ -1,13 +0,0 @@
-Hello, !adf:textBreak{}world
-
-**Hello, !adf:textBreak{}world**
-
-`a`!adf:textBreak{}`b`
-
-[a!adf:textBreak{}b](https://example.com/)
-
-Line!adf:text{text="\n"}!adf:textBreak{}next
-
-!adf:underline[a!adf:textBreak{}b]
-
-!adf:underline[a]{attrs=empty}!adf:underline[b]

corpus/round-trip/opaque-carry/carry-in-wrappers.md

@@ -1,15 +1,17 @@
-> ```adf:blockCard
+> ```carry
 > {
 >   "attrs": {
 >     "url": "https://example.com/quoted"
->   }
+>   },
+>   "type": "blockCard"
 > }
 > ```
 
-- ```adf:blockCard
+- ```carry
   {
     "attrs": {
       "url": "https://example.com/listed"
-    }
+    },
+    "type": "blockCard"
   }
   ```

corpus/round-trip/opaque-carry/code-block-children.json

@@ -1,35 +0,0 @@
-{
-  "content": [
-    {
-      "attrs": {
-        "language": "js"
-      },
-      "content": [
-        {
-          "marks": [
-            {
-              "type": "strong"
-            }
-          ],
-          "text": "const a = 1",
-          "type": "text"
-        }
-      ],
-      "type": "codeBlock"
-    },
-    {
-      "content": [
-        {
-          "text": "a",
-          "type": "text"
-        },
-        {
-          "type": "hardBreak"
-        }
-      ],
-      "type": "codeBlock"
-    }
-  ],
-  "type": "doc",
-  "version": 1
-}

corpus/round-trip/opaque-carry/code-block-children.md

@@ -1,32 +0,0 @@
-```adf:codeBlock
-{
-  "attrs": {
-    "language": "js"
-  },
-  "content": [
-    {
-      "marks": [
-        {
-          "type": "strong"
-        }
-      ],
-      "text": "const a = 1",
-      "type": "text"
-    }
-  ]
-}
-```
-
-```adf:codeBlock
-{
-  "content": [
-    {
-      "text": "a",
-      "type": "text"
-    },
-    {
-      "type": "hardBreak"
-    }
-  ]
-}
-```

corpus/round-trip/opaque-carry/unknown-block.md

@@ -1,21 +1,23 @@
-```adf:blockCard
+```carry
 {
   "attrs": {
     "url": "https://example.com/roadmap"
-  }
+  },
+  "type": "blockCard"
 }
 ```
 
 !adf:panel info
 The card below has no spelling yet.
 
-```adf:embedCard
+```carry
 {
   "attrs": {
     "layout": "wide",
     "url": "https://example.com/board",
     "width": 100
-  }
+  },
+  "type": "embedCard"
 }
 ```
 !adf:/panel

corpus/round-trip/opaque-carry/unknown-type-spelling.json

@@ -1,21 +0,0 @@
-{
-  "content": [
-    {
-      "attrs": {
-        "url": "https://example.com/"
-      },
-      "type": "has`tick"
-    },
-    {
-      "type": ""
-    },
-    {
-      "type": " padded"
-    },
-    {
-      "type": "two words"
-    }
-  ],
-  "type": "doc",
-  "version": 1
-}

corpus/round-trip/opaque-carry/unknown-type-spelling.md

@@ -1,24 +0,0 @@
-```adf:
-{
-  "attrs": {
-    "url": "https://example.com/"
-  },
-  "type": "has`tick"
-}
-```
-
-```adf:
-{
-  "type": ""
-}
-```
-
-```adf:
-{
-  "type": " padded"
-}
-```
-
-```adf:two words
-{}
-```

docs/decisions.md

@@ -1,668 +0,0 @@
-# Decisions
-
-## Plain markdown is a flavour of the grammar
-
-2026-09-27, the maintainer. Goal 2. Valid while the plain flavour's spellings are ones the markdown
-grammar can read and write.
-
-The lossy pair is the plain flavour: the markdown grammar's reader and writer with the flavour set,
-its spellings — alerts, callouts, task markers, `==` — read and written there, so a marker line and
-a backslash reach them intact; what the flavour cannot spell reduces ADF→ADF ahead of the writer.
-
-## The round-trip is the product
-
-2026-08-23, real payloads 2026-09-15, the maintainer. Goal 1. Valid while a consumer saves back
-through the lossless pair.
-
-`markdownToAdf(adfToMarkdown(doc))` and `htmlToAdf(adfToHtml(doc))` must deep-equal `doc` — anything
-less silently destroys content an editor could not represent, in a document it did not author.
-When losslessness and readability conflict, losslessness wins. Round-trip equality is a property
-tested over a checked-in corpus (`corpus/README.md`), not a claim made in prose. Its real payloads
-are invented content written in Atlassian's editor on the maintainer's test site, so none is
-sanitized and a mention keeps the test user's real account id.
-
-## Markdown in is a canonical fixpoint
-
-2026-08-23, the maintainer. Goals 1 and 4. Valid while markdown input may be written by hand.
-
-The other direction is a canonical fixpoint, not byte-identity: human markdown normalizes, the way
-back yields the library's canonical spelling, and that spelling round-trips byte-identically —
-where there is a way back. CommonMark spells some things the flavour has no escape for — a
-paragraph opening with a code span whose backticks read back as a fence — so a parse succeeding
-does not imply a spellable document; `corpus/commonmark-spec/exceptions.json` names those.
-
-## Equality is deep
-
-2026-08-24, deep 2026-10-03, the maintainer. Goal 1. Valid while a pipeline or a bot can build a
-shape the editor would not.
-
-"Equals" is `assert.deepStrictEqual`: every key and value `doc` holds, two adjacent text nodes, an
-empty `attrs`, `content` or `marks` and `-0` included, with no normalization on either side.
-CommonMark's spelling stays wherever a document holds none of those shapes. The plain reader
-builds what is written, as `markdownToAdf` does. Only the plain writer is lossy: its reduction
-writes editor-normal ADF — adjacent text nodes of identical marks and no attributes merged, `-0`
-as `0`, and an empty `attrs`, `content` or `marks` the absent key.
-
-## `!adf:textBreak{}` parts text CommonMark would join
-
-2026-10-03, the maintainer. Goal 1. Valid while CommonMark reads adjacent text as one run.
-
-Two adjacent text nodes a reader would build back as one — neither carried, neither holding
-`attrs` or an empty key, their marks identical, attributes included — are parted by the reserved
-inline leaf `!adf:textBreak{}`, mirroring `!adf:listBreak`: it builds no node, and anywhere but
-between two such nodes, or given `[content]` or `{attrs}`, it is `unsupported-node-shape`. It sits
-inside every mark spelling the pair shares, `**Hello, !adf:textBreak{}world**`; a code span holds
-no directive, so it closes and reopens, `` `a`!adf:textBreak{}`b` ``. A carried node never joins
-its neighbour, so a carry needs no break. A mark run breaks on any difference in the mark, `attrs:
-{}` against no `attrs` included.
-
-## An empty key spells `empty`
-
-2026-10-03, a writer panel and the maintainer. Goals 1 and 5. Valid while no attribute value
-spells an empty object or array.
-
-An `attrs`, `content` or `marks` key holding an empty object or array is the reserved key with the
-bare value `empty` on every directive — block, inline node and mark: `{attrs=empty}`,
-`{content=empty}`, `{marks=empty}`. A writer panel chose the spelling, 5 of 7. A container
-spelling `content=empty` closes with no body, so an empty pair stays the node holding no content
-key; a leaf spells it too, `!adf:rule {content=empty}`. A node CommonMark spells takes its
-directive form to hold an empty key, and a text node holding one rides the inline carry, as does a
-node under an `em`, `strong`, `strike`, `code` or `link` mark whose `attrs` is empty, since none of
-those spellings holds attributes. Any other value of a reserved key is `unsupported-node-shape`,
-except on a block's `marks`, which reads it as the marks array in JSON.
-
-## `-0` is spelled `-0`
-
-2026-10-03, the maintainer. Goal 1. Valid while JSON's own serialization writes `-0` as `0`.
-
-Wherever the flavour writes a number or a JSON value — an attribute, a `json` value, the carry —
-`-0` is `-0`, which JSON's grammar reads back as `-0`. An `orderedList` whose `order` is `-0` takes
-the directive form, since no list marker spells the sign.
-
-## Empty markdown is a document of no blocks
-
-2026-10-03, a panel and the maintainer. Goals 1 and 5. Valid while ADF's schema requires
-`content` on `doc`.
-
-Markdown holding no block reads as `{ content: [], type: 'doc', version: 1 }`, the document
-`spec/adf-schema/full.json` requires. A document holding no `content` key is
-`!adf:doc {content=none}` standing alone as its only block, and a named error anywhere else. The
-writer panel split 4 for `none` and 3 for `absent`, and the maintainer chose `none`; all seven rejected a
-bare `!adf:doc`.
-
-## Unknown nodes ride the carry
-
-2026-08-23, extended to misplaced known nodes 2026-08-26 and to code block children 2026-10-03, the
-maintainer. Goal 1. Valid while ADF holds nodes, or node positions, this library does not spell.
-
-An unknown ADF node is carried opaquely — raw JSON rides a dedicated syntax in both formats and
-restores to a deep-equal node. The round-trip holds for documents newer than the library. So does
-a known node no section spells where it stands: a markdown serializer spells a node by type without
-checking its position, and refusing loses a document ADF itself keeps in an `unsupportedBlock`. A
-`codeBlock` holding a child no fence holds — anything but a text node carrying no marks, `attrs` or
-`content` — rides the carry whole.
-
-## The carry fence names the node type
-
-2026-10-03, the maintainer. Goals 1 and 5. Valid while a code fence's info string reads back
-verbatim.
-
-The block carry is a code fence whose info string `adf:<type>` names the node's type, its body the
-node's JSON without `type`: ```` ```adf:blockCard ````. A type no info string carries back — by the
-rule a code language follows — leaves the info string `adf:` and keeps `type` in the body. Every
-info string opening `adf:` is reserved, so a `codeBlock` whose language opens so takes the
-`language` attribute, and `carry` is an ordinary language. A body holding `type` under a named
-type, or an `adf:` fence whose type an info string carries, is `unsupported-node-shape`.
-
-## A code block is a fence per text node
-
-2026-10-03, the maintainer. Goal 1. Valid while ADF holds a code block's text in more than one
-node.
-
-A `codeBlock` holding several text nodes is the `!adf:codeBlock` container holding one fence per
-node, each fence's info string the language; its other attributes sit on the opener, and a
-language no info string carries stays the opener's `language` with bare fences. A `codeBlock`
-spelling `content=empty` has no fence to carry the language, so the opener does. Fences with
-differing info strings are `unsupported-node-shape` — ADF holds one language — and so is an empty
-fence beside another, since a text node holds text.
-
-## Foreign HTML sorts three ways
-
-2026-08-23, the sort 2026-09-20, the maintainer. Goals 1 and 4. Valid while ADF holds no node
-for a bare container, a comment or a script. Lands with `todo.md` item 6.
-
-Every foreign element `htmlToAdf` and `markdownToAdf` read sorts one of three ways, never a silent
-drop of content:
-
-- A container around document content that ADF has no node for unwraps to its children, its own
-  attributes dropped: `<div align="center">text</div>` keeps `text`, losing the alignment.
-- Content ADF cannot hold is an error result naming it. A comment is one: a person wrote those
-  words, and neither of Atlassian's schemas holds them — `annotation`'s `inlineComment` carries an
-  id, `placeholder` is the editor's own hint, `extension` names a vendor app.
-- What is not document content drops whole: `<script>` and `<style>`, their text with them.
-
-`<details><summary>Title</summary>…</details>` is an `expand` titled by its summary, a
-`nestedExpand` inside another; an empty one is refused, since `expand` requires content. A `style`
-attribute is not read at `0.2.0`: the `textColor` and `backgroundColor` it could reach cost more
-than they buy.
-`plainMarkdownToAdf` reads through `markdownToAdf`'s parser, so it takes the same set.
-
-## Names stay text
-
-2026-08-23, the maintainer. Goal 7. Valid while resolving a name to an id needs I/O.
-
-A bare `@name` or `:smile:` in typed text stays a text node. Only directives produce
-mention/emoji/media nodes; resolving names to ids is the consumer's job.
-
-## Directives under `!adf:`
-
-2026-08-23, prefixed `!adf:` 2026-09-16, the maintainer. Goals 4 and 5. Valid while prose does not
-write `!adf:`.
-
-Directives are 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.
-
-## CommonMark is a subset
-
-2026-08-23, the maintainer. Goal 4. Valid while prose rarely writes the shapes the carve-outs claim.
-
-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
-
-2026-08-23, the maintainer. Goal 5. Valid while a pipe table holds only one header row and inline
-cells.
-
-One header row plus plain inline cells → pipe table; anything richer → directive form.
-
-## Links
-
-2026-09-13, nesting 2026-09-17, the maintainer. Goals 1 and 5. Valid while CommonMark's link
-syntax is what readers edit.
-
-`[text](url "title")`, or `<url>` for a bare autolink-shaped text, wherever CommonMark spells the
-mark; `!adf:link[text]{attrs}` where it does not — an attribute CommonMark cannot hold, an `href` or
-`title` no canonical escape spells, a paragraph opening whose CommonMark spelling would read as a
-link reference definition — and a directive link CommonMark could spell is refused. No link wraps a
-link — the bracket form goes literal, the directive form refused — which is CommonMark's prose
-where its reference implementation nests one `<a>` in another.
-
-## Ids stay site-local
-
-2026-08-23, the maintainer. Goal 1. Valid while ADF ids are minted per site.
-
-Identity-bearing nodes carry their ids in attributes; a document is only portable within its site —
-accepted.
-
-## Plain task ids come from position
-
-2026-09-26, spelling 2026-09-29, the maintainer. Goals 6 and 7. Valid while a site rejects a task
-node with no `localId`.
-
-`plainMarkdownToAdf` gives each `taskList`, `taskItem` and `blockTaskItem` lacking one a `localId`
-in the editor's UUID v4 shape, hashed from the whole markdown and the node's order among those it
-mints, skipping any id the document holds: the same markdown reads to the same ids every run,
-different markdown to different ids. The same markdown pasted twice into one document repeats its
-ids: determinism wins over that case. A node the carry restores stays deep-equal (§Unknown nodes ride the carry): its
-ids are only skipped.
-
-## A callout title keeps its link targets
-
-2026-09-29, the maintainer. Goals 5 and 6. Valid while an expand's `title` is a string.
-
-`plainMarkdownToAdf` writes a link in a folded callout's title as its text and its target in
-parentheses: `> [!faq]- See [x](http://y)` reads to the title `See x (http://y)`. A link whose text
-is its target, with or without `mailto:`, keeps its text alone: `<http://y>` titles `http://y`,
-`<a@b.c>` `a@b.c` — three persona readers agreeing, 2026-09-30.
-
-## The plain flavour's spellings
-
-2026-09-14, panels 2026-09-25 and 2026-09-29, the maintainer. Goals 5 and 6. Valid while GitHub's
-renderer is the one the audience's markdown is read in.
-
-README §Plain markdown's rows come 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. Reader panels settled `error` as an error panel, the `==` bounds
-(3 of 3) and a Han, Hangul, kana, Thai, Lao, Khmer or Myanmar character on either side bounding a
-delimiter, so `は==日本語==で` (3 of 3), `==한국어==에서만` and `iPhone==専用==` (6 of 7) highlight,
-the external image's two forms (6 of 7), a rule opening a list item dropping and the omission
-notes (3 of 3), and a list's numbering overflowing into bullets (3 of 3, 5 of 7).
-An omission note reads as the converter's, never as the author's.
-Reading takes other tools' spellings, since it reads their output and writes none of them.
-Rejected: `~sub~` and `^sup^` (`~2~` is a strike on GitHub, so `subsup` drops), 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.
-
-## The HTML dialect
-
-2026-08-23, the maintainer. Goals 5 and 7. Valid while HTML output is read by consumers styling it
-themselves.
-
-The HTML dialect mirrors the markdown flavour: semantic elements, stable `adf-*` classes, `data-*`
-for what HTML cannot express, text always escaped. No stylesheet ships.
-
-## No runtime dependencies
-
-2026-08-23, the maintainer. Goal 7. Valid while ~20 lines of own code, or a vendored table, do each
-job a dependency would.
-
-`dependencies` is empty. A runtime dependency enters only through an entry here stating why ~20
-lines of own code cannot do the job, who maintains it, and what auditing it costs. So the CommonMark
-and HTML parsers are written in this repo.
-
-## Standards ship as data
-
-2026-08-30, the CommonMark suite 2026-09-05 and ADF's schemas 2026-09-13, the maintainer. Goals 1,
-4 and 7. Valid while each table is fixed data a dependency would only wrap.
-
-A table a standard fixes is data rather than a dependency: HTML5's 2125 semicolon-terminated
-character references ship packed in their own module, so entity decoding is complete without one.
-The CommonMark spec suite is the same shape of 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.
-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.
-
-## fast-check
-
-2026-09-14, the maintainer. Goal 1. Valid while a failing generated document needs shrinking by
-hand otherwise.
-
-`fast-check` earns its place as a devDependency shrinking a failing generated document to the
-nodes that break it.
-
-## Any ES2022 engine
-
-2026-09-01, the maintainer. Goal 7. Valid while ES2022 is the floor browsers and servers share.
-
-The library runs on any ES2022 engine, not only Node — a browser as readily as a server. The
-shipped source is ECMAScript and nothing else: no host import, no host global, no DOM.
-`tsconfig.build.json` is that gate, typechecking and emitting the shipped files alone, so
-`node:fs`, `process` and an ES2024 method are compile errors here rather than a consumer's crash
-there. The standard is the line, never an engine list: one implementing it in part — Hermes is the
-live doubt, on the Unicode property escapes emphasis matching leans on and on lookbehind — is out
-of scope rather than a bug. Node's test runner, the corpus reads and the build are the repo's own,
-never the library's, and `engines.node` states the floor the shipped JavaScript needs — `>=18` —
-never the higher one those repo-only tools want.
-
-## ESM only
-
-2026-08-23, the maintainer. Goal 7. Valid while the audience's toolchains all import ES modules.
-
-No CommonJS build, no dual-package hazard.
-
-## One built entrypoint
-
-2026-08-23, the maintainer. Goal 7. Valid while Node refuses to type-strip under `node_modules`.
-
-Built JavaScript, `.d.ts` beside it. Do not add a TypeScript-source entrypoint — Node refuses to
-type-strip under `node_modules` (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`), so it cannot serve
-an npm consumer.
-
-## Public on npm
-
-2026-08-23, the name 2026-09-01, the maintainer. Goals 2 and 7. Valid while the package's source
-stays public beside it.
-
-Published to public npm as `@larvit/adf-codec`. Public source: the Gitea repo goes public,
-LICENSE in place, before the first publish. A codec, since it converts both directions, and named
-for the hub rather than the formats around it.
-
-## The formats are API
-
-2026-08-23, strict input 2026-09-01, content models 2026-09-16, the maintainer. Goal 1.
-Valid while consumers store what the library emits.
-
-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. 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. Input reads the canonical directive
-spelling alone — spacing, key order, each value's spelling — since loosening it later is MINOR.
-
-The error surface is a contract too; `README.md` §The errors states it to the consumer, and the
-types in `src/result.ts` hold its shape.
-
-## The code list
-
-2026-08-25, the maintainer; dated below where a rule came later. Goal 1. Valid while a consumer
-switches on `code` with no `default`.
-
-- Adding, removing or renaming a code is breaking, so a new cause takes an existing code whose
-  name reads true of it in both directions; where none does and a plain name exists, a new code —
-  in any 0.x minor, and after 1.0 only in a MAJOR (2026-09-18).
-- A refusal whose cause is this library's own invariant rather than the input takes the existing
-  code nearest what the consumer sees — a document that does not convert is
-  `unsupported-node-shape` — since a code no input reaches is one no consumer can switch on
-  (2026-09-20).
-- 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 (`unspellable-link`, 2026-09-13). A cause the carry answers gets
-  no code: a mark no spelling writes rides the carry with its node.
-
-## Which code a cause takes
-
-2026-08-28, the maintainer; dated below where a rule came later. Goal 1. Valid while a consumer
-handles one cause alike whichever node, attribute or direction raised it.
-
-- A code names the cause; where one cause recurs across node types, across one mark's attributes
-  or across directions, one code covers them all and `path` and `message` say which —
-  `unsupported-nesting-depth` is the 500-level guard whichever direction hits it,
-  `unspellable-character` the text node and the code block alike. Where two codes stay 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 `!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. What the grammar itself refuses stays a
-  claim code, key order among it, and a leaf given a body is refused at its opener, as a container
-  missing its closer is (2026-09-16).
-- A directive whose name reads back to no node is `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 names the flavour reserves part on form: 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, `!adf:textBreak{}` anything but two text nodes a reader joins, `!adf:doc` standing beside
-  another block (2026-09-01, the text break and `doc` 2026-10-03).
-- A well-formed directive the node tables refuse — an attribute a node does not hold or spells
-  elsewhere, a value outside its kind or its canonical spelling, an argument, or a body of a shape
-  its content model does not take — is `unsupported-node-shape`, the emitter's code for the same
-  mismatch read the other way: one code across both directions for good, since the call site
-  knows which direction it called and parting them after `0.1.0` is MAJOR (2026-09-23).
-- A non-finite number takes two codes: `unsupported-node-shape` parsing, `not-an-adf-document`
-  emitting — no document holds one, so no round-trip crosses them (2026-09-23).
-
-## `message` and `path`
-
-2026-09-03, the path 2026-09-23, the maintainer. Goals 1 and 4. Valid while a person fixing the
-input reads `message`.
-
-- 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: `\!adf:` for a directive, block line and
-  inline alike, `\|` for every pipe row.
-- `not-an-adf-document` carries the document's own path throughout: seven of the guard's eight
-  branches read the document's own shape, and threading a path to the eighth — a malformed node
-  anywhere in the tree — wants the manual stack §Nothing recurses unbounded forces. The message
-  names the violation instead.
-
-## Publish on a version bump
-
-2026-08-23, converging 2026-09-03, the maintainer. Goal 7. Valid while CI on `main` holds the npm
-token.
-
-`package.json` version on `main` is the source of truth. CI on `main`: tests green and the version
-not yet on npm → publish and tag `vX.Y.Z`. No bump, no deploy. `publish.sh` is that job.
-
-The publish and the tag each check their own end state — the version on npm, the tag on the
-remote — so a run that dies between them converges on the next push
-to `main` rather than leaving npm ahead of the tags. An unanswered registry reads the same as an
-unpublished version, which npm's own duplicate rejection is what catches. The job rebuilds rather
-than taking the gate's `dist`: the lockfile is committed, the image is patch-pinned and `tsc` is
-deterministic, so the two builds agree, and promoting an artifact would make the release path
-depend on a store that the gate would then have to keep.
-
-## Docs describe the release being built
-
-2026-09-16, the maintainer. Goal 7. Valid while a bump on `main` publishes.
-
-Docs on `main` describe the release being built rather than the version npm holds, so they match it
-the moment the bump publishes; add no interim note marking the gap.
-
-## No schema validation
-
-2026-08-23, the mark refusal 2026-08-25, the maintainer. Goal 1. Valid while the site a document
-is saved to validates it.
-
-No ADF schema validation or exported validator. A refusal that keeps the round-trip is not schema
-validation, so the one a spelled node carrying the same mark type twice earns stays, and input
-nesting a spelling inside its own kind (`*(*a*)*`) names that mark once.
-
-## The gate runs on Deno and Bun
-
-2026-09-01, Deno's reason 2026-09-28, the maintainer. Goals 3 and 7. Valid while the library claims
-any ES2022 engine.
-
-The gate runs the suite under Deno and Bun as well as Node. Bun runs JavaScriptCore, the one engine
-of the three that is not V8, where the Unicode property escapes emphasis matching leans on can
-disagree. Deno shares Node's V8 and stays to prove the library runs there too, catching what the
-two runtimes leave undocumented. Both refuse a run matching no test, so Node's is the only
-vacuous-green guard, and `AGENTS.md` §3's `node:` shims rule is the price of proving those engines
-over the corpus rather than over a smoke import.
-
-## The gate installs the tarball
-
-2026-09-03, the maintainer. Goal 7. Valid while consumers install the packed package.
-
-The gate packs the build and installs the tarball under `package-tests/`, so `files`, `exports`
-and `types` are proved on the artifact that ships rather than on the source tree a self-reference
-would resolve against. `consumer.ts` typechecks the emitted `.d.ts` from outside
-`tsconfig.build.json` — declaration emit leaves the `.ts` specifiers
-`rewriteRelativeImportExtensions` rewrites in the JavaScript, and this is what says a consumer's
-resolver maps them, under `NodeNext` alone; a `.d.ts` reader that is not `tsc` stays unproven.
-`node-floor.js` round-trips the installed package under a Node pinned to `engines.node`'s floor.
-
-## Firefox reads the build
-
-2026-09-04, the maintainer. Goal 7. Valid while the library claims a browser and no other leg runs
-SpiderMonkey.
-
-A headless Firefox loads `dist/index.js` 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 the browser half of §Any ES2022 engine and the only SpiderMonkey there is — the gate's
-other 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. The leg re-checks
-the conversions and nothing else — each fixture's emitted markdown, its parsed document, its error
-code — leaving the corpus's pairing, uniqueness, source positions and byte-level equality to the
-Node suite that owns them. `selenium/standalone-firefox` runs it over the smaller
-`instrumentisto/geckodriver`: the leg is worth a current SpiderMonkey, and that image fell four
-Firefox majors behind.
-
-## The coverage floors
-
-2026-08-24, the maintainer. Goal 1. Valid while `noUncheckedIndexedAccess` and ADF's optional keys
-force guards with a half no valid document reaches.
-
-The floors live in the `test` script, so `npm test` and the gate are one path: 100% of lines and
-functions, and a branch floor that only ever moves upward. It sits below 100 because the guards
-`noUncheckedIndexedAccess` and ADF's optional keys force — `?? []`, `?? {}`, `?.`, an index
-compared against `undefined` — have a half no valid document reaches.
-
-## The size ratchet
-
-2026-09-20, the maintainer. KISS, a technical principle. Valid while no measure picks out what
-readers find hard better than a function's length.
-
-`.oxlintrc.json`'s single rule, over the files `tsconfig.build.json` builds, is a per-function line
-ceiling, set at that set's worst and moving only downward. It covers the built files alone, since
-one ceiling over the tests too would have to be their worst, loosening the guard over the shipped
-code. It guards against drift and never drives a refactor, so no cyclomatic rule and no second lint
-rule join it: neither measure picked out what nine readers found hard (the comprehension panel,
-2026-09-20). `oxlint` measures it since TypeScript 7 is a native compiler publishing no in-process
-parser, only the `unstable/` AST surface an out-of-process handshake reaches. Three switches guard
-a silent green: `IIFEs: true`, since oxlint exempts an IIFE otherwise; an explicit `-c`, so a
-config gone missing fails the leg instead of falling back to oxlint's own defaults; and
-`--deny-warnings`, since a rule from a category this config never names arrives as a warning it
-exits 0 on.
-
-## Properties on a fixed seed
-
-2026-09-14, the maintainer. Goal 1. Valid while a red gate must reproduce.
-
-Beside the corpus, properties run over documents generated from the node tables and over generated
-markdown, on a fixed seed in the gate; a counterexample found becomes a round-trip fixture.
-
-## The CommonMark suite checks three ways
-
-2026-08-27, the maintainer. Goals 1 and 3. Valid while the suite's answers are HTML ADF cannot be
-compared against.
-
-Each example is a named error or markdown that parses and emits to itself byte for byte; its
-reference HTML's text, tags stripped and entities decoded, equals the parsed document's; and its
-elements count the marks and nodes they map to. The fixpoint alone passes a parser returning the
-empty document, the text alone one dropping every emphasis. An exception is the maintainer's to
-add, and valid CommonMark parsing to a document `adfToMarkdown` refuses where a spelling could exist
-is a bug to fix, never an exception.
-
-## The flavour spec is read as a source
-
-2026-09-01, the maintainer. Goal 1. Valid while `spec/flavour.md` restates the node tables in
-prose.
-
-`spec/flavour.md` is read as a source, so the node tables cannot drift from the prose they copy:
-its node and mark bullets must equal the tables in `adf/`. It guards the attributes alone: nodes
-that differ in content model share a bullet, and the argument attribute is spelled outside the
-bullet's attribute list, so both answer to the round-trip corpus and to nothing else where a node
-has no fixture.
-
-## The node tables answer to Atlassian's schema
-
-2026-09-13, the maintainer. Goal 1. Valid while a site's editor writes what Atlassian's schema
-holds.
-
-For every node and mark the tables spell, the attribute names and kinds equal what `full.json` and
-`stage-0.json` (§Standards ship as data) 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.
-
-## Nothing recurses unbounded
-
-2026-08-25, the directive form's count 2026-09-18, the maintainer. Goal 1. Valid while an engine's
-stack overflows near 2000 frames.
-
-The guards walk iteratively, and blocks, marks and JSON values — an attribute's and a carried
-node's alike — are all held to 500 levels (`largestNesting`), so a deep document is a `Result`
-rather than the stack overflow that waits near 2000. An attribute is counted from its value; a
-spelling that nests it deeper — the block directive's `marks`, the carry — refuses in its own
-format, as its parser does. A list giving way to the directive form refuses at zero headroom rather
-than walking again; counting every list twice halved the list limit, counting the directive form
-once doubled the parser's frames per level.
-
-## Nothing spreads an unbounded array
-
-2026-09-18, the maintainer. Goal 1. Valid while engines cap a call's arguments.
-
-Nothing spreads an unbounded array into a call — a node's siblings, a code block's held lines, a
-mark run's segments: the argument list caps near 125k and throws a `RangeError` where a `Result` is
-owed. A walk pushes one at a time. A literal spread (`[...value]`) is not the same thing and is
-fine.
-
-## A retry loop checks its own termination
-
-2026-09-20, the maintainer. Goal 1. Valid while a fallback can fail to spell what it is handed.
-
-A loop retrying an input until a fallback spells it refuses the pass taking no fallback, so its
-termination is the loop's own check.
-
-## Readers scan by index
-
-2026-08-30, the kept scan 2026-09-18, the maintainer. Goal 8. Valid while the pipeline persona
-feeds documents nobody typed.
-
-A reader takes the text and an index — a sticky regex whose `lastIndex` the caller sets on the line
-before it reads, `indexOf` — never a fresh slice per character, and a per-character walk hoists the
-scan that does not vary with the character: a megabyte through a quadratic walk is a minute rather
-than a millisecond. A scan may keep what it read for a later walk of the same text, and the
-fallback where it kept nothing must be the same reader over the same text at the same index, so the
-two cannot disagree — which is what makes the kept value a memo rather than a second spelling.
-
-## The spelling memo
-
-2026-09-19, the maintainer. Goal 8. Valid while the `commonMarkSpelling` ask spells a node once
-per level above it otherwise.
-
-The parse and the plain reduction keep each node's readable spelling in a memo, so the
-`commonMarkSpelling` ask stops spelling a node once per level above it. `text` and `spelling` carry
-no depth and `headroom` is affine in it, so a read at or above the depth that filled the entry
-rebases; a read below re-spells, because a hit skips the depth guards the walk it replaces runs and
-an ordered list past the marker cap gives way, spending two emitter levels where the parser spent
-one. Only what succeeded is kept, so no path minted at another position is ever read.
-
-## Cost fixes are measured, never timed
-
-2026-09-18, the maintainer and the stability-reviewer. Goal 8. Valid while Goal 8 promises growth
-rather than a figure.
-
-A cost fix that changes no behaviour lands on the suite staying green with no fixture output
-changed, and a before-and-after figure in its PR; the gate times nothing. Measured and kept:
-`adfDocumentFault`'s shape and depth walks stay two — the parting gives depth its own code — at
-52 ms for a 9 MB document the emit takes 314 ms over; and `continuesContainer`'s re-scan per item
-level stays, linear in the lines and bounded in depth by the 500-level guard.
-
-## Only the hard break holds a raw newline
-
-2026-08-26, the maintainer. Goal 1. Valid while the whitespace carry finds a line edge by its raw
-newline.
-
-Only the hard break's inline segment holds a raw newline — every other spelling escapes one or
-refuses it — which is how the whitespace carry finds a line edge.
-
-## Emphasis follows CommonMark's matching
-
-2026-08-27, the maintainer. Goals 1 and 3. Valid while CommonMark's emphasis rules are the
-reader's.
-
-Emphasis is spelled against CommonMark's matching, never flanking alone: a delimiter run in text
-escapes wherever CommonMark could open or close with it, leaving the emitter's own delimiters the
-only ones in play, and a pair that matching hands to another delimiter rides the carry instead.
-
-## Readable spellings take the `try` prefix
-
-2026-09-21, the maintainer. Goals 1 and 5. Valid while a readable spelling's refusal would cost a
-document the general form spells.
-
-A readable spelling tried ahead of a general one takes the `try` prefix and fails only where the
-general form fails on the same node: refusing there refuses a document the general form spells, so a
-refusal the general form does not share belongs in the general form or nowhere. A readable spelling
-that must spell its subtree before it can give way — the list, whose thematic-break first line and
-blank lines exist only spelled — hands that one walk to the general form instead: giving way after
-the walk walks again at every level, doubling per level.
-
-## The attribute vocabulary is ADF's
-
-2026-08-27, the maintainer. Goal 2. Valid while every format spells the same ADF attributes.
-
-`adf/` walks the attribute vocabulary and narrows each value to its kind, and a format spells the
-narrowed value. A spelling that re-checks the type is the check's second copy. Reading a spelling
-back is the format's own: the reader sits beside the spelling it inverts, so
-decode-respell-compare cannot drift, and each format writes its own — canonical JSON for a number
-is the markdown flavour's choice, not ADF's.
-
-## The source parts by ADF and format
-
-2026-08-27, placement 2026-09-18, `adf/`'s bar 2026-09-21, the maintainer. Goal 2. Valid while
-each format has a reader and a writer through ADF.
-
-`src/adf/` holds ADF's own knowledge, imports no format, and is where a construct both formats read
-lives: the question is answered in ADF's vocabulary — a node type, an attribute kind, a content
-model — and no delimiter, element name or escape reaches it. A helper that cannot answer that way
-is two constructs, the ADF question there and the spelling in each format, the seam
-`markAttributes` and `markSpellings` already draw; one that cannot be split is a gap to ask.
-`markdown/` and `html/` are peers: neither imports the other, and no third directory sits between
-them. A primitive knowing neither ADF nor a format stays at `src/` root. A construct rises to
-`adf/` on its second consumer, not in anticipation of one. A directory follows a split
-`spec/flavour.md` draws, and a placement nothing here settles goes beside its only reader, or in
-what both read where there are two.
-
-Each format directory parts into `emit/` (ADF→format) and `parse/` (format→ADF), the rest of it
-holding what both directions read. A construct's reader lives there beside the regex the emitter
-escapes against, so the two cannot drift; a reader with no emit counterpart goes in `parse/`,
-unless it is part of a construct that side already holds — a grammar stays in one file rather than
-splitting across the seam. A rule both directions must answer alike — whether a list marker
-interrupts a paragraph — is one function there too, never a copy per direction, however
-conservative the copy would be. Where the rule is the emitter's own choice, input consults it
-rather than restating it, and that is the only import `parse/` takes from `emit/` —
-`commonMarkSpelling` and `openingLinkTakesDirective` — so no fixture the emitter writes can be
-refused, and a spelling the emitter refuses gives its own error rather than a second name for it.

package-tests/consumer.ts

@@ -1,13 +1,11 @@
-import { adfToMarkdown, adfToPlainMarkdown, isAdfDocument, markdownToAdf, plainMarkdownToAdf, type AdfDocument, type ConvertErrorCode, type ParseError, type Result } from '@larvit/adf-codec'
+import { adfToMarkdown, isAdfDocument, markdownToAdf, type AdfDocument, type ConvertErrorCode, type ParseError, type Result } from '@larvit/adf-codec'
 
 const document: AdfDocument = { content: [{ content: [{ text: 'x', type: 'text' }], type: 'paragraph' }], type: 'doc', version: 1 }
 
 const emitted: Result<string> = adfToMarkdown(document)
 const parsed: Result<AdfDocument, ParseError> = markdownToAdf('x\n')
-const plainEmitted: Result<string> = adfToPlainMarkdown(document)
-const plainParsed: Result<AdfDocument, ParseError> = plainMarkdownToAdf('x\n')
 const guarded: boolean = isAdfDocument(document)
 const code: ConvertErrorCode | undefined = emitted.ok ? undefined : emitted.error.code
 const line: number | undefined = parsed.ok ? undefined : parsed.error.position.line
 
-export const surface = { code, guarded, line, plainEmitted, plainParsed }
+export const surface = { code, guarded, line }

package.json

@@ -24,7 +24,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "size-ratchet": "oxlint --deny-warnings -c .oxlintrc.json src",
-    "test": "node --test --experimental-test-coverage --test-coverage-exclude=\"src/**/*.test.ts\" --test-coverage-exclude=src/conformance/property-harness.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": {

publish.sh

@@ -30,6 +30,7 @@ fi
 published=$(leg "ask npmjs for $name@$version ($node_image)" published_version "$name" "$version")
 tagged=$(leg "ask origin for v$version" git ls-remote --tags origin "v$version")
 
+# Both steps observe their own end state, so a partial run converges on the next push to main.
 if [ -z "$published" ]; then
   : "${NPM_TOKEN:?the publish needs NPM_TOKEN}"
   leg "install ($node_image)" in_image "$node_image" npm ci

spec/flavour.md

@@ -1,12 +1,12 @@
 # The markdown flavour
 
 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 `!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 (`docs/decisions.md` §The formats are API). Per-node syntaxes build on this
-grammar in the sections below.
+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 `!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.
 
 ## Canonical form
 
@@ -44,8 +44,7 @@ normalizes to it through the round-trip.
   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 an `!adf:paragraph` … `!adf:/paragraph` pair
-  holding nothing, and one whose `content` is an empty array the pair
-  `!adf:paragraph {content=empty}` … `!adf:/paragraph` (Attributes).
+  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
@@ -68,26 +67,22 @@ normalizes to it through the round-trip.
   matching below, which is what lets the emitter decide its own pairings.
 - Blocks separated by one blank line at document level, inside a blockquote and between CommonMark
   blocks; inside a directive container a pair holding a directive block takes none. No trailing
-  whitespace outside a code block's content, single trailing newline. A document whose `content` is
-  an empty array is the empty string, and markdown holding no block reads back to it; a document
-  holding no `content` key is the leaf `!adf:doc {content=none}` as its only block, which is a
-  named error anywhere else or spelled any other way.
+  whitespace outside a code
+  block's
+  content, single trailing newline; a document with no blocks is the empty string.
 
 ## Directives
 
 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 (`docs/decisions.md`
-§The formats are API). 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. Four reserved names read back to no node: `carry` for the inline
-opaque carry, `listBreak` for the leaf that parts two adjacent lists and `doc` for a document
-holding no `content` key (Canonical form), and `textBreak` for the leaf that parts two text nodes
-(Inline nodes). Every fence info string opening `adf:` is reserved for the block carry (The opaque
-carry).
+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).
 
 **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
@@ -128,7 +123,7 @@ Which of the two a node takes is its content model, never the spelling: a model
 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 (`docs/decisions.md` §The formats are API).
+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
@@ -148,13 +143,6 @@ ends the name (`!adf:hardBreak{}`). Input reads that spelling alone: keys out of
 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.
-`attrs`, `content` and `marks` are reserved keys on every directive — block, inline node and mark —
-whose bare value `empty` spells the node's or mark's key holding an empty object or array:
-`!adf:underline[a]{attrs=empty}`, `!adf:date{content=empty}`, `!adf:hardBreak{marks=empty}`. A
-container spelling `content=empty` closes with no body; `attrs=empty` stands beside no other
-attribute, argument or content slot; and an inline node spelling `marks=empty` stands inside no
-mark spelling. Any other value of a reserved key is a named error, except on a block's `marks`
-(Block nodes).
 
 **Escaping**: the emitter backslash-escapes whatever literal text would otherwise parse as
 directive syntax — every literal `!adf:`, `]` inside content, a bracket a link's destination and
@@ -166,57 +154,51 @@ outside code spans and code blocks, `\!adf:` in input yields the literal text.
 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 the round-trip refuses.
+fallback — a typo that reparses as prose is the silent loss §2 refuses.
 
-## The opaque carry
+## The opaque carry (AGENTS.md §3)
 
-A node no section spells where it stands (`docs/decisions.md` §Unknown nodes ride the carry) — an
-unknown type, or a known one whose spelling belongs to the other position — rides as its raw JSON
-and restores to a deep-equal node. A carry may hold a node the emitter spells natively: it restores
-unreinterpreted, and the next emit spells it canonically (`docs/decisions.md` §The round-trip is the
-product). Block and inline positions canonicalize differently, each fitting where it sits:
+A node no section spells where it stands — an unknown type, or a known one whose spelling belongs
+to the other position — rides as its raw JSON and restores to a deep-equal node. A carry may hold
+a node the emitter spells natively: it restores unreinterpreted, and the next emit spells it
+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:` and the node's type, body = the
-  node's JSON without its `type` — two-space indent, object keys sorted: ```` ```adf:blockCard ````.
-  A type no info string carries back, by the rule a `codeBlock`'s language follows, leaves the info
-  string `adf:` and keeps `type` in the body. A body holding `type` under a named type, or an
-  `adf:` fence whose type an info string carries, is a named error.
+- **Block position**: a fenced code block with info string `carry`, body = the node's JSON —
+  two-space indent, object keys sorted.
 - **Inline position**: `!adf:carry{json="…"}` — compact serialization (keys sorted, no whitespace),
   JSON-string-escaped into the attribute.
 
-Every info string opening `adf:` is reserved: a genuine `codeBlock` whose `language` opens so 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 position `!adf:carry` is a named error — the carry's block form
-is the fence.
+stays absolute.
+In block-directive position `!adf:carry` is a named error — the carry's block form is the fence.
 
 ## Raw HTML in input
 
 CommonMark input may contain raw HTML. `markdownToAdf` routes each construct through the foreign
-HTML element mapping (`docs/decisions.md` §Foreign HTML sorts three ways; specified with the HTML
-dialect, `todo.md` item 6) — ADF has no raw-HTML node, so a construct without a mapping, comments
-and processing instructions included, is an error result naming it. The flavour never emits raw
-HTML.
+HTML element mapping (AGENTS.md §3; specified with the HTML dialect, todo.md milestone 6) — ADF
+has no raw-HTML node, so a construct without a mapping, comments and processing instructions
+included, is an error result naming it. The flavour never emits raw HTML.
 
 ## Block nodes
 
-The directive name is always the ADF node type. A container's body is the node's `content`; a leaf
-has none. Every directive parses in any position — `markdownToAdf` builds exactly what is written;
-validity against ADF's content models stays the author's business (`docs/decisions.md` §No schema
-validation). It parses only in the form the emitter picks, though: a directive spelling a node the
-emitter would have written as CommonMark is a named error.
+The directive name is always the ADF node type. A container's body is the node's `content`; a
+leaf has none. Every directive parses in any position — `markdownToAdf` builds exactly what is
+written; validity against ADF's content models stays the author's business (AGENTS.md §14). It
+parses only in the form the emitter picks, though: a directive spelling a node the emitter would
+have written as CommonMark is a named error.
 
 Each section lists attributes as `name (type)`. A parenthesized value set documents what real
 payloads hold; the type stays string and any value round-trips verbatim. Values map to attrs by
 type: strings verbatim, numbers and booleans in canonical JSON spelling — quoted where not bare
-(`width="33.33"`) — and `json` values as the inline carry's serialization (compact, keys sorted),
-quoted, `-0` spelled `-0`. `markdownToAdf` builds an `attrs`, `content` or `marks` key only where the
-markdown spells one, an empty one through its reserved key (Attributes), so a document reads back
-deep-equal (`docs/decisions.md` §Equality is deep). A node CommonMark spells takes the directive
-form to hold an empty key.
+(`width="33.33"`) — and `json` values as the inline carry's serialization (compact, keys
+sorted), quoted. `markdownToAdf` emits `attrs`, `content` and `marks` keys only when non-empty;
+editor-normal ADF reads an empty attrs object, marks array or content array as the absent key
+(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, `marks=empty` where it is empty:
-`!adf: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 an empty pair is a node holding none.
 
@@ -232,17 +214,14 @@ cannot — `localId` (string) on any of them, marks, and the values below — ta
 form.
 
 - `blockquote`, `bulletList`, `listItem` — containers, block body. Attributes: `localId` (string).
-- `codeBlock` — container, body one fenced code block per text node, each fence's info string the
-  language and its content the node's text; a node holding no `content` key is one empty fence.
-  Attributes: `hideLineNumbers` (boolean), `language` (string), `localId` (string), `uniqueId`
-  (string), `wrap` (boolean). A language no info string carries back — empty, opening the reserved
-  `adf:`, or holding a backtick, a backslash, a control character, edge whitespace or an entity
-  reference — rides the `language` attribute instead and the fences carry no info string, and so
-  does a language beside `content=empty`, which has no fence; writing it in the slot that rule
-  leaves empty, or in both, is a named error, and so are fences whose info strings differ and an
-  empty fence beside another. Each fence is an ordinary code block, and its info string decodes
-  escapes and entity references as any other does. A node holding a child no fence holds — any but
-  a text node carrying no marks, `attrs` or `content` — rides the block carry.
+- `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 `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
+  other does.
 - `heading` — container, inline body. Attributes: `level` (number), `localId` (string). `level` is
   the `#` count, so a heading carrying none, or one that is no whole number from 1 to 6, has no
   CommonMark spelling.
@@ -321,10 +300,10 @@ other text, or one carrying a title, is a named error: `mediaInline` carries a m
 ### Tables
 
 One header row plus plain inline cells is a pipe table; anything richer is the directive form
-(`docs/decisions.md` §Tables). Precisely: a table emits as a pipe table exactly when the `table`,
-every row and every cell carry no attrs and no marks, the first row is all `tableHeader` and the
-rest all `tableCell`, every row has the header's cell count, and every cell holds exactly one
-attr-less, mark-less paragraph — an empty cell holds one empty paragraph — with no `|` anywhere the
+(AGENTS.md §4). Precisely: a table emits as a pipe table exactly when the `table`, every row
+and every cell carry no attrs and no marks, the first row is all `tableHeader` and the rest all
+`tableCell`, every row has the header's cell count, and every cell holds exactly one attr-less,
+mark-less paragraph — an empty cell holds one empty paragraph — with no `|` anywhere the
 inline layer spells as syntax: a code span, an autolink, a link destination or title. A `|` there
 takes the directive form instead. A pipe table parses back to exactly that shape.
 
@@ -444,8 +423,9 @@ 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 text node carrying neither marks, attributes nor content 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,
+parsing to anything but one text node carrying neither marks, attributes nor content — 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).
@@ -469,30 +449,19 @@ Shipped !adf:emoji[🎉]{shortName=":tada:"} on !adf:date{timestamp=175608000000
 ```
 
 **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 `!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, which
-the spelled run joins on reading. 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.
+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
+`!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 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.
 
 ```
 !adf:text{text="  "}Two leading spaces held, and one text node split!adf:text{text="\n"}over two lines.
 ```
 
-**Adjacent text nodes.** CommonMark reads two adjacent text nodes back as one where neither is
-carried, neither holds `attrs` or an empty key, and their marks are identical, attributes included.
-The reserved leaf `!adf:textBreak{}` parts such a pair, inside every mark spelling the two share; a
-code span holds no directive, so it closes and reopens. It builds no node and reads only between
-two such nodes: elsewhere, or with `[content]` or `{attrs}`, it is a named error (`docs/decisions.md`
-§`!adf:textBreak{}` parts text CommonMark would join). A text node holding `attrs` or an empty key
-rides the inline carry.
-
-```
-Hello, !adf:textBreak{}world — **Hello, !adf:textBreak{}world** — `a`!adf:textBreak{}`b`
-```
-
 ## Marks
 
 An inline node's marks ride the spelling wrapped around them, never the block sections' reserved
@@ -519,21 +488,21 @@ the directive form, open to no literal reading, is a named error.
 
 A spelling adds its mark to every inline node it wraps, and nesting is the marks array in order,
 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 —
-`docs/decisions.md` §Equality is deep 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: `attrs: {}` differs from no `attrs`, and a directive spells it `{attrs=empty}`. A run
-breaks at every node the emitter carries, so no emitted carry sits inside a mark spelling.
+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
+node the emitter carries, so no emitted carry sits inside a mark spelling.
 
 An inline node whose marks no nesting spells — a mark type not listed here, an attrs key its
 spelling does not list, a value that is not the spelling's type, an attribute the spelling needs
-and the mark lacks, an empty `attrs` on a mark CommonMark spells, an order putting a code span outside another mark, `code` over anything but a
+and the mark lacks, an order putting a code span outside another mark, `code` over anything but a
 text node or over text holding a newline, or a spelling CommonMark's flanking rules cannot open or
 close where the run sits (`un**-real**istic`), or one CommonMark's matching pairs elsewhere — the
 intra-word `*` runs together with a neighbouring `**`, and the multiple-of-3 rule can leave the
 merged run's pairing to another delimiter — rides the inline carry whole. An opaque carry inside a
 mark spelling is a named error in input: the carry restores its node exactly, marks included
-(`docs/decisions.md` §Unknown nodes ride the carry).
+(AGENTS.md §3).
 
 ```
 !adf:textColor[**Overdue**]{color="#ae2e24"}, H!adf:subsup[2]{type=sub}O, !adf:underline[signed].

src/adf-property.test.ts

@@ -0,0 +1,23 @@
+import assert from 'node:assert/strict'
+import fc from 'fast-check'
+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

@@ -5,11 +5,11 @@ import { fileURLToPath } from 'node:url'
 import { readFileSync } from 'node:fs'
 import test from 'node:test'
 
-import type { AttributeKind, AttributeVocabulary } from '../adf/attribute-vocabulary.ts'
-import { blockArgument } from '../markdown/block-directive.ts'
-import { blockNodes } from '../adf/block-nodes.ts'
-import { inlineNodes } from '../adf/inline-nodes.ts'
-import { markAttributes } from '../adf/mark-attributes.ts'
+import type { AttributeKind, AttributeVocabulary } from './adf/attribute-vocabulary.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'
 
 type Held = Map<string, Set<AttributeKind>>
 type Properties = Map<string, SchemaObject[]>
@@ -21,7 +21,7 @@ const definitionReference = '#/definitions/'
 const gaps: string[] = []
 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 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', () => {
@@ -78,8 +78,8 @@ test("the ADF JSON Schemas hold no type the tables leave unspelled, the pinned c
 
 function spelled(): Spelled[] {
   return [
-    ...Object.entries(blockNodes).map(([type, model]) => spelledType(type, model.attributes, blockArgument(type))),
-    ...Object.entries(inlineNodes).map(([type, model]) => spelledType(type, model.attributes)),
+    ...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)),
   ]
 }

src/adf/block-directives.ts

@@ -1,6 +1,6 @@
 import type { AttributeVocabulary } from './attribute-vocabulary.ts'
 
-export type BlockNodeModel = {
+export type BlockDirective = {
   attributes: AttributeVocabulary
   contentModel: 'block' | 'code' | 'inline' | 'none'
 }
@@ -41,7 +41,7 @@ const mediaAttributes: AttributeVocabulary = {
 
 const syncBlockAttributes: AttributeVocabulary = { localId: 'string', resourceId: 'string' }
 
-export const blockNodes = {
+export const blockDirectives = {
   blockTaskItem: { attributes: localIdAttributes, contentModel: 'block' },
   blockquote: { attributes: localIdAttributes, contentModel: 'block' },
   bodiedExtension: { attributes: extensionAttributes, contentModel: 'block' },
@@ -80,14 +80,14 @@ export const blockNodes = {
   tableRow: { attributes: localIdAttributes, contentModel: 'block' },
   taskItem: { attributes: localIdAttributes, contentModel: 'inline' },
   taskList: { attributes: localIdAttributes, contentModel: 'block' },
-} satisfies Readonly<Record<string, BlockNodeModel>>
+} satisfies Readonly<Record<string, BlockDirective>>
 
-export type BlockType = keyof typeof blockNodes
+export type BlockType = keyof typeof blockDirectives
 
-export function blockNodeModel(type: string): BlockNodeModel | undefined {
-  return isBlockType(type) ? blockNodes[type] : undefined
+export function blockDirective(type: string): BlockDirective | undefined {
+  return isBlockType(type) ? blockDirectives[type] : undefined
 }
 
 function isBlockType(type: string): type is BlockType {
-  return Object.hasOwn(blockNodes, type)
+  return Object.hasOwn(blockDirectives, type)
 }

src/adf/document.test.ts

@@ -61,15 +61,16 @@ test('rejects a node whose shape ProseMirror JSON cannot hold', () => {
 })
 
 test('names the attribute nesting past the levels the parser reads one at, and still calls the value a document', () => {
-  const deeper = (key: string, type: string): string => `the ${key} attribute of ${type} nests deeper than the ${largestNesting} levels an attribute carries`
+  const deeper = (key: string, type: string, levels: number = largestNesting): string =>
+    `the ${key} attribute of ${type} nests deeper than the ${levels} levels an attribute carries`
   assert.equal(fault(withAttribute(nested(largestNesting))), 'accepted')
   assert.equal(fault(withAttribute(nested(largestNesting + 1))), deeper('a', 'paragraph'))
   assert.equal(faultCode(withAttribute(nested(largestNesting + 1))), 'unsupported-nesting-depth')
   assert.equal(isAdfDocument(withAttribute(nested(largestNesting + 1))), true)
   const marked = (levels: number): unknown => ({ content: [{ marks: [{ attrs: { a: nested(levels) }, type: 'link' }], text: 'x', type: 'text' }], type: 'doc', version: 1 })
-  assert.equal(fault(marked(largestNesting)), 'accepted')
-  assert.equal(fault(marked(largestNesting + 1)), deeper('a', 'link'))
-  assert.equal(isAdfDocument(marked(largestNesting + 1)), true)
+  assert.equal(fault(marked(largestNesting - 3)), 'accepted')
+  assert.equal(fault(marked(largestNesting - 2)), deeper('a', 'link', largestNesting - 3))
+  assert.equal(isAdfDocument(marked(largestNesting - 2)), true)
 })
 
 test('accepts the JSON values an attribute may hold', () => {

src/adf/document.ts

@@ -1,7 +1,6 @@
 import type { ConvertFault } from '../result.ts'
 import { isJsonValue, overNested, type JsonValue } from '../json-value.ts'
 import { largestNesting } from '../nesting.ts'
-import { serializeCanonicalJson } from '../canonical-json.ts'
 
 export type AdfAttributes = { [key: string]: JsonValue }
 
@@ -18,14 +17,15 @@ export type AdfNode = {
   type: string
 }
 
-export type EmptyKey = 'attrs' | 'content' | 'marks'
-
 export type AdfDocument = {
   content?: AdfNode[]
   type: 'doc'
   version: number
 }
 
+// A block directive spells the whole mark set as one JSON attribute, so a mark's value sits three levels inside it.
+const markAttributeNesting = largestNesting - 3
+
 const documentKeys = ['content', 'type', 'version']
 const markKeys = ['attrs', 'type']
 const nodeKeys = ['attrs', 'content', 'marks', 'text', 'type']
@@ -47,45 +47,15 @@ export function adfDocumentFault(value: unknown): ConvertFault | undefined {
   return nestingFault(content)
 }
 
-export function attributeNestingMessage(key: string, type: string): string {
-  return `the ${key} attribute of ${type} nests deeper than the ${largestNesting} levels an attribute carries`
+export function attributeNestingMessage(key: string, type: string, levels: number = largestNesting): string {
+  return `the ${key} attribute of ${type} nests deeper than the ${levels} levels an attribute carries`
 }
 
 export function carriesOnly(node: AdfNode, attributes: readonly string[]): boolean {
-  if (nodeMarks(node).length > 0 || node.text !== undefined || emptyKeys(node).length > 0) return false
+  if (nodeMarks(node).length > 0 || node.text !== undefined) return false
   return holdsOnly(nodeAttrs(node), attributes)
 }
 
-export function emptyKeys(held: { attrs?: AdfAttributes; content?: AdfNode[]; marks?: AdfMark[] }): EmptyKey[] {
-  const keys: EmptyKey[] = []
-  if (held.attrs !== undefined && Object.keys(held.attrs).length === 0) keys.push('attrs')
-  if (held.content?.length === 0) keys.push('content')
-  if (held.marks?.length === 0) keys.push('marks')
-  return keys
-}
-
-export function identicalMark(left: AdfMark, right: AdfMark): boolean {
-  return marksKey([left]) === marksKey([right])
-}
-
-export function identicalMarks(left: readonly AdfMark[], right: readonly AdfMark[]): boolean {
-  return marksKey(left) === marksKey(right)
-}
-
-// `joins` is the caller's: a reader joins what CommonMark reads as one, editor-normal ADF what the editor would.
-export function mergeAdjacentText(nodes: readonly AdfNode[], joins: (previous: AdfNode, node: AdfNode) => boolean): AdfNode[] {
-  const merged: AdfNode[] = []
-  for (const node of nodes) {
-    const previous = merged[merged.length - 1]
-    if (previous !== undefined && joins(previous, node)) {
-      merged[merged.length - 1] = { ...previous, text: `${previous.text ?? ''}${node.text ?? ''}` }
-      continue
-    }
-    merged.push(node)
-  }
-  return merged
-}
-
 // Depth is the walks' business, not the shape's: the guard waves a deep document through as blocks and marks do.
 export function isAdfDocument(value: unknown): value is AdfDocument {
   const fault = adfDocumentFault(value)
@@ -132,13 +102,6 @@ function isNodeArray(value: readonly unknown[]): value is readonly AdfNode[] {
   return true
 }
 
-function marksKey(marks: readonly AdfMark[]): string {
-  return serializeCanonicalJson(
-    marks.map((mark) => (mark.attrs === undefined ? [mark.type] : [mark.type, mark.attrs])),
-    'compact',
-  )
-}
-
 function nestingFault(nodes: readonly AdfNode[]): ConvertFault | undefined {
   const pending: AdfNode[] = [...nodes]
   while (pending.length > 0) {
@@ -153,15 +116,15 @@ function nestingFault(nodes: readonly AdfNode[]): ConvertFault | undefined {
 
 function marksFault(marks: readonly AdfMark[]): ConvertFault | undefined {
   for (const mark of marks) {
-    const fault = attributesFault(nodeAttrs(mark), mark.type)
+    const fault = attributesFault(nodeAttrs(mark), mark.type, markAttributeNesting)
     if (fault !== undefined) return fault
   }
   return undefined
 }
 
-function attributesFault(attrs: AdfAttributes, type: string): ConvertFault | undefined {
+function attributesFault(attrs: AdfAttributes, type: string, levels: number = largestNesting): ConvertFault | undefined {
   for (const [key, value] of Object.entries(attrs)) {
-    if (overNested(value)) return { code: 'unsupported-nesting-depth', message: attributeNestingMessage(key, type) }
+    if (overNested(value, levels)) return { code: 'unsupported-nesting-depth', message: attributeNestingMessage(key, type, levels) }
   }
   return undefined
 }

src/adf/editor-normal.ts

@@ -1,25 +1,34 @@
 import type { AdfAttributes, AdfDocument, AdfMark, AdfNode } from './document.ts'
 import type { JsonValue } from '../json-value.ts'
-import { identicalMark, identicalMarks, mergeAdjacentText, nodeAttrs, nodeContent, nodeMarks } from './document.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(left: AdfMark, right: AdfMark): boolean {
-  return identicalMark(normalMark(left), normalMark(right))
+export function sameMark(candidate: AdfMark, mark: AdfMark): boolean {
+  return markKey(candidate) === markKey(mark)
 }
 
-export function joinsNormally(previous: AdfNode, node: AdfNode): boolean {
-  if (!mergesText(previous) || !mergesText(node)) return false
-  return identicalMarks(nodeMarks(previous).map(normalMark), nodeMarks(node).map(normalMark))
+export function mergeAdjacentText(nodes: readonly AdfNode[]): AdfNode[] {
+  const merged: AdfNode[] = []
+  for (const node of nodes) {
+    const previous = merged[merged.length - 1]
+    if (previous !== undefined && mergesText(previous) && mergesText(node) && sameMarks(previous, node)) {
+      merged[merged.length - 1] = { ...previous, text: `${previous.text ?? ''}${node.text ?? ''}` }
+      continue
+    }
+    merged.push(node)
+  }
+  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), joinsNormally)
+    const content = mergeAdjacentText(nodeContent(entry.source))
     if (content.length === 0) continue
     entry.holder.content = content.map((source) => {
       const holder = normalNode(source)
@@ -67,3 +76,15 @@ function normalValue(value: JsonValue, pending: JsonContainer[]): JsonValue {
 function mergesText(node: AdfNode): boolean {
   return node.type === 'text' && Object.keys(nodeAttrs(node)).length === 0
 }
+
+function sameMarks(previous: AdfNode, node: AdfNode): boolean {
+  return marksKey(nodeMarks(previous)) === marksKey(nodeMarks(node))
+}
+
+function marksKey(marks: readonly AdfMark[]): string {
+  return marks.map(markKey).join('\n')
+}
+
+function markKey(mark: AdfMark): string {
+  return `${mark.type} ${serializeCanonicalJson(nodeAttrs(mark), 'compact')}`
+}

src/adf/inline-directives.ts

@@ -1,11 +1,11 @@
 import type { AttributeVocabulary } from './attribute-vocabulary.ts'
 
-export type InlineNodeModel = {
+export type InlineDirective = {
   attributes: AttributeVocabulary
   textAttribute?: string
 }
 
-export const inlineNodes: Readonly<Record<string, InlineNodeModel>> = {
+export const inlineDirectives: Readonly<Record<string, InlineDirective>> = {
   date: { attributes: { localId: 'string', timestamp: 'string' } },
   emoji: { attributes: { id: 'string', localId: 'string', shortName: 'string', text: 'string' }, textAttribute: 'text' },
   hardBreak: { attributes: { localId: 'string', text: 'string' } },
@@ -27,6 +27,6 @@ export const inlineNodes: Readonly<Record<string, InlineNodeModel>> = {
   status: { attributes: { color: 'string', localId: 'string', style: 'string', text: 'string' }, textAttribute: 'text' },
 }
 
-export function inlineNodeModel(type: string): InlineNodeModel | undefined {
-  return Object.hasOwn(inlineNodes, type) ? inlineNodes[type] : undefined
+export function inlineDirective(type: string): InlineDirective | undefined {
+  return Object.hasOwn(inlineDirectives, type) ? inlineDirectives[type] : undefined
 }

src/canonical-json.ts

@@ -18,7 +18,7 @@ export function serializeCanonicalJson(value: JsonValue, spelling: JsonSpelling)
     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(Object.is(held, -0) ? '-0' : JSON.stringify(held))
+    else text.push(JSON.stringify(held))
   }
   return text.join('')
 }

src/commonmark-spec.test.ts

@@ -5,11 +5,11 @@ import { fileURLToPath } from 'node:url'
 import { readFileSync } from 'node:fs'
 import test from 'node:test'
 
-import type { AdfDocument, AdfNode } from '../adf/document.ts'
-import { adfToMarkdown } from '../markdown/emit/adf-to-markdown.ts'
-import { markdownToAdf } from '../markdown/parse/markdown-to-adf.ts'
+import type { AdfDocument, AdfNode } from './adf/document.ts'
+import { adfToMarkdown } from './markdown/emit/adf-to-markdown.ts'
+import { markdownToAdf } from './markdown/parse/markdown-to-adf.ts'
 
-const root = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'corpus', 'commonmark-spec')
+const root = join(dirname(fileURLToPath(import.meta.url)), '..', 'corpus', 'commonmark-spec')
 const checks = ['count', 'fixpoint', 'text'] as const
 
 type Check = (typeof checks)[number]
@@ -91,7 +91,7 @@ test('the refusal list is unique per example and names real examples', () => {
   for (const example of exampleToRefusal.keys()) assert.ok(spec.some((entry) => entry.example === example), `refusal ${example} names no example in the suite`)
 })
 
-// A mark is counted once per text node it touches (docs/decisions.md §No schema validation).
+// A mark is counted once per text node it touches (AGENTS.md §14).
 const countKeys = ['a', 'blockquote', 'br', 'code', 'em', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'hr', 'img', 'li', 'ol', 'pre', 'strong', 'ul']
 const nodeElement: Record<string, string> = {
   blockquote: 'blockquote',

src/conformance/adf-property.test.ts

@@ -1,63 +0,0 @@
-import assert from 'node:assert/strict'
-import fc from 'fast-check'
-import test from 'node:test'
-
-import type { AdfNode } from '../adf/document.ts'
-import { adfDocument, propertyRuns, propertyTimeout } from './property-harness.ts'
-import { adfToMarkdown } from '../markdown/emit/adf-to-markdown.ts'
-import { adfToPlainMarkdown, reduceToPlain } from '../markdown/emit/plain-reduction.ts'
-import { directivePrefix } from '../markdown/directive-syntax.ts'
-import { markdownToAdf, plainMarkdownToAdf } from '../markdown/parse/markdown-to-adf.ts'
-
-const gateRuns = 1600
-const renamedPrefix = '!adg:'
-
-// Renaming the prefix changes what markdown reads only where a directive was read.
-function readsNoDirective(markdown: string): boolean {
-  const read = markdownToAdf(markdown)
-  const renamed = markdownToAdf(markdown.replaceAll(directivePrefix, renamedPrefix))
-  return read.ok && renamed.ok && JSON.stringify(read.value).replaceAll(directivePrefix, renamedPrefix) === JSON.stringify(renamed.value)
-}
-
-// Each block's text, an expand's title and an image's alt and url, in document order: what the plain pair keeps.
-function shownText(nodes: readonly AdfNode[]): string[] {
-  const shown: string[] = []
-  for (const node of nodes) {
-    const attrs = node.attrs ?? {}
-    if ((node.type === 'expand' || node.type === 'nestedExpand') && typeof attrs['title'] === 'string') shown.push(attrs['title'])
-    if (node.type === 'media') shown.push(`${JSON.stringify(attrs['alt'] ?? '')} ${JSON.stringify(attrs['url'])}`)
-    const content = node.content ?? []
-    if (content.some((child) => child.type === 'text' || child.type === 'hardBreak')) shown.push(content.map((child) => child.text ?? '\n').join(''))
-    else for (const text of shownText(content)) shown.push(text)
-  }
-  return shown.filter((text) => text !== '')
-}
-
-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(read.value, document, `reading ${JSON.stringify(emitted.value)}`)
-    }),
-    propertyRuns(gateRuns),
-  )
-})
-
-test('a generated document writes plain markdown refusing only what the guard refuses, and that markdown reads back to its text and to itself', { timeout: propertyTimeout }, () => {
-  fc.assert(
-    fc.property(adfDocument, (document) => {
-      const written = adfToPlainMarkdown(document)
-      assert.ok(written.ok, written.ok ? '' : `${written.error.code}: ${written.error.message}`)
-      assert.ok(readsNoDirective(written.value), `a directive in ${JSON.stringify(written.value)}`)
-      const read = plainMarkdownToAdf(written.value)
-      assert.ok(read.ok, read.ok ? '' : `${read.error.code}: ${read.error.message} — reading ${JSON.stringify(written.value)}`)
-      const reduced = reduceToPlain(document)
-      assert.deepEqual(shownText(read.value.content ?? []), reduced.ok ? shownText(reduced.value.content ?? []) : reduced, `reading ${JSON.stringify(written.value)}`)
-      assert.deepEqual(adfToPlainMarkdown(read.value), written, `reading ${JSON.stringify(written.value)}`)
-    }),
-    propertyRuns(gateRuns),
-  )
-})

src/corpus.test.ts

@@ -4,13 +4,14 @@ import { fileURLToPath } from 'node:url'
 import { readFileSync, readdirSync } from 'node:fs'
 import test from 'node:test'
 
-import { adfToMarkdown } from '../markdown/emit/adf-to-markdown.ts'
-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 { adfToMarkdown } from './markdown/emit/adf-to-markdown.ts'
+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 corpusRoot = join(dirname(fileURLToPath(import.meta.url)), '..', 'corpus')
 const errorsRoot = join(corpusRoot, 'errors')
 const normalizationRoot = join(corpusRoot, 'normalization')
 const realPayloadsRoot = join(corpusRoot, 'real-payloads')
@@ -96,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)
     })
   }
 }
@@ -124,12 +125,12 @@ 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)
   })
 }
 
@@ -145,7 +146,7 @@ for (const name of names(realPayloadsRoot, '.json')) {
     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(parsed.value, payload)
+    assert.deepEqual(toEditorNormal(parsed.value), payload)
   })
 }
 

src/flavour.test.ts

@@ -4,15 +4,15 @@ import { fileURLToPath } from 'node:url'
 import { readFileSync } from 'node:fs'
 import test from 'node:test'
 
-import type { AttributeKind, AttributeVocabulary } from '../adf/attribute-vocabulary.ts'
-import { blockNodes } from '../adf/block-nodes.ts'
-import { inlineNodes } from '../adf/inline-nodes.ts'
-import { markAttributes } from '../adf/mark-attributes.ts'
-import { textDirectiveName } from '../markdown/text-directive.ts'
+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 { textDirectiveName } from './markdown/text-directive.ts'
 
 type Declared = { attributes: AttributeVocabulary }
 
-const specPath = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'spec', 'flavour.md')
+const specPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'spec', 'flavour.md')
 const introducer = 'Attributes: '
 const codeFence = /^`{3,}/
 const directiveName = /`([a-z][A-Za-z0-9]*)`/g
@@ -90,16 +90,16 @@ function vocabularies(table: Readonly<Record<string, Declared>>): Record<string,
 }
 
 test('the block node table holds the attributes spec/flavour.md gives each node', () => {
-  assert.deepEqual(declarations('Block nodes'), vocabularies(blockNodes))
+  assert.deepEqual(declarations('Block nodes'), vocabularies(blockDirectives))
 })
 
 test('the inline node table holds the attributes spec/flavour.md gives each node', () => {
-  assert.deepEqual(declarations('Inline nodes'), vocabularies(inlineNodes))
+  assert.deepEqual(declarations('Inline nodes'), vocabularies(inlineDirectives))
 })
 
 // A name in two tables would make the position a directive is read in ambiguous.
 test('no name is spelled in more than one position', () => {
-  const names = [...Object.keys(blockNodes), ...Object.keys(inlineNodes), ...Object.keys(markAttributes), textDirectiveName]
+  const names = [...Object.keys(blockDirectives), ...Object.keys(inlineDirectives), ...Object.keys(markAttributes), textDirectiveName]
   assert.equal(new Set(names).size, names.length)
 })
 

src/index.ts

@@ -1,8 +1,6 @@
-// Export only the conversions, their types, isAdfDocument and what a guarantee or a persona needs.
 export type { AdfAttributes, AdfDocument, AdfMark, AdfNode } from './adf/document.ts'
 export type { ConvertError, ConvertErrorCode, ConvertErrorPath, ParseError, Result, SourcePosition } from './result.ts'
 export type { JsonValue } from './json-value.ts'
 export { adfToMarkdown } from './markdown/emit/adf-to-markdown.ts'
-export { adfToPlainMarkdown } from './markdown/emit/plain-reduction.ts'
 export { isAdfDocument } from './adf/document.ts'
-export { markdownToAdf, plainMarkdownToAdf } from './markdown/parse/markdown-to-adf.ts'
+export { markdownToAdf } from './markdown/parse/markdown-to-adf.ts'

src/markdown-property.test.ts

@@ -2,16 +2,16 @@ import assert from 'node:assert/strict'
 import fc from 'fast-check'
 import test from 'node:test'
 
-import type { AdfDocument } from '../adf/document.ts'
+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 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, listBreakName, marksAttribute } from '../markdown/block-directive.ts'
-import { blockNodes } from '../adf/block-nodes.ts'
-import { carryName } from '../markdown/opaque-carry.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 {
   directivePrefix,
   spellAttributes,
@@ -22,16 +22,19 @@ import {
   spellJsonAttribute,
   spellStringAttribute,
   spellVocabulary,
-} from '../markdown/directive-syntax.ts'
-import { fencedCodeBlock } from '../markdown/commonmark/backtick-runs.ts'
-import { inlineNodes } from '../adf/inline-nodes.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 { nodeContent, nodeMarks } from '../adf/document.ts'
-import { serializeCanonicalJson } from '../canonical-json.ts'
-import { textDirectiveName } from '../markdown/text-directive.ts'
-import { vocabularyPairs } from '../adf/attribute-vocabulary.ts'
+} from './markdown/directive-syntax.ts'
+import { fencedCodeBlock } from './markdown/commonmark/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 { 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 }
 
@@ -47,11 +50,11 @@ const fixpointFloor = 600
 const gateRuns = 1000
 const markdownMarkTypes = new Set(Object.keys(markAttributes).filter((type) => markSpelling(type)?.kind !== 'directive'))
 
-const vocabularies = [...Object.values(blockNodes).map((model) => model.attributes), ...Object.values(inlineNodes).map((model) => model.attributes), ...Object.values(markAttributes)]
+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(blockNodes).flatMap((type) => blockArgument(type) ?? []), marksAttribute, 'json', textDirectiveName]),
+  ...new Set([...vocabularies.flatMap((vocabulary) => Object.keys(vocabulary)), ...Object.keys(blockDirectives).flatMap((type) => blockArgument(type) ?? []), marksAttribute, 'json', textDirectiveName]),
 ]
-const directiveNames = [...Object.keys(blockNodes), ...Object.keys(inlineNodes), ...Object.keys(markAttributes), carryName, listBreakName, 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> {
@@ -230,9 +233,9 @@ function inlineMarkdown(hostile: boolean): InlineMarkdown {
         },
         {
           arbitrary: fc.oneof(
-            ...Object.entries(inlineNodes).map(([name, model]) =>
+            ...Object.entries(inlineDirectives).map(([name, directive]) =>
               fc
-                .tuple(model.textAttribute === undefined ? fc.constant(null) : fc.option(hostile ? word : prose), tableAttributes(model.attributes, model.textAttribute))
+                .tuple(directive.textAttribute === undefined ? fc.constant(null) : fc.option(hostile ? word : prose), tableAttributes(directive.attributes, directive.textAttribute))
                 .map(([slot, attrs]) => (slot === null ? spellInlineLeafDirective(name, attrs) : `${spellInlineDirectiveOpener(name)}${slot}]${attrs}`)),
             ),
             ...Object.entries(markAttributes)
@@ -325,15 +328,15 @@ function blockMarkdown(hostile: boolean, { inlines, oneLine }: InlineMarkdown, {
   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(blockNodes).map(([name, model]) => {
+    const tableDirectives = Object.entries(blockDirectives).map(([name, directive]) => {
       const argument =
         blockArgument(name) === undefined
           ? fc.constant(undefined)
           : fc.oneof({ arbitrary: fc.constantFrom('DONE', 'TODO', 'custom', 'info', 'warning'), weight: 3 }, { arbitrary: bareToken, weight: 1 })
-      const attrs = hostile ? fc.oneof({ arbitrary: tableAttributes(model.attributes), weight: 4 }, { arbitrary: hostileAttributes, weight: 1 }) : tableAttributes(model.attributes)
-      if (model.contentModel === 'none') return fc.tuple(argument, attrs).map(([held, spelled]) => spellDirectiveOpener(name, held, spelled))
+      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]) => spellDirectiveOpener(name, held, spelled))
       return fc
-        .tuple(argument, attrs, bodyByModel[model.contentModel], hostile ? closerDrift : fc.constant(null))
+        .tuple(argument, attrs, bodyByModel[directive.contentModel], hostile ? closerDrift : fc.constant(null))
         .map(([held, spelled, body, closer]) => container(spellDirectiveOpener(name, held, spelled), body, closer ?? spellDirectiveCloser(name)))
     })
     return {
@@ -432,7 +435,7 @@ test('generated markdown refuses, or what it parses to refuses to emit, or its s
       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(read.value, parsed.value, `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)

src/markdown/block-directive-arguments.ts

@@ -0,0 +1,13 @@
+import type { BlockType } from '../adf/block-directives.ts'
+
+const argumentByType = new Map(
+  Object.entries({
+    blockTaskItem: 'state',
+    panel: 'panelType',
+    taskItem: 'state',
+  } satisfies Partial<Record<BlockType, string>>),
+)
+
+export function blockArgument(type: string): string | undefined {
+  return argumentByType.get(type)
+}

src/markdown/block-directive-forms.ts

@@ -0,0 +1,9 @@
+import { blockDirective } from '../adf/block-directives.ts'
+import { listBreakName } from './list-break.ts'
+
+export function blockDirectiveForm(name: string): 'container' | 'leaf' | undefined {
+  if (name === listBreakName) return 'leaf'
+  const directive = blockDirective(name)
+  if (directive === undefined) return undefined
+  return directive.contentModel === 'none' ? 'leaf' : 'container'
+}

src/markdown/block-directive-marks.ts

@@ -0,0 +1,23 @@
+import type { AdfMark } from '../adf/document.ts'
+import type { JsonValue } from '../json-value.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 = nodeAttrs(mark)
+    return Object.keys(attrs).length === 0 ? { type: mark.type } : { attrs, type: mark.type }
+  })
+}
+
+export function readMarkValues(value: JsonValue): AdfMark[] | undefined {
+  if (!Array.isArray(value) || value.length === 0) return undefined
+  const marks: AdfMark[] = []
+  for (const item of value) {
+    if (!isAdfMark(item)) return undefined
+    marks.push(item)
+  }
+  return serializeCanonicalJson(markValues(marks), 'compact') === serializeCanonicalJson(value, 'compact') ? marks : undefined
+}

src/markdown/block-directive.ts

@@ -1,51 +0,0 @@
-import type { AdfMark } from '../adf/document.ts'
-import type { BlockType } from '../adf/block-nodes.ts'
-import type { JsonValue } from '../json-value.ts'
-import { blockNodeModel } from '../adf/block-nodes.ts'
-import { isAdfMark } from '../adf/document.ts'
-import { serializeCanonicalJson } from '../canonical-json.ts'
-import { spellDirectiveOpener } from './directive-syntax.ts'
-
-const argumentByType = new Map(
-  Object.entries({
-    blockTaskItem: 'state',
-    panel: 'panelType',
-    taskItem: 'state',
-  } satisfies Partial<Record<BlockType, string>>),
-)
-
-export const documentName = 'doc'
-
-// spec/flavour.md, Directives: a document holding no content key, which the empty string cannot spell.
-export const documentSpelling = spellDirectiveOpener(documentName, undefined, '{content=none}')
-
-export const listBreakName = 'listBreak'
-
-export const listBreakSpelling = spellDirectiveOpener(listBreakName, undefined, '')
-
-export const marksAttribute = 'marks'
-
-export function blockArgument(type: string): string | undefined {
-  return argumentByType.get(type)
-}
-
-export function blockDirectiveForm(name: string): 'container' | 'leaf' | undefined {
-  if (name === listBreakName || name === documentName) return 'leaf'
-  const model = blockNodeModel(name)
-  if (model === undefined) return undefined
-  return model.contentModel === 'none' ? 'leaf' : 'container'
-}
-
-export function markValues(marks: readonly AdfMark[]): JsonValue {
-  return marks.map((mark) => (mark.attrs === undefined ? { type: mark.type } : { attrs: mark.attrs, type: mark.type }))
-}
-
-export function readMarkValues(value: JsonValue): AdfMark[] | undefined {
-  if (!Array.isArray(value) || value.length === 0) return undefined
-  const marks: AdfMark[] = []
-  for (const item of value) {
-    if (!isAdfMark(item)) return undefined
-    marks.push(item)
-  }
-  return serializeCanonicalJson(markValues(marks), 'compact') === serializeCanonicalJson(value, 'compact') ? marks : undefined
-}

src/markdown/code-language.ts

@@ -1,12 +1,14 @@
 import type { JsonValue } from '../json-value.ts'
-import { carryFencePrefix } from './opaque-carry.ts'
-import { infoStringCarries } from './commonmark/grammar.ts'
+import { carryName } from './opaque-carry.ts'
+import { holdsControlCharacter } from './commonmark/grammar.ts'
+import { holdsEntityReference } from './commonmark/entity-references.ts'
 
 export type LanguageSlot = { info: string; kind: 'fence' } | { kind: 'attribute' } | { kind: 'none' }
 
 // spec/flavour.md, The CommonMark blocks: the one slot a codeBlock's language rides.
 export function languageSlot(language: JsonValue | undefined): LanguageSlot {
   if (language === undefined) return { kind: 'none' }
-  if (typeof language !== 'string' || language.startsWith(carryFencePrefix) || !infoStringCarries(language)) return { kind: 'attribute' }
+  if (typeof language !== 'string' || language === '' || language === carryName) return { kind: 'attribute' }
+  if (/[`\\]/.test(language) || holdsControlCharacter(language) || language !== language.trim() || holdsEntityReference(language)) return { kind: 'attribute' }
   return { info: language, kind: 'fence' }
 }

src/markdown/commonmark/emphasis-matching.ts

@@ -27,7 +27,6 @@ export function isWordCharacter(character: string): boolean {
   return character !== '' && !isWhitespace(character) && !isPunctuation(character)
 }
 
-// Transcribes CommonMark's reference process_emphasis line for line; the closer walk and opener search stay whole, since named steps drift from it.
 export function matchEmphasis<Run extends DelimiterRun>(runs: readonly Run[]): EmphasisPairing<Run>[] {
   const pairings: EmphasisPairing<Run>[] = []
   const bottoms = new Map<string, Candidate<Run> | undefined>()

src/markdown/commonmark/grammar.ts

@@ -1,4 +1,4 @@
-import { holdsEntityReference, readEntityReference, replacementCharacter } from './entity-references.ts'
+import { readEntityReference, replacementCharacter } from './entity-references.ts'
 
 export type LinePosition = 'first' | 'later'
 
@@ -133,11 +133,6 @@ export function holdsControlCharacter(text: string): boolean {
   return controlCharacter.test(text)
 }
 
-// What a backtick fence's info string reads back verbatim: escapes and entity references decode, and the edges trim.
-export function infoStringCarries(text: string): boolean {
-  return text !== '' && !/[`\\]/.test(text) && !holdsControlCharacter(text) && text === text.trim() && !holdsEntityReference(text)
-}
-
 export function holdsNullCharacter(text: string): boolean {
   return nullCharacter.test(text)
 }

src/markdown/directive-syntax.ts

@@ -139,7 +139,7 @@ export function spellStringAttribute(text: string): string {
 export function spellAttributeValue(value: VocabularyValue): string {
   if (value.kind === 'boolean') return `${value.value}`
   if (value.kind === 'json') return spellJsonAttribute(value.value)
-  if (value.kind === 'number') return spellStringAttribute(serializeCanonicalJson(value.value, 'compact'))
+  if (value.kind === 'number') return spellStringAttribute(JSON.stringify(value.value))
   return spellStringAttribute(value.value)
 }
 

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

@@ -6,13 +6,14 @@ 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 }
 }
 
 function paragraph(...content: AdfNode[]): AdfNode {
-  return content.length === 0 ? { type: 'paragraph' } : { content, type: 'paragraph' }
+  return { content, type: 'paragraph' }
 }
 
 function code(result: Result<string>): string {
@@ -167,24 +168,21 @@ test('parts two adjacent lists of the same kind, the marker spelling being what
   const nested: AdfNode = { content: [{ content: [list, list], type: 'listItem' }], type: 'bulletList' }
   assert.equal(markdown(adfToMarkdown(document(nested))), '- - x\n\n  !adf:listBreak\n\n  - x\n')
   const carried: AdfNode = { ...list, attrs: { unknown: 'x' } }
-  assert.ok(markdown(adfToMarkdown(document(carried, carried))).includes('```\n\n```adf:bulletList\n'))
+  assert.ok(markdown(adfToMarkdown(document(carried, carried))).includes('```\n\n```carry\n'))
   assert.ok(markdown(adfToMarkdown(document(carried, list))).endsWith('```\n\n- x\n'))
-  assert.ok(markdown(adfToMarkdown(document(list, carried))).startsWith('- x\n\n```adf:bulletList\n'))
+  assert.ok(markdown(adfToMarkdown(document(list, carried))).startsWith('- x\n\n```carry\n'))
 })
 
-test('carries a node type no section spells, the fence naming the type wherever an info string carries it', () => {
-  assert.equal(markdown(adfToMarkdown(document({ type: 'blockCard' }))), '```adf:blockCard\n{}\n```\n')
-  assert.equal(markdown(adfToMarkdown(document({ type: 'toString' }))), '```adf:toString\n{}\n```\n')
+test('carries a node type no section spells', () => {
+  assert.equal(markdown(adfToMarkdown(document({ type: 'blockCard' }))), '```carry\n{\n  "type": "blockCard"\n}\n```\n')
+  assert.equal(markdown(adfToMarkdown(document({ type: 'toString' }))), '```carry\n{\n  "type": "toString"\n}\n```\n')
   assert.equal(markdown(adfToMarkdown(document(paragraph({ type: 'blockCard' })))), '!adf:carry{json="{\\"type\\":\\"blockCard\\"}"}\n')
-  assert.equal(markdown(adfToMarkdown(document({ text: 'x', type: 'text' }))), '```adf:text\n{\n  "text": "x"\n}\n```\n')
-  assert.equal(markdown(adfToMarkdown(document({ type: 'hardBreak' }))), '```adf:hardBreak\n{}\n```\n')
-  assert.equal(markdown(adfToMarkdown(document({ type: 'a&amp;b' }))), '```adf:\n{\n  "type": "a&amp;b"\n}\n```\n')
-  assert.equal(markdown(adfToMarkdown(document({ type: 'a\\b' }))), '```adf:\n{\n  "type": "a\\\\b"\n}\n```\n')
+  assert.equal(markdown(adfToMarkdown(document({ text: 'x', type: 'text' }))), '```carry\n{\n  "text": "x",\n  "type": "text"\n}\n```\n')
+  assert.equal(markdown(adfToMarkdown(document({ type: 'hardBreak' }))), '```carry\n{\n  "type": "hardBreak"\n}\n```\n')
 })
 
-test('spells the code block whose language opens with the reserved info string prefix', () => {
-  assert.equal(markdown(adfToMarkdown(document({ attrs: { language: 'adf:x' }, type: 'codeBlock' }))), '!adf:codeBlock {language="adf:x"}\n```\n```\n!adf:/codeBlock\n')
-  assert.equal(markdown(adfToMarkdown(document({ attrs: { language: 'carry' }, type: 'codeBlock' }))), '```carry\n```\n')
+test('spells the code block whose language is the reserved info string', () => {
+  assert.equal(markdown(adfToMarkdown(document({ attrs: { language: 'carry' }, type: 'codeBlock' }))), '!adf:codeBlock {language=carry}\n```\n```\n!adf:/codeBlock\n')
   assert.equal(markdown(adfToMarkdown(document({ attrs: { language: 'adf' }, type: 'codeBlock' }))), '```adf\n```\n')
 })
 
@@ -210,17 +208,21 @@ test('refuses a carried node nested deeper than the levels its position leaves',
   assert.equal(code(adfToMarkdown(document(quoted))), 'unsupported-nesting-depth')
 })
 
-test('carries a code block holding a node no fence holds', () => {
-  assert.equal(markdown(adfToMarkdown(document({ content: [paragraph()], type: 'codeBlock' }))), '```adf:codeBlock\n{\n  "content": [\n    {\n      "type": "paragraph"\n    }\n  ]\n}\n```\n')
-  for (const child of [{ attrs: {}, text: 'x', type: 'text' }, { content: [], text: 'x', type: 'text' }, { marks: [], text: 'x', type: 'text' }, { content: [{ text: 'lost', type: 'text' }], text: 'x', type: 'text' }]) {
-    assert.ok(markdown(adfToMarkdown(document({ content: [child], type: 'codeBlock' }))).startsWith('```adf:codeBlock\n'), JSON.stringify(child))
-  }
+test('refuses a node whose content model the canonical form cannot emit', () => {
+  assert.equal(
+    markdown(adfToMarkdown(document({ content: [paragraph()], type: 'codeBlock' }))),
+    'unsupported-node-shape: a codeBlock holds plain text nodes only: this paragraph node is not one',
+  )
+  assert.equal(
+    markdown(adfToMarkdown(document({ content: [{ content: [{ text: 'lost', type: 'text' }], text: 'x', type: 'text' }], type: 'codeBlock' }))),
+    'unsupported-node-shape: a codeBlock holds plain text nodes only: this text node is not one',
+  )
 })
 
 test('spells a list its own content shape cannot hold as a directive', () => {
   assert.equal(markdown(adfToMarkdown(document({ content: [paragraph()], type: 'bulletList' }))), '!adf:bulletList\n!adf:paragraph\n!adf:/paragraph\n!adf:/bulletList\n')
   assert.equal(markdown(adfToMarkdown(document({ type: 'bulletList' }))), '!adf:bulletList\n!adf:/bulletList\n')
-  assert.equal(markdown(adfToMarkdown(document({ attrs: { order: 2 }, content: [], type: 'orderedList' }))), '!adf:orderedList {content=empty order=2}\n!adf:/orderedList\n')
+  assert.equal(markdown(adfToMarkdown(document({ attrs: { order: 2 }, content: [], type: 'orderedList' }))), '!adf:orderedList {order=2}\n!adf:/orderedList\n')
 })
 
 test('spells an ordered list no marker fits as a directive', () => {
@@ -332,7 +334,7 @@ test('refuses a node carrying one mark type twice', () => {
 })
 
 test('parts a nested list the tight spelling would swallow from the block above it', () => {
-  const item = (...content: AdfNode[]): AdfNode => (content.length === 0 ? { type: 'listItem' } : { content, type: 'listItem' })
+  const item = (...content: AdfNode[]): AdfNode => ({ content, type: 'listItem' })
   const text = (value: string): AdfNode => ({ content: [{ text: value, type: 'text' }], type: 'paragraph' })
   const outer = (...content: AdfNode[]): AdfDocument => document({ content: [item(...content)], type: 'bulletList' })
   const ordered: AdfNode = { attrs: { order: 2 }, content: [item(text('b'))], type: 'orderedList' }
@@ -343,7 +345,7 @@ test('parts a nested list the tight spelling would swallow from the block above
   const list: AdfNode = { content: [item(text('b'))], type: 'bulletList' }
   const panel: AdfNode = { attrs: { panelType: 'info' }, content: [text('p')], type: 'panel' }
   assert.equal(markdown(adfToMarkdown(outer(panel, list))), '- !adf:panel info\n  p\n  !adf:/panel\n\n  - b\n')
-  assert.ok(markdown(adfToMarkdown(outer(text('a'), { ...list, attrs: { unknown: 'x' } }))).startsWith('- a\n\n  ```adf:bulletList\n'))
+  assert.ok(markdown(adfToMarkdown(outer(text('a'), { ...list, attrs: { unknown: 'x' } }))).startsWith('- a\n\n  ```carry\n'))
 })
 
 test('refuses marks and attributes nested deeper than the emitter carries', () => {
@@ -351,8 +353,8 @@ test('refuses marks and attributes nested deeper than the emitter carries', () =
   assert.equal(code(adfToMarkdown(document(paragraph({ marks, text: 'x', type: 'text' })))), 'unsupported-nesting-depth')
   let attrs: AdfMark['attrs'] = { depth: 'x' }
   for (let depth = 0; depth < 600; depth += 1) attrs = { depth: attrs }
-  const deeper = (key: string, type: string): string =>
-    `unsupported-nesting-depth: the ${key} attribute of ${type} nests deeper than the ${largestNesting} levels an attribute carries`
+  const deeper = (key: string, type: string, levels: number = largestNesting): string =>
+    `unsupported-nesting-depth: the ${key} attribute of ${type} nests deeper than the ${levels} levels an attribute carries`
   const nested = (levels: number): JsonValue => {
     let value: JsonValue = 1
     for (let level = 0; level < levels; level += 1) value = [value]
@@ -370,21 +372,14 @@ test('refuses marks and attributes nested deeper than the emitter carries', () =
     assert.ok(spelled.ok, spelled.ok ? '' : spelled.error.message)
     const read = markdownToAdf(spelled.value)
     assert.ok(read.ok, read.ok ? '' : read.error.message)
-    assert.deepEqual(read.value, document(node))
+    assert.deepEqual(toEditorNormal(read.value), document(node))
   }
 
-  assert.equal(markdown(adfToMarkdown(document(paragraph({ marks: [{ attrs, type: 'em' }], text: 'x', type: 'text' })))), deeper('depth', 'em'))
-  assert.equal(
-    markdown(adfToMarkdown(document(paragraph({ marks: [{ attrs: { deep: nested(largestNesting) }, type: 'em' }], text: 'x', type: 'text' })))),
-    `unsupported-nesting-depth: a carried node's JSON nests deeper than the ${largestNesting} levels its position leaves`,
-  )
+  assert.equal(markdown(adfToMarkdown(document(paragraph({ marks: [{ attrs, type: 'em' }], text: 'x', type: 'text' })))), deeper('depth', 'em', largestNesting - 3))
   assert.equal(markdown(adfToMarkdown(document(paragraph(card(largestNesting + 1))))), deeper('data', 'inlineCard'))
   assert.deepEqual(path(adfToMarkdown(document(paragraph(card(largestNesting + 1))))), [])
   roundTrips(paragraph(card(largestNesting)))
-  assert.equal(markdown(adfToMarkdown(document(marked(largestNesting - 2)))), deeper('marks', 'panel'))
-  assert.deepEqual(path(adfToMarkdown(document(marked(largestNesting - 2)))), ['content', 0])
-  const markedCode: AdfNode = { content: [{ text: 'x', type: 'text' }], marks: [{ attrs: { deep: nested(largestNesting - 2) }, type: 'em' }], type: 'codeBlock' }
-  assert.equal(markdown(adfToMarkdown(document(markedCode))), deeper('marks', 'codeBlock'))
+  assert.equal(markdown(adfToMarkdown(document(marked(largestNesting - 2)))), deeper('deep', 'em', largestNesting - 3))
   roundTrips(marked(largestNesting - 3))
 })
 
@@ -440,7 +435,7 @@ test('escapes a hyphen underline a hard break would expose', () => {
 })
 
 test('spells a list item whose marker completes a thematic break as a directive', () => {
-  const item = (...content: AdfNode[]): AdfNode => (content.length === 0 ? { type: 'listItem' } : { content, type: 'listItem' })
+  const item = (...content: AdfNode[]): AdfNode => ({ content, type: 'listItem' })
   assert.equal(markdown(adfToMarkdown(document({ content: [item({ type: 'rule' })], type: 'bulletList' }))), '!adf:bulletList\n!adf:listItem\n---\n!adf:/listItem\n!adf:/bulletList\n')
   const nested: AdfNode = { content: [item({ content: [item()], type: 'bulletList' })], type: 'bulletList' }
   assert.equal(markdown(adfToMarkdown(document(nested))), '- -\n')
@@ -467,7 +462,10 @@ test('refuses the characters CommonMark rewrites', () => {
   )
   assert.equal(code(adfToMarkdown(document(paragraph({ text: 'a\u0000b', type: 'text' })))), 'unspellable-character')
   assert.equal(code(adfToMarkdown(document({ content: [{ text: 'a\u0000b', type: 'text' }], type: 'codeBlock' }))), 'unspellable-character')
-  assert.equal(markdown(adfToMarkdown(document({ content: [{ text: '', type: 'text' }], type: 'codeBlock' }))), 'unsupported-node-shape: a text node holds text: this one has none')
+  assert.equal(
+    markdown(adfToMarkdown(document({ content: [{ text: '', type: 'text' }], type: 'codeBlock' }))),
+    'unsupported-node-shape: a codeBlock holds plain text nodes only: this text node is not one',
+  )
 })
 
 test('refuses a text node the spelling would empty out', () => {
@@ -496,11 +494,11 @@ test('pads a code span whose edges CommonMark would strip', () => {
   assert.equal(markdown(adfToMarkdown(document(paragraph({ marks: [{ type: 'code' }], text: ' \t ', type: 'text' })))), '`  \t  `\n')
 })
 
-test('spells a code span per code-marked node, parted by the text break', () => {
+test('spells one code span over a run of code-marked nodes', () => {
   const code_ = { type: 'code' }
   assert.equal(
     markdown(adfToMarkdown(document(paragraph({ marks: [code_], text: 'a', type: 'text' }, { marks: [code_], text: 'b', type: 'text' })))),
-    '`a`!adf:textBreak{}`b`\n',
+    '`ab`\n',
   )
 })
 
@@ -540,7 +538,7 @@ test('emits an empty list item without trailing whitespace', () => {
 test('spells a block directive as its node type, arg and attributes', () => {
   const panel = (attrs: AdfAttributes): AdfDocument => document({ attrs, content: [paragraph({ text: 'x', type: 'text' })], type: 'panel' })
   assert.equal(markdown(adfToMarkdown(panel({ panelType: 'warning' }))), '!adf:panel warning\nx\n!adf:/panel\n')
-  assert.equal(markdown(adfToMarkdown(panel({}))), '!adf:panel {attrs=empty}\nx\n!adf:/panel\n')
+  assert.equal(markdown(adfToMarkdown(panel({}))), '!adf:panel\nx\n!adf:/panel\n')
   assert.equal(markdown(adfToMarkdown(document({ content: [{ text: 'x', type: 'text' }], type: 'caption' }))), '!adf:caption\nx\n!adf:/caption\n')
   assert.equal(markdown(adfToMarkdown(document({ type: 'caption' }))), '!adf:caption\n!adf:/caption\n')
   assert.equal(markdown(adfToMarkdown(document({ attrs: { localId: 'a' }, type: 'syncBlock' }))), '!adf:syncBlock {localId=a}\n')
@@ -548,20 +546,20 @@ test('spells a block directive as its node type, arg and attributes', () => {
 
 test('carries a directive attribute no section spells', () => {
   const carried = (node: AdfNode): string => markdown(adfToMarkdown(document(node)))
-  assert.equal(carried({ attrs: { rounded: true }, type: 'panel' }), '```adf:panel\n{\n  "attrs": {\n    "rounded": true\n  }\n}\n```\n')
-  assert.equal(carried({ attrs: { toString: 'x' }, type: 'panel' }), '```adf:panel\n{\n  "attrs": {\n    "toString": "x"\n  }\n}\n```\n')
-  assert.equal(carried({ attrs: { localId: 4 }, type: 'panel' }), '```adf:panel\n{\n  "attrs": {\n    "localId": 4\n  }\n}\n```\n')
+  assert.equal(carried({ attrs: { rounded: true }, type: 'panel' }), '```carry\n{\n  "attrs": {\n    "rounded": true\n  },\n  "type": "panel"\n}\n```\n')
+  assert.equal(carried({ attrs: { toString: 'x' }, type: 'panel' }), '```carry\n{\n  "attrs": {\n    "toString": "x"\n  },\n  "type": "panel"\n}\n```\n')
+  assert.equal(carried({ attrs: { localId: 4 }, type: 'panel' }), '```carry\n{\n  "attrs": {\n    "localId": 4\n  },\n  "type": "panel"\n}\n```\n')
   assert.equal(
     carried({ attrs: { width: '50' }, type: 'layoutColumn' }),
-    '```adf:layoutColumn\n{\n  "attrs": {\n    "width": "50"\n  }\n}\n```\n',
+    '```carry\n{\n  "attrs": {\n    "width": "50"\n  },\n  "type": "layoutColumn"\n}\n```\n',
   )
   assert.equal(
     carried({ attrs: { isNumberColumnEnabled: 'true' }, type: 'table' }),
-    '```adf:table\n{\n  "attrs": {\n    "isNumberColumnEnabled": "true"\n  }\n}\n```\n',
+    '```carry\n{\n  "attrs": {\n    "isNumberColumnEnabled": "true"\n  },\n  "type": "table"\n}\n```\n',
   )
   assert.equal(
     carried({ content: [{ attrs: { alt: 4 }, type: 'media' }], type: 'mediaGroup' }),
-    '!adf:mediaGroup\n```adf:media\n{\n  "attrs": {\n    "alt": 4\n  }\n}\n```\n!adf:/mediaGroup\n',
+    '!adf:mediaGroup\n```carry\n{\n  "attrs": {\n    "alt": 4\n  },\n  "type": "media"\n}\n```\n!adf:/mediaGroup\n',
   )
 })
 
@@ -569,16 +567,15 @@ test('carries an arg slot value no bare token spells', () => {
   const carried = (node: AdfNode): string => markdown(adfToMarkdown(document(node)))
   assert.equal(
     carried({ attrs: { panelType: 'extra info' }, type: 'panel' }),
-    '```adf:panel\n{\n  "attrs": {\n    "panelType": "extra info"\n  }\n}\n```\n',
+    '```carry\n{\n  "attrs": {\n    "panelType": "extra info"\n  },\n  "type": "panel"\n}\n```\n',
   )
-  assert.equal(carried({ attrs: { state: 2 }, type: 'taskItem' }), '```adf:taskItem\n{\n  "attrs": {\n    "state": 2\n  }\n}\n```\n')
+  assert.equal(carried({ attrs: { state: 2 }, type: 'taskItem' }), '```carry\n{\n  "attrs": {\n    "state": 2\n  },\n  "type": "taskItem"\n}\n```\n')
 })
 
 test('carries a block node mark in the reserved attribute', () => {
   const section = (...marks: AdfMark[]): AdfDocument => document({ marks, type: 'layoutSection' })
   assert.equal(markdown(adfToMarkdown(section({ type: 'breakout' }))), '!adf:layoutSection {marks="[{\\"type\\":\\"breakout\\"}]"}\n!adf:/layoutSection\n')
-  assert.equal(markdown(adfToMarkdown(section({ attrs: {}, type: 'breakout' }))), '!adf:layoutSection {marks="[{\\"attrs\\":{},\\"type\\":\\"breakout\\"}]"}\n!adf:/layoutSection\n')
-  assert.equal(markdown(adfToMarkdown(section())), '!adf:layoutSection {marks=empty}\n!adf:/layoutSection\n')
+  assert.equal(markdown(adfToMarkdown(section({ attrs: {}, type: 'breakout' }))), '!adf:layoutSection {marks="[{\\"type\\":\\"breakout\\"}]"}\n!adf:/layoutSection\n')
 })
 
 test('refuses the content a directive body has no room for', () => {
@@ -600,7 +597,7 @@ test('separates blocks in a container body by a blank line only where a directiv
 test('spells the image form for exactly the centered external media shape', () => {
   const url = 'https://example.com/moon.png'
   const single = (attrs: AdfAttributes, ...content: AdfNode[]): AdfDocument =>
-    document({ attrs: { layout: 'center' }, content: [content.length === 0 ? { attrs, type: 'media' } : { attrs, content, type: 'media' }], type: 'mediaSingle' })
+    document({ attrs: { layout: 'center' }, content: [{ attrs, content, type: 'media' }], type: 'mediaSingle' })
   assert.equal(markdown(adfToMarkdown(single({ alt: 'The moon', type: 'external', url }))), `![The moon](${url})\n`)
   assert.equal(markdown(adfToMarkdown(single({ type: 'external', url }))), `![](${url})\n`)
   assert.equal(markdown(adfToMarkdown(single({ alt: 'a [b] c', type: 'external', url }))), `![a \\[b\\] c](${url})\n`)
@@ -697,8 +694,7 @@ test('spells the directive marks around the longest run they cover', () => {
   const emitted = (...content: AdfNode[]): string => markdown(adfToMarkdown(document(paragraph(...content))))
   const underline: AdfMark = { type: 'underline' }
   assert.equal(emitted(marked('x', underline)), '!adf:underline[x]\n')
-  assert.equal(emitted(marked('a', underline), marked('b', underline)), '!adf:underline[a!adf:textBreak{}b]\n')
-  assert.equal(emitted(marked('a', { attrs: {}, type: 'underline' }), marked('b', underline)), '!adf:underline[a]{attrs=empty}!adf:underline[b]\n')
+  assert.equal(emitted(marked('a', underline), marked('b', underline)), '!adf:underline[ab]\n')
   assert.equal(emitted(marked('x', { attrs: { type: 'sub' }, type: 'subsup' })), '!adf:subsup[x]{type=sub}\n')
   assert.equal(emitted(marked('x', { attrs: { color: '#ae2e24' }, type: 'textColor' })), '!adf:textColor[x]{color="#ae2e24"}\n')
   assert.equal(emitted(marked('x', { attrs: { color: '#091e42', size: 2 }, type: 'border' })), '!adf:border[x]{color="#091e42" size=2}\n')
@@ -743,5 +739,5 @@ test('carries whitespace CommonMark strips in the reserved text directive', () =
 
 test("joins a mark run's segments as a walk rather than as one call's arguments", () => {
   const run = Array.from({ length: 200000 }, (): AdfNode => ({ marks: [{ type: 'strong' }], text: 'a', type: 'text' }))
-  assert.equal(markdown(adfToMarkdown(document({ content: run, type: 'paragraph' }))), `**${Array.from({ length: 200000 }, () => 'a').join('!adf:textBreak{}')}**\n`)
+  assert.equal(markdown(adfToMarkdown(document({ content: run, type: 'paragraph' }))), `**${'a'.repeat(200000)}**\n`)
 })

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

@@ -1,17 +1,16 @@
 import type { AdfDocument, AdfNode } from '../../adf/document.ts'
-import type { BlockNodeModel } from '../../adf/block-nodes.ts'
-import type { Flavour } from '../plain-conventions.ts'
-import { adfDocumentFault, carriesOnly, nodeAttrs, nodeContent } from '../../adf/document.ts'
-import { alertMarker, foldedAlertMarker, leadingMarker, readAlertMarker, readTaskMarker, taskMarker } from '../plain-conventions.ts'
-import { blockDirectiveForm, documentSpelling, listBreakSpelling } from '../block-directive.ts'
-import { blockNodeModel, blockNodes } from '../../adf/block-nodes.ts'
+import type { BlockDirective } from '../../adf/block-directives.ts'
+import { adfDocumentFault, carriesOnly, nodeAttrs, nodeContent, nodeMarks } from '../../adf/document.ts'
+import { blockDirective, blockDirectives } from '../../adf/block-directives.ts'
+import { blockDirectiveForm } from '../block-directive-forms.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 '../commonmark/backtick-runs.ts'
 import { holdsNullCharacter, isBlankLine, isThematicBreak, markerInterruptsParagraph } from '../commonmark/grammar.ts'
-import { languageSlot, type LanguageSlot } from '../code-language.ts'
+import { languageSlot } from '../code-language.ts'
 import { largestNesting } from '../../nesting.ts'
+import { listBreakSpelling } from '../list-break.ts'
 import { spellBlockDirectiveOpener } from './block-directive-spelling.ts'
 import { spellDirectiveCloser, spellDirectiveOpener } from '../directive-syntax.ts'
 import { tryImage } from './image.ts'
@@ -21,39 +20,32 @@ type BlockContainer = 'directive' | 'document' | 'list-item'
 type BlockSpelling = 'commonmark' | 'directive' | 'list'
 type EmittedBlock = { headroom: number; spelling: BlockSpelling; text: string }
 type KeptSpelling = { block: EmittedBlock | undefined; depth: number }
-type PlacedBlock = Omit<EmittedBlock, 'headroom'> & { node: AdfNode }
-// Keyed by reference: only a caller building one object per position (the parse, the plain reduction) passes one; a consumer's document may share a node.
+type PlacedBlock = EmittedBlock & { node: AdfNode }
 export type SpellingMemo = Map<AdfNode, KeptSpelling>
 type Walk = { blocks: readonly PlacedBlock[]; headroom: number }
 type WalkedItem = { node: AdfNode; walk: Walk }
-export type Writing = { flavour: Flavour; memo: SpellingMemo | undefined }
 
-export const largestListMarker = 999999999
+const largestListMarker = 999999999
 // Bare because tryList admits no item carrying attributes, marks or text.
 const listItemOpener = spellDirectiveOpener('listItem', undefined, '')
 
 export function adfToMarkdown(document: AdfDocument): Result<string> {
-  return writeMarkdown(document, 'lossless')
-}
-
-export function writeMarkdown(document: AdfDocument, flavour: Flavour): 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}`, [])
-  if (document.content === undefined) return success(`${documentSpelling}\n`)
-  const walk = walkBlocks(document.content, [], 0, { flavour, memo: undefined })
+  const walk = walkBlocks(nodeContent(document), [], 0, undefined)
   if (!walk.ok) return walk
   const text = joinBlocks(walk.value.blocks, 'document')
   return success(text === '' ? '' : `${text}\n`)
 }
 
 // headroom: the least slack any depth guard below the walk has.
-function walkBlocks(nodes: readonly AdfNode[], path: ConvertErrorPath, depth: number, writing: Writing): Result<Walk> {
+function walkBlocks(nodes: readonly AdfNode[], path: ConvertErrorPath, depth: number, memo: SpellingMemo | undefined): Result<Walk> {
   let headroom = largestNesting - depth
   if (headroom < 0) return tooDeep(path)
   const blocks: PlacedBlock[] = []
   for (const [index, node] of nodes.entries()) {
-    const block = emitBlock(node, [...path, 'content', index], depth, writing)
+    const block = emitBlock(node, [...path, 'content', index], depth, memo)
     if (!block.ok) return block
     headroom = Math.min(headroom, block.value.headroom)
     blocks.push({ ...block.value, node })
@@ -89,120 +81,51 @@ function separationBetween(previous: PlacedBlock, next: PlacedBlock, container:
 
 function interruptsParagraph(node: AdfNode): boolean {
   const items = nodeContent(node)
-  const empty = node.type !== 'taskList' && (items[0] === undefined || nodeContent(items[0]).length === 0)
+  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)
 }
 
-function emitBlock(node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result<EmittedBlock> {
-  const model = blockNodeModel(node.type)
-  if (model === undefined) return commonMarkLine(carriedBlock(node, path, depth))
-  const readable = readableBlock(node, path, depth, writing)
+function emitBlock(node: AdfNode, path: ConvertErrorPath, depth: number, memo: SpellingMemo | undefined): Result<EmittedBlock> {
+  const directive = blockDirective(node.type)
+  if (directive === undefined) return commonMarkLine(carriedBlock(node, path, depth))
+  const readable = readableBlock(node, path, depth, memo)
   if (readable !== undefined) return readable
-  return emitDirectiveBlock(node, model, path, depth, () => walkBlocks(nodeContent(node), path, depth + 1, writing))
+  return emitDirectiveBlock(node, directive, path, depth, () => walkBlocks(nodeContent(node), path, depth + 1, memo))
 }
 
-export function commonMarkSpelling(node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result<null> | undefined {
-  const readable = readableBlock(node, path, depth, writing)
+export function commonMarkSpelling(node: AdfNode, path: ConvertErrorPath, depth: number, memo: SpellingMemo): Result<null> | undefined {
+  const readable = readableBlock(node, path, depth, memo)
   if (readable === undefined) return undefined
   if (!readable.ok) return readable
   return readable.value.spelling === 'directive' ? undefined : success(null)
 }
 
-function readableBlock(node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result<EmittedBlock> | undefined {
-  const { memo } = writing
+function readableBlock(node: AdfNode, path: ConvertErrorPath, depth: number, memo: SpellingMemo | undefined): Result<EmittedBlock> | undefined {
   const kept = memo?.get(node)
   if (kept !== undefined) {
     if (kept.block === undefined) return undefined
-    // A read below the fill would skip the depth guards the walk it replaces runs (docs/decisions.md §The spelling memo).
+    // A read below the fill would skip the depth guards the walk it replaces runs (AGENTS.md §11).
     if (depth <= kept.depth) return success({ ...kept.block, headroom: kept.block.headroom + kept.depth - depth })
   }
-  const spelled = spellReadableBlock(node, path, depth, writing)
+  const spelled = spellReadableBlock(node, path, depth, memo)
   if (spelled === undefined) memo?.set(node, { block: undefined, depth })
   else if (spelled.ok) memo?.set(node, { block: spelled.value, depth })
   return spelled
 }
 
-function spellReadableBlock(node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result<EmittedBlock> | undefined {
-  const plain = writing.flavour === 'plain' ? spellPlainBlock(node, path, depth, writing) : undefined
-  if (plain !== undefined) return plain
-  if (node.type === 'blockquote') return tryBlockquote(node, path, depth, writing)
-  if (node.type === 'bulletList' || node.type === 'orderedList') return tryList(node, path, depth, writing)
+function spellReadableBlock(node: AdfNode, path: ConvertErrorPath, depth: number, memo: SpellingMemo | undefined): Result<EmittedBlock> | undefined {
+  if (node.type === 'blockquote') return tryBlockquote(node, path, depth, memo)
+  if (node.type === 'bulletList' || node.type === 'orderedList') return tryList(node, path, depth, memo)
   if (node.type === 'codeBlock') return tryCodeBlock(node, path)
-  if (node.type === 'heading') return tryHeading(node, path, writing.flavour)
+  if (node.type === 'heading') return tryHeading(node, path)
   if (node.type === 'mediaSingle') return readableText(tryImage(node, path))
-  if (node.type === 'paragraph') return tryParagraph(node, path, writing.flavour)
+  if (node.type === 'paragraph') return tryParagraph(node, path)
   if (node.type === 'rule') return readableText(tryRule(node))
-  if (node.type === 'table') return readableText(tryPipeTable(node, path, writing.flavour))
+  if (node.type === 'table') return readableText(tryPipeTable(node, path))
   return undefined
 }
 
-// The plain flavour's nodes, in the shapes the plain reduction leaves them.
-function spellPlainBlock(node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result<EmittedBlock> | undefined {
-  if (node.type === 'panel') return quotedUnder(alertMarker(nodeAttrs(node)['panelType']), node, path, depth, writing)
-  if (node.type === 'taskList') return tryTaskList(node, path, depth, writing)
-  if (node.type !== 'expand' && node.type !== 'nestedExpand') return undefined
-  const title = nodeAttrs(node)['title']
-  if (typeof title !== 'string') return quotedUnder(foldedAlertMarker, node, path, depth, writing)
-  // The reader takes a title as lossless inline text.
-  const line = emitInlineLine([{ text: title, type: 'text' }], 'paragraph', path, 'lossless')
-  return line.ok ? quotedUnder(`${foldedAlertMarker} ${line.value}`, node, path, depth, writing) : line
-}
-
-function quotedUnder(head: string, node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result<EmittedBlock> {
-  const inner = walkBlocks(nodeContent(node), path, depth + 1, writing)
-  if (!inner.ok) return inner
-  const body = joinBlocks(inner.value.blocks, 'document')
-  return success(commonMarkText(quoted(body === '' ? head : `${head}\n\n${body}`), inner.value.headroom))
-}
-
-function quoted(text: string): string {
-  return text
-    .split('\n')
-    .map((line) => (line === '' ? '>' : `> ${line}`))
-    .join('\n')
-}
-
-function tryTaskList(node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result<EmittedBlock> {
-  const items: PlacedBlock[][] = []
-  let headroom = largestNesting - depth - 1
-  // A child other than a task nests in the task before it.
-  for (const [index, child] of nodeContent(node).entries()) {
-    const task = child.type === 'taskItem' || child.type === 'blockTaskItem'
-    const walk = task ? taskBlocks(child, [...path, 'content', index], depth + 1, writing) : placedBlock(child, [...path, 'content', index], depth + 1, writing)
-    if (!walk.ok) return walk
-    headroom = Math.min(headroom, walk.value.headroom)
-    const previous = items.at(-1)
-    if (task || previous === undefined) items.push([...walk.value.blocks])
-    else for (const block of walk.value.blocks) previous.push(block)
-  }
-  const lines = items.map((blocks) => tryListItemLines(joinBlocks(blocks, 'list-item'), '- '))
-  // The plain reduction leaves no task a list item cannot hold: a directive here would break the flavour.
-  return lines.includes(undefined) ? failure('unsupported-node-shape', 'a task holds blocks no list item spells', path) : success({ headroom, spelling: 'list', text: lines.join('\n') })
-}
-
-function placedBlock(node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result<Walk> {
-  const block = emitBlock(node, path, depth, writing)
-  return block.ok ? success({ blocks: [{ ...block.value, node }], headroom: block.value.headroom }) : block
-}
-
-// The marker leads the first paragraph, or stands as one where the blocks open with another.
-function taskBlocks(task: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result<Walk> {
-  const marker = taskMarker(nodeAttrs(task)['state'])
-  const markerBlock: PlacedBlock = { node: { type: 'paragraph' }, spelling: 'commonmark', text: marker }
-  if (task.type === 'taskItem') {
-    const content = nodeContent(task)
-    const line = content.length === 0 ? success('') : emitInlineLine(content, 'paragraph', path, writing.flavour)
-    if (!line.ok) return line
-    return success({ blocks: [{ ...markerBlock, text: line.value === '' ? marker : `${marker} ${line.value}` }], headroom: Number.POSITIVE_INFINITY })
-  }
-  const walk = walkBlocks(nodeContent(task), path, depth, writing)
-  if (!walk.ok) return walk
-  const [first, ...rest] = walk.value.blocks
-  const blocks = first?.node.type === 'paragraph' ? [{ ...first, text: `${marker} ${first.text}` }, ...rest] : [markerBlock, ...walk.value.blocks]
-  return success({ blocks, headroom: walk.value.headroom })
-}
-
 function readableText(text: string | undefined): Result<EmittedBlock> | undefined {
   return text === undefined ? undefined : success(commonMarkText(text))
 }
@@ -220,20 +143,19 @@ function directivePair(node: AdfNode, opener: string, body: string, headroom: nu
   return { headroom, spelling: 'directive', text: `${opener}\n${body === '' ? '' : `${body}\n`}${spellDirectiveCloser(node.type)}` }
 }
 
-function emitDirectiveBlock(node: AdfNode, model: BlockNodeModel, path: ConvertErrorPath, depth: number, walkBody: () => Result<Walk>): Result<EmittedBlock> {
+function emitDirectiveBlock(node: AdfNode, directive: BlockDirective, path: ConvertErrorPath, depth: number, walkBody: () => Result<Walk>): Result<EmittedBlock> {
   if (node.text !== undefined) return failure('unsupported-node-shape', `a ${node.type} carries no text: this one holds text`, path)
   if (blockDirectiveForm(node.type) === 'leaf' && nodeContent(node).length > 0) return failure('unsupported-node-shape', `a ${node.type} holds no content: this one holds some`, path)
-  if (model.contentModel === 'code') return emitCodeDirective(node, model, path, depth)
-  const opener = spellBlockDirectiveOpener(node, model, path)
+  if (directive.contentModel === 'code') return emitCodeDirective(node, directive, path, depth)
+  const opener = spellBlockDirectiveOpener(node, directive)
   if (opener === undefined) return commonMarkLine(carriedBlock(node, path, depth))
-  if (!opener.ok) return opener
-  return emitDirectiveBody(node, model, opener.value, path, walkBody)
+  return emitDirectiveBody(node, directive, opener, path, walkBody)
 }
 
-function emitDirectiveBody(node: AdfNode, model: BlockNodeModel, opener: string, path: ConvertErrorPath, walkBody: () => Result<Walk>): Result<EmittedBlock> {
+function emitDirectiveBody(node: AdfNode, directive: BlockDirective, opener: string, path: ConvertErrorPath, walkBody: () => Result<Walk>): Result<EmittedBlock> {
   if (blockDirectiveForm(node.type) === 'leaf') return success({ headroom: Number.POSITIVE_INFINITY, spelling: 'directive', text: opener })
-  if (model.contentModel === 'inline') {
-    const line = emitInlineLine(nodeContent(node), 'paragraph', path, 'lossless')
+  if (directive.contentModel === 'inline') {
+    const line = emitInlineLine(nodeContent(node), 'paragraph', path)
     if (!line.ok) return line
     return success(directivePair(node, opener, line.value))
   }
@@ -242,67 +164,69 @@ function emitDirectiveBody(node: AdfNode, model: BlockNodeModel, opener: string,
   return success(directivePair(node, opener, joinBlocks(walk.value.blocks, 'directive'), walk.value.headroom))
 }
 
-function tryBlockquote(node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result<EmittedBlock> | undefined {
+function tryBlockquote(node: AdfNode, path: ConvertErrorPath, depth: number, memo: SpellingMemo | undefined): Result<EmittedBlock> | undefined {
   if (!carriesOnly(node, [])) return undefined
-  const inner = walkBlocks(nodeContent(node), path, depth + 1, writing)
+  const inner = walkBlocks(nodeContent(node), path, depth + 1, memo)
   if (!inner.ok) return inner
   const text = joinBlocks(inner.value.blocks, 'document')
-  const alert = writing.flavour === 'plain' && leadingMarker(text, readAlertMarker) !== undefined
-  return success(commonMarkText(quoted(alert ? `\\${text}` : text), inner.value.headroom))
+    .split('\n')
+    .map((line) => (line === '' ? '>' : `> ${line}`))
+    .join('\n')
+  return success(commonMarkText(text, inner.value.headroom))
 }
 
 function tryCodeBlock(node: AdfNode, path: ConvertErrorPath): Result<EmittedBlock> | undefined {
   if (!carriesOnly(node, ['language'])) return undefined
   const slot = languageSlot(nodeAttrs(node)['language'])
   if (slot.kind === 'attribute') return undefined
-  const texts = fencedTexts(node, path)
-  if (!texts.ok) return texts
-  const [only, ...others] = texts.value ?? []
-  if (only === undefined || others.length > 0) return undefined
-  return success(commonMarkText(fencedCodeBlock(slot.kind === 'fence' ? slot.info : '', only)))
+  const text = codeBlockText(node, path)
+  if (!text.ok) return text
+  return success(commonMarkText(fencedCodeBlock(slot.kind === 'fence' ? slot.info : '', text.value)))
 }
 
-// spec/flavour.md, The CommonMark blocks: one fence per text node, the language on each; with no fence to carry it, the attribute does.
-function emitCodeDirective(node: AdfNode, model: BlockNodeModel, path: ConvertErrorPath, depth: number): Result<EmittedBlock> {
-  const texts = fencedTexts(node, path)
-  if (!texts.ok) return texts
-  if (texts.value === undefined) return commonMarkLine(carriedBlock(node, path, depth))
-  const slot: LanguageSlot = texts.value.length === 0 ? { kind: 'attribute' } : languageSlot(nodeAttrs(node)['language'])
-  const opener = spellBlockDirectiveOpener(node, model, path, slot.kind === 'attribute' ? [] : ['language'])
+function emitCodeDirective(node: AdfNode, directive: BlockDirective, path: ConvertErrorPath, depth: number): Result<EmittedBlock> {
+  const slot = languageSlot(nodeAttrs(node)['language'])
+  const opener = spellBlockDirectiveOpener(node, directive, slot.kind === 'attribute' ? [] : ['language'])
   if (opener === undefined) return commonMarkLine(carriedBlock(node, path, depth))
-  if (!opener.ok) return opener
-  const info = slot.kind === 'fence' ? slot.info : ''
-  return success(directivePair(node, opener.value, texts.value.map((text) => fencedCodeBlock(info, text)).join('\n')))
+  const text = codeBlockText(node, path)
+  if (!text.ok) return text
+  return success(directivePair(node, opener, fencedCodeBlock(slot.kind === 'fence' ? slot.info : '', text.value)))
 }
 
-// The text each fence holds, or `undefined` where a child is no plain text node, which the carry holds instead.
-function fencedTexts(node: AdfNode, path: ConvertErrorPath): Result<string[] | undefined> {
-  if (node.content === undefined) return success([''])
-  if (node.content.some((child) => child.type !== 'text' || child.attrs !== undefined || child.content !== undefined || child.marks !== undefined)) return success(undefined)
-  const texts: string[] = []
-  for (const [index, child] of node.content.entries()) {
+function codeBlockText(node: AdfNode, path: ConvertErrorPath): Result<string> {
+  let text = ''
+  for (const [index, child] of nodeContent(node).entries()) {
     const childPath = [...path, 'content', index]
-    if (typeof child.text !== 'string' || child.text === '') return failure('unsupported-node-shape', 'a text node holds text: this one has none', childPath)
+    if (
+      child.type !== 'text' ||
+      typeof child.text !== 'string' ||
+      child.text === '' ||
+      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)
+    }
     if (/\r/.test(child.text)) return failure('unspellable-character', 'a codeBlock holds no carriage return CommonMark keeps: this text holds one', childPath)
     if (holdsNullCharacter(child.text)) return failure('unspellable-character', 'a codeBlock holds a null character CommonMark replaces', childPath)
-    texts.push(child.text)
+    text += child.text
   }
-  return success(texts)
+  return success(text)
 }
 
-function tryHeading(node: AdfNode, path: ConvertErrorPath, flavour: Flavour): Result<EmittedBlock> | undefined {
+function tryHeading(node: AdfNode, path: ConvertErrorPath): Result<EmittedBlock> | undefined {
   if (!carriesOnly(node, ['level'])) return undefined
   const level = nodeAttrs(node)['level']
   if (typeof level !== 'number' || !Number.isInteger(level) || level < 1 || level > 6) return undefined
   const hashes = '#'.repeat(level)
   const content = nodeContent(node)
   if (content.length === 0) return success(commonMarkText(hashes))
-  const line = emitInlineLine(content, 'heading', path, flavour)
+  const line = emitInlineLine(content, 'heading', path)
   if (!line.ok) return line
   return success(commonMarkText(`${hashes} ${line.value}`))
 }
 
-function tryList(node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result<EmittedBlock> | undefined {
+function tryList(node: AdfNode, path: ConvertErrorPath, depth: number, memo: SpellingMemo | undefined): Result<EmittedBlock> | undefined {
   const ordered = node.type === 'orderedList'
   if (!carriesOnly(node, ordered ? ['order'] : [])) return undefined
   const items = nodeContent(node)
@@ -312,39 +236,37 @@ function tryList(node: AdfNode, path: ConvertErrorPath, depth: number, writing:
   const walked: WalkedItem[] = []
   let headroom = Number.POSITIVE_INFINITY
   for (const [offset, item] of items.entries()) {
-    const walk = walkBlocks(nodeContent(item), [...path, 'content', offset], depth + 1, writing)
+    const walk = walkBlocks(nodeContent(item), [...path, 'content', offset], depth + 1, memo)
     if (!walk.ok) return walk
     headroom = Math.min(headroom, walk.value.headroom)
     walked.push({ node: item, walk: walk.value })
   }
   const lines: string[] = []
   for (const [offset, item] of walked.entries()) {
-    const inner = joinBlocks(item.walk.blocks, 'list-item')
-    // GitHub reads a task marker opening any item's first paragraph as a checkbox, whatever its siblings hold.
-    const escaped = writing.flavour === 'plain' && leadingMarker(inner, readTaskMarker) !== undefined ? `\\${inner}` : inner
-    const line = tryListItemLines(escaped, ordered ? `${start + offset}. ` : '- ')
+    const line = tryListItemLines(item.walk.blocks, ordered ? `${start + offset}. ` : '- ')
     if (line === undefined) {
-      // The directive form spends a level the walk did not count.
       if (headroom < 1) return tooDeep(path)
-      return emitDirectiveBlock(node, ordered ? blockNodes.orderedList : blockNodes.bulletList, path, depth, () => success({ blocks: directiveItems(walked), headroom: headroom - 1 }))
+      return emitDirectiveBlock(node, ordered ? blockDirectives.orderedList : blockDirectives.bulletList, path, depth, () => success({ blocks: directiveItems(walked), headroom: headroom - 1 }))
     }
     lines.push(line)
   }
   return success({ headroom, spelling: 'list', text: lines.join('\n') })
 }
 
+// The directive form sinks each item's blocks a level below where the walk read them.
 function directiveItems(items: readonly WalkedItem[]): PlacedBlock[] {
-  return items.map((item) => ({ ...directivePair(item.node, listItemOpener, joinBlocks(item.walk.blocks, 'directive')), node: item.node }))
+  return items.map((item) => ({ ...directivePair(item.node, listItemOpener, joinBlocks(item.walk.blocks, 'directive'), item.walk.headroom - 1), node: item.node }))
 }
 
 function listStart(node: AdfNode, items: number): number | undefined {
   if (node.type !== 'orderedList') return 0
   const start = nodeAttrs(node)['order']
-  if (typeof start !== 'number' || !Number.isInteger(start) || start < 0 || Object.is(start, -0) || start > largestListMarker) return undefined
+  if (typeof start !== 'number' || !Number.isInteger(start) || start < 0 || start > largestListMarker) return undefined
   return start + items - 1 > largestListMarker ? undefined : start
 }
 
-function tryListItemLines(inner: string, marker: string): string | undefined {
+function tryListItemLines(blocks: readonly PlacedBlock[], marker: string): string | undefined {
+  const inner = joinBlocks(blocks, 'list-item')
   if (inner === '') return marker.trimEnd()
   const body = inner.split('\n')
   if (body.some((line) => line !== '' && isBlankLine(line))) return undefined
@@ -354,10 +276,10 @@ function tryListItemLines(inner: string, marker: string): string | undefined {
   return lines.join('\n')
 }
 
-function tryParagraph(node: AdfNode, path: ConvertErrorPath, flavour: Flavour): Result<EmittedBlock> | undefined {
+function tryParagraph(node: AdfNode, path: ConvertErrorPath): Result<EmittedBlock> | undefined {
   const content = nodeContent(node)
   if (content.length === 0 || !carriesOnly(node, [])) return undefined
-  const line = emitInlineLine(content, 'paragraph', path, flavour)
+  const line = emitInlineLine(content, 'paragraph', path)
   if (!line.ok) return line
   return success(commonMarkText(line.value))
 }

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

@@ -1,28 +1,22 @@
 import type { AdfNode } from '../../adf/document.ts'
-import type { BlockNodeModel } from '../../adf/block-nodes.ts'
-import { attributeNestingMessage, nodeAttrs, nodeMarks } from '../../adf/document.ts'
-import { blockArgument, markValues, marksAttribute } from '../block-directive.ts'
-import { failure, success, type ConvertErrorPath, type Result } from '../../result.ts'
+import type { BlockDirective } from '../../adf/block-directives.ts'
+import { blockArgument } from '../block-directive-arguments.ts'
 import { isBareToken, spellAttributes, spellDirectiveOpener, spellJsonAttribute, spellVocabulary } from '../directive-syntax.ts'
-import { overNested } from '../../json-value.ts'
-import { spellEmptyKeys } from '../empty-keys.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 spellBlockDirectiveOpener(node: AdfNode, model: BlockNodeModel, path: ConvertErrorPath, spelledByBody: readonly string[] = []): Result<string> | undefined {
+export function spellBlockDirectiveOpener(node: AdfNode, directive: BlockDirective, spelledByBody: readonly string[] = []): string | undefined {
   const argumentAttribute = blockArgument(node.type)
   const slot = bareArgument(node, argumentAttribute)
   if (slot === undefined) return undefined
   const spelled = argumentAttribute === undefined ? spelledByBody : [argumentAttribute, ...spelledByBody]
-  const pairs = vocabularyPairs(nodeAttrs(node), model.attributes, spelled)
+  const pairs = vocabularyPairs(nodeAttrs(node), directive.attributes, spelled)
   if (pairs === undefined) return undefined
-  const spelledPairs = [...spellVocabulary(pairs), ...spellEmptyKeys(node)]
+  const spelledPairs = spellVocabulary(pairs)
   const marks = nodeMarks(node)
-  if (marks.length > 0) {
-    const values = markValues(marks)
-    if (overNested(values)) return failure('unsupported-nesting-depth', attributeNestingMessage(marksAttribute, node.type), path)
-    spelledPairs.push([marksAttribute, spellJsonAttribute(values)])
-  }
-  return success(spellDirectiveOpener(node.type, slot.argument, spellAttributes(spelledPairs)))
+  if (marks.length > 0) spelledPairs.push([marksAttribute, spellJsonAttribute(markValues(marks))])
+  return spellDirectiveOpener(node.type, slot.argument, spellAttributes(spelledPairs))
 }
 
 // `undefined` where the argument slot holds a value no bare token spells.

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

@@ -1,11 +1,10 @@
 import type { AdfNode } from '../../adf/document.ts'
-import type { InlineNodeModel } from '../../adf/inline-nodes.ts'
+import type { InlineDirective } from '../../adf/inline-directives.ts'
 import { nodeAttrs } from '../../adf/document.ts'
 import { spellAttributes, spellVocabulary } from '../directive-syntax.ts'
-import { spellEmptyKeys } from '../empty-keys.ts'
 import { vocabularyPairs } from '../../adf/attribute-vocabulary.ts'
 
-export function spellInlineNodeAttributes(node: AdfNode, model: InlineNodeModel): string | undefined {
-  const pairs = vocabularyPairs(nodeAttrs(node), model.attributes, model.textAttribute === undefined ? [] : [model.textAttribute])
-  return pairs === undefined ? undefined : spellAttributes([...spellVocabulary(pairs), ...spellEmptyKeys(node)])
+export function spellInlineNodeAttributes(node: AdfNode, directive: InlineDirective): string | undefined {
+  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,19 +1,16 @@
 import type { AdfMark, AdfNode } from '../../adf/document.ts'
-import type { Flavour } from '../plain-conventions.ts'
-import type { InlineNodeModel } from '../../adf/inline-nodes.ts'
-import type { LineContainer } from '../line-container.ts'
-import { assembleInlineLine, isSyntax, type InlineEscaping, type InlineSegment, type MarkRun, type NodeRange } from './line-escaping.ts'
+import type { InlineDirective } from '../../adf/inline-directives.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, trimTrailingSpace } from '../commonmark/grammar.ts'
 import { commonMarkLink, linkHref, markSpelling, spellMarkAttributes } from '../mark-spellings.ts'
-import { emptyKeys, identicalMark, nodeAttrs, nodeContent, nodeMarks } from '../../adf/document.ts'
 import { escapeUnbalanced, spellDestination } from '../commonmark/link-syntax.ts'
 import { failure, faulted, success, type ConvertErrorPath, type Result } from '../../result.ts'
-import { highlightDelimiter } from '../plain-conventions.ts'
-import { inlineNodeModel } from '../../adf/inline-nodes.ts'
+import { inlineDirective } from '../../adf/inline-directives.ts'
 import { largestNesting } from '../../nesting.ts'
 import { longestBacktickRun } from '../commonmark/backtick-runs.ts'
-import { readsAsOne, textBreakSpelling } from '../text-break.ts'
+import { nodeAttrs, nodeContent, nodeMarks } from '../../adf/document.ts'
+import { sameMark } from '../../adf/editor-normal.ts'
 import { slotLineEndingFault, spellInlineDirectiveOpener, spellInlineLeafDirective } from '../directive-syntax.ts'
 import { spellInlineNodeAttributes } from './inline-directive-spelling.ts'
 import { spellTextDirective } from '../text-directive.ts'
@@ -26,7 +23,6 @@ type InlineContext = {
   atBlockEnd: boolean
   bracketed: boolean
   carried: ReadonlySet<number>
-  flavour: Flavour
   openingLinkAsDirective: boolean
   path: ConvertErrorPath
   spansLines: boolean
@@ -36,32 +32,22 @@ type InlineRun = { index: number; kind: 'marked'; mark: AdfMark; nodes: AdfNode[
 
 type LineAttempt = { fallback: NodeRange | 'opening-link'; line?: undefined } | { fallback?: undefined; line: string }
 
-type LineFallbacks = { carried: Set<number>; flavour: Flavour; openingLinkAsDirective: boolean }
+type LineFallbacks = { carried: Set<number>; openingLinkAsDirective: boolean }
 
-export type PlainLineFallback = { kind: 'claimed-line'; line: number; text: string } | { kind: 'opening-link' } | { kind: 'unspellable-run'; runs: [MarkRun, ...MarkRun[]] }
-
-export function emitInlineLine(nodes: readonly AdfNode[], container: LineContainer, path: ConvertErrorPath, flavour: Flavour): Result<string> {
-  const emitted = emitLine(nodes, container, path, flavour)
+export function emitInlineLine(nodes: readonly AdfNode[], container: LineContainer, path: ConvertErrorPath): Result<string> {
+  const emitted = emitLine(nodes, container, path)
   if (!emitted.ok) return emitted
   return success(emitted.value.line)
 }
 
 export function openingLinkTakesDirective(nodes: readonly AdfNode[], path: ConvertErrorPath): Result<boolean> {
-  const emitted = emitLine(nodes, 'paragraph', path, 'lossless')
+  const emitted = emitLine(nodes, 'paragraph', path)
   if (!emitted.ok) return emitted
   return success(emitted.value.openingLinkAsDirective)
 }
 
-export function plainLineFallback(nodes: readonly AdfNode[], container: LineContainer, path: ConvertErrorPath): Result<PlainLineFallback | undefined> {
-  const emission = lineSegments(nodes, container, path, { carried: new Set(), flavour: 'plain', openingLinkAsDirective: false })
-  if (!emission.ok) return emission
-  if (emission.value.carry !== undefined) return failure('unsupported-node-shape', 'an inline node on a plain line has no spelling but the carry', path)
-  const verdict = lineVerdict(emission.value.segments, container, 'plain')
-  return success(verdict.kind === 'line' ? undefined : verdict)
-}
-
-export function tryPipeCell(nodes: readonly AdfNode[], path: ConvertErrorPath, flavour: Flavour): string | undefined {
-  const emitted = emitLine(nodes, 'table-cell', path, flavour)
+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) => isSyntax(segment.escaping) && segment.text.includes('|'))) return undefined
   return emitted.value.line
@@ -72,13 +58,12 @@ export function tryImageLine(alt: string | undefined, href: string, path: Conver
   const destination = spellDestination(href)
   if (destination === undefined) return undefined
   const description: InlineSegment[] = alt === undefined ? [] : [{ escaping: 'bracketed', text: alt }]
-  const attempt = attemptLine([syntax('!['), ...description, syntax(`](${destination})`)], 'paragraph', path, 'lossless')
+  const attempt = attemptLine([syntax('!['), ...description, syntax(`](${destination})`)], 'paragraph', path)
   return attempt.ok ? attempt.value.line : undefined
 }
 
-function emitLine(nodes: readonly AdfNode[], container: LineContainer, path: ConvertErrorPath, flavour: Flavour): Result<EmittedLine> {
-  const fallbacks: LineFallbacks = { carried: new Set(), flavour, openingLinkAsDirective: false }
-  // Terminates because takeFallback refuses a pass that took no new fallback.
+function emitLine(nodes: readonly AdfNode[], container: LineContainer, path: ConvertErrorPath): Result<EmittedLine> {
+  const fallbacks: LineFallbacks = { carried: new Set(), openingLinkAsDirective: false }
   for (;;) {
     const emission = lineSegments(nodes, container, path, fallbacks)
     if (!emission.ok) return emission
@@ -87,7 +72,7 @@ function emitLine(nodes: readonly AdfNode[], container: LineContainer, path: Con
       if (!taken.ok) return taken
       continue
     }
-    const attempt = attemptLine(emission.value.segments, container, path, flavour)
+    const attempt = attemptLine(emission.value.segments, container, path)
     if (!attempt.ok) return attempt
     if (attempt.value.line !== undefined) {
       return success({ line: attempt.value.line, openingLinkAsDirective: fallbacks.openingLinkAsDirective, segments: emission.value.segments })
@@ -117,23 +102,16 @@ function lineSegments(nodes: readonly AdfNode[], container: LineContainer, path:
   return success({ segments: carryStrippedWhitespace(emission.value.segments) })
 }
 
-function attemptLine(segments: readonly InlineSegment[], container: LineContainer, path: ConvertErrorPath, flavour: Flavour): Result<LineAttempt> {
-  const verdict = lineVerdict(segments, container, flavour)
-  if (verdict.kind === 'opening-link') return success({ fallback: 'opening-link' })
-  if (verdict.kind === 'unspellable-run') return success({ fallback: verdict.runs[0] })
-  if (verdict.kind === 'claimed-line') return failure('unspellable-line-start', `block parsing would claim the emitted line ${JSON.stringify(verdict.text)}`, path)
-  return success({ line: verdict.text })
-}
-
-// The fallbacks in the order a line takes them, or the line where it takes none.
-function lineVerdict(segments: readonly InlineSegment[], container: LineContainer, flavour: Flavour): PlainLineFallback | { kind: 'line'; text: string } {
-  const assembled = assembleInlineLine(segments, container, flavour)
-  if (assembled.openingLinkAsDirective) return { kind: 'opening-link' }
-  const [run, ...others] = assembled.unspellableRuns
-  if (run !== undefined) return { kind: 'unspellable-run', runs: [run, ...others] }
-  const lines = assembled.line.split('\n')
-  const claimed = container === 'paragraph' ? lines.findIndex((single, index) => claimsLine(single, index === 0 ? 'first' : 'later')) : -1
-  return claimed === -1 ? { kind: 'line', text: assembled.line } : { kind: 'claimed-line', line: claimed, text: lines[claimed] ?? '' }
+function attemptLine(segments: readonly InlineSegment[], container: LineContainer, path: ConvertErrorPath): Result<LineAttempt> {
+  const assembled = assembleInlineLine(segments, container)
+  if (assembled.openingLinkAsDirective) return success({ fallback: 'opening-link' })
+  if (assembled.unspellableRun !== undefined) return success({ fallback: assembled.unspellableRun })
+  for (const [index, single] of assembled.line.split('\n').entries()) {
+    if (container === 'paragraph' && claimsLine(single, index === 0 ? 'first' : 'later')) {
+      return failure('unspellable-line-start', `block parsing would claim the emitted line ${JSON.stringify(single)}`, path)
+    }
+  }
+  return success({ line: assembled.line })
 }
 
 // spec/flavour.md, Inline nodes.
@@ -186,7 +164,6 @@ function emitRun(nodes: readonly AdfNode[], depth: number, firstIndex: number, c
   const runs = inlineRuns(nodes, depth, firstIndex, context.carried)
   const segments: InlineSegment[] = []
   for (const [offset, run] of runs.entries()) {
-    if (partsText(runs[offset - 1], run, context.carried)) segments.push(syntax(textBreakSpelling))
     const runContext = { ...context, atBlockEnd: context.atBlockEnd && offset === runs.length - 1 }
     const emitted = run.kind === 'plain' ? emitLeaf(run.node, runContext, run.index) : emitMarkedRun(run.nodes, run.mark, depth, run.index, runContext)
     if (!emitted.ok) return emitted
@@ -207,25 +184,19 @@ function inlineRuns(nodes: readonly AdfNode[], depth: number, firstIndex: number
       continue
     }
     const previous = runs[runs.length - 1]
-    if (previous?.kind === 'marked' && identicalMark(previous.mark, mark)) previous.nodes.push(node)
+    if (previous?.kind === 'marked' && sameMark(previous.mark, mark)) previous.nodes.push(node)
     else runs.push({ index, kind: 'marked', mark, nodes: [node] })
   }
   return runs
 }
 
-function partsText(previous: InlineRun | undefined, run: InlineRun, carried: ReadonlySet<number>): boolean {
-  if (previous?.kind !== 'plain' || run.kind !== 'plain') return false
-  if (carries(previous.node, carried, previous.index) || carries(run.node, carried, run.index)) return false
-  return readsAsOne(previous.node, run.node)
-}
-
 function nodePath(context: InlineContext, index: number): ConvertErrorPath {
   return [...context.path, 'content', index]
 }
 
 function carries(node: AdfNode, carried: ReadonlySet<number>, index: number): boolean {
   if (carried.has(index)) return true
-  return node.type !== 'text' && inlineNodeModel(node.type) === undefined
+  return node.type !== 'text' && inlineDirective(node.type) === undefined
 }
 
 function emitLeaf(node: AdfNode, context: InlineContext, index: number): Result<Emission> {
@@ -237,27 +208,27 @@ function emitLeaf(node: AdfNode, context: InlineContext, index: number): Result<
   }
   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 model = inlineNodeModel(node.type)
-  if (model === undefined) return emitText(node, context, index, path)
-  if (node.type === 'hardBreak') return emitHardBreak(node, model, context, index, path)
-  return emitInlineDirective(node, model, index, path)
+  const directive = inlineDirective(node.type)
+  if (directive === undefined) return emitText(node, context, index, path)
+  if (node.type === 'hardBreak') return emitHardBreak(node, directive, context, index, path)
+  return emitInlineDirective(node, directive, index, path)
 }
 
-function emitHardBreak(node: AdfNode, model: InlineNodeModel, context: InlineContext, index: number, path: ConvertErrorPath): Result<Emission> {
+function emitHardBreak(node: AdfNode, directive: InlineDirective, context: InlineContext, index: number, path: ConvertErrorPath): Result<Emission> {
   const empty = refuseContentAndText(node, path)
   if (!empty.ok) return empty
-  const attributes = spellInlineNodeAttributes(node, model)
+  const attributes = spellInlineNodeAttributes(node, directive)
   if (attributes === undefined) return success({ carry: { first: index, last: index } })
   if (attributes === '' && context.spansLines && !context.atBlockEnd) return success({ segments: [syntax('\\\n')] })
   return success({ segments: [syntax(spellInlineLeafDirective('hardBreak', attributes))] })
 }
 
-function emitInlineDirective(node: AdfNode, model: InlineNodeModel, index: number, path: ConvertErrorPath): Result<Emission> {
+function emitInlineDirective(node: AdfNode, directive: InlineDirective, index: number, path: ConvertErrorPath): Result<Emission> {
   const empty = refuseContentAndText(node, path)
   if (!empty.ok) return empty
-  const attributes = spellInlineNodeAttributes(node, model)
+  const attributes = spellInlineNodeAttributes(node, directive)
   if (attributes === undefined) return success({ carry: { first: index, last: index } })
-  const slot = model.textAttribute === undefined ? undefined : nodeAttrs(node)[model.textAttribute]
+  const slot = directive.textAttribute === undefined ? undefined : nodeAttrs(node)[directive.textAttribute]
   if (slot === undefined) return success({ segments: [syntax(spellInlineLeafDirective(node.type, attributes))] })
   if (typeof slot !== 'string') return success({ carry: { first: index, last: index } })
   const spans = slotLineEndingFault(node.type, slot)
@@ -268,7 +239,7 @@ function emitInlineDirective(node: AdfNode, model: InlineNodeModel, index: numbe
 }
 
 function emitText(node: AdfNode, context: InlineContext, index: number, path: ConvertErrorPath): Result<Emission> {
-  if (node.attrs !== undefined || emptyKeys(node).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 (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)
@@ -281,10 +252,9 @@ function emitText(node: AdfNode, context: InlineContext, index: number, path: Co
 function emitMarkedRun(nodes: readonly AdfNode[], mark: AdfMark, depth: number, index: number, context: InlineContext): Result<Emission> {
   const path = nodePath(context, index)
   const range: NodeRange = { first: index, last: index + nodes.length - 1 }
-  if (mark.type === 'backgroundColor' && context.flavour === 'plain') return emitHighlight(nodes, depth, range, context)
   const spelling = markSpelling(mark.type)
   if (spelling === undefined) return success({ carry: range })
-  const attributes = spellMarkAttributes(mark, spelling)
+  const attributes = spellMarkAttributes(mark, spelling.attributes)
   if (attributes === undefined) return success({ carry: range })
   if (spelling.kind === 'code') return emitCodeSpan(nodes, depth, range, path)
   if (spelling.kind === 'emphasis') return emitEmphasis(nodes, spelling.spelling, depth, range, context)
@@ -303,36 +273,26 @@ function emitEmphasis(nodes: readonly AdfNode[], spelling: string, depth: number
   const carried = carryStrippedWhitespace(inner.value.segments)
   return success({
     segments: [
-      { emphasis: 'open', escaping: 'none', nodes: { ...range, depth }, text: spelling },
+      { emphasis: 'open', escaping: 'none', nodes: range, text: spelling },
       ...carried,
-      { emphasis: 'close', escaping: 'none', nodes: { ...range, depth }, text: spelling },
+      { emphasis: 'close', escaping: 'none', nodes: range, text: spelling },
     ],
   })
 }
 
-function emitHighlight(nodes: readonly AdfNode[], depth: number, range: NodeRange, context: InlineContext): Result<Emission> {
-  const inner = emitRun(nodes, depth + 1, range.first, context)
-  if (!inner.ok || inner.value.carry !== undefined) return inner
-  const run = { ...range, depth }
-  return success({
-    segments: [{ escaping: 'none', highlight: 'open', nodes: run, text: highlightDelimiter }, ...inner.value.segments, { escaping: 'none', highlight: 'close', nodes: run, text: highlightDelimiter }],
-  })
-}
-
-// Each node its own span: CommonMark reads two adjacent text nodes in one span back as one.
 function emitCodeSpan(nodes: readonly AdfNode[], depth: number, range: NodeRange, path: ConvertErrorPath): Result<Emission> {
-  const spans: string[] = []
+  let text = ''
   for (const node of nodes) {
-    if (node.type !== 'text' || nodeMarks(node).length !== depth + 1 || node.attrs !== undefined || emptyKeys(node).length > 0) return success({ carry: range })
-    const { text } = node
-    if (typeof text !== 'string' || text === '') return failure('unsupported-node-shape', 'a text node holds text: this one has none', path)
+    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 (nodeContent(node).length > 0) return failure('unsupported-node-shape', 'a text node holds no content: this one holds some', path)
-    if (/[\n\r]/.test(text)) return success({ carry: range })
-    if (holdsNullCharacter(text)) return failure('unspellable-character', 'a code span holds a null character CommonMark replaces', path)
-    const fence = '`'.repeat(longestBacktickRun(text) + 1)
-    spans.push(`${fence}${needsPadding(text) ? ` ${text} ` : text}${fence}`)
+    text += node.text
   }
-  return success({ segments: [syntax(spans.join(textBreakSpelling))] })
+  if (/[\n\r]/.test(text)) return success({ carry: range })
+  if (holdsNullCharacter(text)) return failure('unspellable-character', 'a code span holds a null character CommonMark replaces', path)
+  const fence = '`'.repeat(longestBacktickRun(text) + 1)
+  const padded = needsPadding(text) ? ` ${text} ` : text
+  return success({ segments: [syntax(`${fence}${padded}${fence}`)] })
 }
 
 function needsPadding(text: string): boolean {

src/markdown/emit/line-escaping.ts

@@ -1,32 +1,28 @@
-import type { Flavour } from '../plain-conventions.ts'
-import type { LineContainer } from '../line-container.ts'
 import { backslashEscape, escapesLineClaim, inlineHtmlConstruct, opensBracketedAutolink, opensEmailAutolink, type LinePosition } from '../commonmark/grammar.ts'
 import { backtickRun, closingBacktickRun } from '../commonmark/backtick-runs.ts'
 import { claimsDirectivePrefix } from '../directive-syntax.ts'
 import { delimiterFlags, isWordCharacter, matchEmphasis, runLength } from '../commonmark/emphasis-matching.ts'
-import { highlightDelimiter, highlightFlanking } from '../plain-conventions.ts'
 import { isBareDelimiterRow } from '../pipe-table-syntax.ts'
 import { opensLinkDefinition } from '../commonmark/link-reference-definitions.ts'
 import { readEntityReference } from '../commonmark/entity-references.ts'
 
-export type DelimiterRole = 'close' | 'open'
+export type EmphasisRole = 'close' | 'open'
 
 export type InlineEscaping = 'backslash' | 'bracketed' | 'bracketed-link-target' | 'none'
 
 export type NodeRange = { first: number; last: number }
 
-export type MarkRun = NodeRange & { depth: number }
-
 export type InlineSegment =
-  | { emphasis: DelimiterRole; escaping: 'none'; highlight?: undefined; nodes: MarkRun; text: string }
-  | { emphasis?: undefined; escaping: 'none'; highlight: DelimiterRole; nodes: MarkRun; text: string }
-  | { emphasis?: undefined; escaping: 'none'; highlight?: undefined; nodes: NodeRange; text: string }
-  | { emphasis?: undefined; escaping: InlineEscaping; highlight?: undefined; nodes?: undefined; text: string }
+  | { emphasis: EmphasisRole; escaping: 'none'; nodes: NodeRange; text: string }
+  | { emphasis?: undefined; escaping: 'none'; nodes: NodeRange; text: string }
+  | { emphasis?: undefined; escaping: InlineEscaping; nodes?: undefined; text: string }
 
-export type AssembledLine = { line: string; openingLinkAsDirective?: true; unspellableRuns: MarkRun[] }
+export type AssembledLine = { line: string; openingLinkAsDirective?: true; unspellableRun: NodeRange | undefined }
 
 type ScanLine = { position: LinePosition; start: number; text: string }
 
+export type LineContainer = 'heading' | 'paragraph' | 'table-cell'
+
 type EmittedDelimiter = { closes: boolean; offset: number; pair: number; width: number }
 
 type EmittedRun = { canClose: boolean; canOpen: boolean; character: string; delimiters: EmittedDelimiter[]; length: number; start: number }
@@ -35,8 +31,8 @@ const delimiters = ['*', '_', '`', '~']
 
 const followsLinkText = /[([]/
 
-export function assembleInlineLine(segments: readonly InlineSegment[], container: LineContainer, flavour: Flavour): AssembledLine {
-  return escape(resolveEmphasis(segments), container, flavour === 'plain')
+export function assembleInlineLine(segments: readonly InlineSegment[], container: LineContainer): AssembledLine {
+  return escape(resolveEmphasis(segments), container)
 }
 
 function resolveEmphasis(segments: readonly InlineSegment[]): InlineSegment[] {
@@ -68,11 +64,11 @@ function resolveEmphasis(segments: readonly InlineSegment[]): InlineSegment[] {
   return resolved
 }
 
-function escape(segments: readonly InlineSegment[], container: LineContainer, highlights: boolean): AssembledLine {
+function escape(segments: readonly InlineSegment[], container: LineContainer): AssembledLine {
   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 = escapeClosedRuns(scan, escapings, escapeClaims(scan, escapings, container, highlights))
+  const escaped = escapedIndexes(scan, escapings, container)
   const placements: number[] = []
   let output = ''
   for (let index = 0; index < scan.length; index += 1) {
@@ -81,48 +77,37 @@ function escape(segments: readonly InlineSegment[], container: LineContainer, hi
     output += scan.charAt(index)
   }
   if (container === 'paragraph' && opensLinkDefinition(output)) {
-    if (segments[0]?.nodes !== undefined) return { line: output, openingLinkAsDirective: true, unspellableRuns: [] }
-    return { line: `\\${output}`, unspellableRuns: unspellableRuns(segments, output, placements) }
+    if (segments[0]?.nodes !== undefined) return { line: output, openingLinkAsDirective: true, unspellableRun: undefined }
+    return { line: `\\${output}`, unspellableRun: unspellableRun(segments, output, placements) }
   }
-  return { line: output, unspellableRuns: unspellableRuns(segments, output, placements) }
+  return { line: output, unspellableRun: unspellableRun(segments, output, placements) }
 }
 
-function escapeClaims(scan: string, escapings: readonly InlineEscaping[], container: LineContainer, highlights: boolean): ReadonlySet<number> {
+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)
-  let afterEscape = false
-  // Whether the `=` before opens a `==` the reader takes whole, so this one starts nothing.
-  let pairsEquals = false
   for (let index = 0; index < scan.length; index += 1) {
     if (index > line.start + line.text.length) line = scanLine(scan, line.start + line.text.length + 1)
     const escaping = escapings[index]
     const escapable = escaping === 'backslash' || escaping === 'bracketed'
-    const opensEquals: boolean = highlights && !pairsEquals && scan.startsWith(highlightDelimiter, index)
-    const claimed: boolean =
+    if (
       (escapable &&
-        ((opensEquals && claimsHighlight(scan, index)) ||
-          claimsLineStart(line, index, container) ||
+        (claimsLineStart(line, index, container) ||
           mergesWithSyntax(scan, escapings, index) ||
-          opensConstruct(scan, linkClose, index, escaping === 'bracketed', container, afterEscape))) ||
+          opensConstruct(scan, linkClose, index, escaping === 'bracketed', container, escaped))) ||
       (escaping === 'bracketed-link-target' &&
-        ((scan.charAt(index) === '`' && opensCodeSpan(scan, index, afterEscape)) || claimsDirectivePrefix(scan, index)))
-    if (claimed) escaped.add(index)
-    afterEscape = claimed
-    pairsEquals = opensEquals && !claimed
+        ((scan.charAt(index) === '`' && opensCodeSpan(scan, index, escaped)) || claimsDirectivePrefix(scan, index)))
+    ) {
+      escaped.add(index)
+    }
   }
+  escapeClosedRuns(scan, escapings, escaped)
   return escaped
 }
 
-// Like an emphasis run, a `==` in text escapes where the reader can open or close with it.
-function claimsHighlight(scan: string, index: number): boolean {
-  const flanking = highlightFlanking(scan, index)
-  return flanking.opens || flanking.closes
-}
-
 // 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[], claimed: ReadonlySet<number>): ReadonlySet<number> {
-  const escaped = new Set(claimed)
+function escapeClosedRuns(scan: string, escapings: readonly InlineEscaping[], escaped: Set<number>): void {
   const formed = new Set<number>()
   let end = scan.length - 1
   while (end >= 0) {
@@ -134,41 +119,23 @@ function escapeClosedRuns(scan: string, escapings: readonly InlineEscaping[], cl
     while (scan.charAt(start - 1) === '`') start -= 1
     let segmentEnd = end
     for (let index = end; index > start; index -= 1) {
-      if (!claimed.has(index)) continue
+      if (!escaped.has(index)) continue
       formed.add(segmentEnd - index + 1)
       segmentEnd = index - 1
     }
-    if (segmentEnd !== end || claimed.has(start)) formed.add(segmentEnd - start + 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
   }
-  return escaped
 }
 
-// One emphasis run, the innermost, or every highlight run the line cannot spell.
-function unspellableRuns(segments: readonly InlineSegment[], output: string, placements: readonly number[]): MarkRun[] {
+function unspellableRun(segments: readonly InlineSegment[], output: string, placements: readonly number[]): NodeRange | undefined {
   const { nodes, runs } = emittedRuns(segments, placements, output)
   const pair = misflanked(runs) ?? unpaired(runs)
-  const run = pair === undefined ? undefined : nodes[pair]
-  return run === undefined ? unreadHighlights(segments, output, placements) : [run]
-}
-
-// No `==` in text can open or close, and highlights never nest, so a pair reads back where each delimiter flanks.
-function unreadHighlights(segments: readonly InlineSegment[], output: string, placements: readonly number[]): MarkRun[] {
-  const unread: MarkRun[] = []
-  let cursor = 0
-  for (const segment of segments) {
-    const start = placements[cursor] ?? 0
-    cursor += segment.text.length
-    if (segment.highlight === undefined) continue
-    const flanking = highlightFlanking(output, start)
-    const flanks = segment.highlight === 'open' ? flanking.opens : flanking.closes
-    if (!flanks && unread.at(-1) !== segment.nodes) unread.push(segment.nodes)
-  }
-  return unread
+  return pair === undefined ? undefined : nodes[pair]
 }
 
 function misflanked(runs: readonly EmittedRun[]): number | undefined {
@@ -201,9 +168,9 @@ function delimiterAt(run: EmittedRun, closes: boolean, offset: number, width: nu
   return run.delimiters.find((delimiter) => delimiter.closes === closes && delimiter.offset === offset && delimiter.width === width)
 }
 
-function emittedRuns(segments: readonly InlineSegment[], placements: readonly number[], output: string): { nodes: MarkRun[]; runs: EmittedRun[] } {
+function emittedRuns(segments: readonly InlineSegment[], placements: readonly number[], output: string): { nodes: NodeRange[]; runs: EmittedRun[] } {
   const runs: EmittedRun[] = []
-  const nodes: MarkRun[] = []
+  const nodes: NodeRange[] = []
   const open: number[] = []
   let cursor = 0
   for (const segment of segments) {
@@ -265,10 +232,10 @@ function opensConstruct(
   index: number,
   inBrackets: boolean,
   container: LineContainer,
-  afterEscape: boolean,
+  escaped: ReadonlySet<number>,
 ): boolean {
   if (container === 'heading' && closesHeading(scan, index)) return true
-  return claimsCharacter(scan, linkClose, index, inBrackets, container, afterEscape)
+  return claimsCharacter(scan, linkClose, index, inBrackets, container, escaped)
 }
 
 // A hard break is the one spelling that puts a delimiter row under a row of its own, so only a later line claims.
@@ -294,7 +261,7 @@ function claimsCharacter(
   index: number,
   inBrackets: boolean,
   container: LineContainer,
-  afterEscape: boolean,
+  escaped: ReadonlySet<number>,
 ): boolean {
   const character = scan.charAt(index)
   if (inBrackets && (character === '[' || character === ']')) return true
@@ -304,8 +271,8 @@ function claimsCharacter(
   if (character === '<') return opensBracketedAutolink(scan, index) || opensEmailAutolink(scan, index) || inlineHtmlConstruct(scan, index) !== undefined
   if (character === '!') return claimsDirectivePrefix(scan, index)
   if (character === '[') return index < linkClose
-  if (character === '`') return opensCodeSpan(scan, index, afterEscape)
-  if (character === '*' || character === '_' || character === '~') return claimsEmphasis(scan, index, afterEscape)
+  if (character === '`') return opensCodeSpan(scan, index, escaped)
+  if (character === '*' || character === '_' || character === '~') return claimsEmphasis(scan, index, escaped)
   return false
 }
 
@@ -318,16 +285,16 @@ function lastLinkClose(scan: string, escapings: readonly (InlineEscaping | undef
   return -1
 }
 
-function opensCodeSpan(scan: string, index: number, afterEscape: boolean): boolean {
+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 (afterEscape && scan.charAt(index - 1) === '`') return true
-  if (!startsRun(scan, index, afterEscape)) return false
+  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
 }
 
-function claimsEmphasis(scan: string, index: number, afterEscape: boolean): boolean {
-  if (!startsRun(scan, index, afterEscape)) return false
+function claimsEmphasis(scan: string, index: number, escaped: ReadonlySet<number>): boolean {
+  if (!startsRun(scan, index, escaped)) return false
   const character = scan.charAt(index)
   const length = runLength(scan, index)
   if (character === '~' && length !== 2) return false
@@ -335,8 +302,8 @@ function claimsEmphasis(scan: string, index: number, afterEscape: boolean): bool
   return flags.canClose || flags.canOpen
 }
 
-function startsRun(scan: string, index: number, afterEscape: boolean): boolean {
-  if (index === 0 || afterEscape) return true
+function startsRun(scan: string, index: number, escaped: ReadonlySet<number>): boolean {
+  if (index === 0 || escaped.has(index - 1)) return true
   return scan.charAt(index - 1) !== scan.charAt(index)
 }
 

src/markdown/emit/pipe-table.ts

@@ -1,11 +1,10 @@
 import type { AdfNode } from '../../adf/document.ts'
 import type { ConvertErrorPath } from '../../result.ts'
-import type { Flavour } from '../plain-conventions.ts'
 import { carriesOnly, nodeContent } from '../../adf/document.ts'
 import { spellPipeDelimiter, spellPipeRow } from '../pipe-table-syntax.ts'
 import { tryPipeCell } from './inline-line.ts'
 
-export function tryPipeTable(node: AdfNode, path: ConvertErrorPath, flavour: Flavour): string | undefined {
+export function tryPipeTable(node: AdfNode, path: ConvertErrorPath): string | undefined {
   const rows = pipeRows(node)
   if (rows === undefined) return undefined
   const lines: string[] = []
@@ -13,7 +12,7 @@ export function tryPipeTable(node: AdfNode, path: ConvertErrorPath, flavour: Fla
     const cells: string[] = []
     for (const [cellIndex, paragraph] of row.entries()) {
       const content = nodeContent(paragraph)
-      const line = content.length === 0 ? '' : tryPipeCell(content, [...path, 'content', rowIndex, 'content', cellIndex, 'content', 0], flavour)
+      const line = content.length === 0 ? '' : tryPipeCell(content, [...path, 'content', rowIndex, 'content', cellIndex, 'content', 0])
       if (line === undefined) return undefined
       cells.push(line)
     }

src/markdown/emit/plain-inline.ts

@@ -1,295 +0,0 @@
-import type { AdfAttributes, AdfMark, AdfNode } from '../../adf/document.ts'
-import type { LineContainer } from '../line-container.ts'
-import type { MarkRun } from './line-escaping.ts'
-import { blockNodeModel } from '../../adf/block-nodes.ts'
-import { failure, success, type ConvertErrorPath, type Result } from '../../result.ts'
-import { joinsNormally, sameMark } from '../../adf/editor-normal.ts'
-import { largestNesting } from '../../nesting.ts'
-import { mergeAdjacentText, nodeAttrs, nodeContent, nodeMarks } from '../../adf/document.ts'
-import { plainLineFallback, type PlainLineFallback } from './inline-line.ts'
-import { spellDestination, spellLinkTarget } from '../commonmark/link-syntax.ts'
-
-const highlight = 'backgroundColor'
-const highlightMark: AdfMark = { type: highlight }
-const edgeStrippingMarks: readonly string[] = [highlight, 'em', 'strike', 'strong']
-const keptMarks: readonly string[] = [...edgeStrippingMarks, 'code', 'link']
-
-export function reduceInline(nodes: readonly AdfNode[], container: LineContainer, path: ConvertErrorPath, depth: number): Result<AdfNode[]> {
-  const leaves = inlineLeaves(nodes, container, path, depth)
-  if (!leaves.ok) return leaves
-  return spellableLine(trimmedEdges(highlighted(trimmedEdges(leaves.value))), container, path)
-}
-
-export function isBlockNodeType(type: string): boolean {
-  return blockNodeModel(type) !== undefined || type === 'blockCard' || type === 'embedCard'
-}
-
-export function inlineLeaves(nodes: readonly AdfNode[], container: LineContainer, path: ConvertErrorPath, depth: number): Result<AdfNode[]> {
-  if (depth > largestNesting) return failure('unsupported-nesting-depth', `the document nests deeper than the ${largestNesting} levels the emitter carries`, path)
-  const leaves: AdfNode[] = []
-  let joinsNext = false
-  for (const [index, node] of nodes.entries()) {
-    const held = nodeLeaves(node, container, [...path, 'content', index], depth)
-    if (!held.ok) return held
-    if (held.value.length === 0) continue
-    const block = isBlockNodeType(node.type) && node.type !== 'media'
-    if (leaves.length > 0 && (joinsNext || block)) leaves.push(textLeaf(' ', []))
-    joinsNext = block
-    for (const leaf of held.value) leaves.push(leaf)
-  }
-  return success(leaves)
-}
-
-function nodeLeaves(node: AdfNode, container: LineContainer, path: ConvertErrorPath, depth: number): Result<AdfNode[]> {
-  const marks = nodeMarks(node)
-  const attrs = nodeAttrs(node)
-  if (node.type === 'text') return success(textLeaves(node.text, marks, container))
-  if (node.type === 'hardBreak') return success([lineBreak(container)])
-  if (node.type === 'date') return success(textLeaves(isoDate(attrs['timestamp']), marks, container))
-  if (node.type === 'emoji') return success(textLeaves(nonEmpty(attrs['text']) ?? attrs['shortName'], marks, container))
-  if (node.type === 'placeholder') return success([])
-  if (node.type === 'mention') return success(textLeaves(nonEmpty(attrs['text']) ?? idMention(attrs['id']), marks, container))
-  if (node.type === 'status') return success(textLeaves(attrs['text'], marks, container))
-  if (['extension', 'inlineExtension'].includes(node.type)) return success(textLeaves(nonEmpty(attrs['text']), marks, container, noteName(attrs['extensionKey']) ?? 'extension'))
-  if (node.type === 'syncBlock') return success(noteLeaves('synced block'))
-  if (['media', 'mediaInline'].includes(node.type)) return success(mediaLeaves(attrs, marks, container))
-  if (['blockCard', 'embedCard', 'inlineCard'].includes(node.type)) return success(cardLeaves(attrs, marks, container))
-  const own = textLeaves(node.text ?? (['expand', 'nestedExpand'].includes(node.type) ? attrs['title'] : undefined), marks, container)
-  const held = inlineLeaves(nodeContent(node), container, path, depth + 1)
-  if (!held.ok) return held
-  return success(own.length > 0 && held.value.length > 0 ? [...own, textLeaf(' ', []), ...held.value] : [...own, ...held.value])
-}
-
-function cardLeaves(attrs: Readonly<AdfAttributes>, marks: readonly AdfMark[], container: LineContainer): AdfNode[] {
-  const data = attrs['data']
-  const held = typeof data === 'object' && data !== null && !Array.isArray(data) ? data : {}
-  const url = nonEmpty(attrs['url'])
-  const heldUrl = nonEmpty(held['url'])
-  const name = nonEmpty(held['name'])
-  const href = url ?? heldUrl
-  if (href === undefined) return textLeaves(name, marks, container, 'link card')
-  return linkedLeaves(url ?? name ?? href, href, marks, container)
-}
-
-function linkedLeaves(text: string, href: string, marks: readonly AdfMark[], container: LineContainer): AdfNode[] {
-  return textLeaves(text, [...marks.filter((mark) => mark.type !== 'link'), { attrs: { href }, type: 'link' }], container)
-}
-
-function idMention(id: unknown): string | undefined {
-  return typeof id === 'string' && id !== '' ? `@${id}` : undefined
-}
-
-// An image standing inline is a link to it: CommonMark's inline image reads back as no node.
-function mediaLeaves(attrs: Readonly<AdfAttributes>, marks: readonly AdfMark[], container: LineContainer): AdfNode[] {
-  const alt = nonEmpty(attrs['alt'])
-  const url = nonEmpty(attrs['url'])
-  if (attrs['type'] !== 'external' || url === undefined) return textLeaves(alt, marks, container, 'image')
-  return linkedLeaves(alt ?? url, url, marks, container)
-}
-
-function noteLeaves(name: string): AdfNode[] {
-  return [textLeaf(`(${name} not included)`, [{ type: 'em' }])]
-}
-
-function noteName(value: unknown): string | undefined {
-  return nonEmpty(value) === undefined ? undefined : oneLine(String(value)).trim()
-}
-
-export function oneLine(text: string): string {
-  return text.replace(/[\r\u0000]/g, '').replace(/\n/g, ' ')
-}
-
-function nonEmpty(value: unknown): string | undefined {
-  return typeof value === 'string' && oneLine(value).trim() !== '' ? value : undefined
-}
-
-function isoDate(timestamp: unknown): string | undefined {
-  const milliseconds = typeof timestamp === 'string' && /^-?\d+$/.test(timestamp) ? Number(timestamp) : Number.NaN
-  const date = new Date(milliseconds)
-  if (Number.isNaN(date.getTime())) return undefined
-  const iso = date.toISOString()
-  return iso.slice(0, iso.indexOf('T'))
-}
-
-function lineBreak(container: LineContainer): AdfNode {
-  return container === 'paragraph' ? { type: 'hardBreak' } : textLeaf(' ', [])
-}
-
-function textLeaves(value: unknown, marks: readonly AdfMark[], container: LineContainer, note?: string): AdfNode[] {
-  if (typeof value !== 'string') return note === undefined ? [] : noteLeaves(note)
-  const text = value.replace(/[\r\u0000]/g, '')
-  const kept = plainMarks(marks, container, text)
-  const leaves: AdfNode[] = []
-  for (const [index, line] of text.split('\n').entries()) {
-    if (index > 0) leaves.push(lineBreak(container))
-    if (line !== '') leaves.push(textLeaf(line, kept))
-  }
-  return leaves
-}
-
-function textLeaf(text: string, marks: readonly AdfMark[]): AdfNode {
-  return marks.length === 0 ? { text, type: 'text' } : { marks: [...marks], text, type: 'text' }
-}
-
-// A highlight goes first, where `highlighted` looks for it, and code last, the only place its spelling holds.
-function plainMarks(marks: readonly AdfMark[], container: LineContainer, text: string): AdfMark[] {
-  const kept: AdfMark[] = []
-  for (const mark of marks) {
-    if (!keptMarks.includes(mark.type) || kept.some((held) => held.type === mark.type)) continue
-    if (mark.type === 'code' && container === 'table-cell' && text.includes('|')) continue
-    const plain = mark.type === 'link' ? plainLink(mark, container) : { type: mark.type }
-    if (plain !== undefined) kept.push(plain)
-  }
-  const rank = (mark: AdfMark): number => (mark.type === highlight ? 0 : mark.type === 'code' ? 2 : 1)
-  // The reader highlights no code, as Atlassian's schema allows none.
-  const code = kept.some((mark) => mark.type === 'code')
-  return kept.filter((mark) => !code || mark.type !== highlight).sort((first, second) => rank(first) - rank(second))
-}
-
-function plainLink(mark: AdfMark, container: LineContainer): AdfMark | undefined {
-  const attrs = nodeAttrs(mark)
-  const held = attrs['href']
-  const title = typeof attrs['title'] === 'string' ? attrs['title'].replace(/\r/g, '').replace(/\n/g, ' ') : undefined
-  if (typeof held !== 'string') return undefined
-  const href = writableHref(container === 'table-cell' ? held.replaceAll('|', '%7C') : held)
-  if (title === undefined || spellLinkTarget(href, title) === undefined || (container === 'table-cell' && title.includes('|'))) return { attrs: { href }, type: 'link' }
-  return { attrs: { href, title }, type: 'link' }
-}
-
-// spec/flavour.md, Links: the characters no destination spelling holds, then an ampersand an entity reference would read.
-export function writableHref(href: string): string {
-  let written = href
-  for (const unwritable of [/[\u0000-\u001f\u007f\\<>]/g, /&/g]) {
-    if (spellDestination(written) !== undefined) return written
-    written = written.replace(unwritable, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase().padStart(2, '0')}`)
-  }
-  return written
-}
-
-// The marks a whole highlight run shares go outside the highlight, so its delimiters open and close inside them.
-function highlighted(leaves: readonly AdfNode[]): AdfNode[] {
-  const spelled: AdfNode[] = []
-  let run: AdfNode[] = []
-  let shared: AdfMark[] = []
-  for (const leaf of [...leaves, { type: 'hardBreak' }]) {
-    const marks = nodeMarks(leaf)
-    if (marks[0]?.type === highlight) {
-      const held = marks.slice(1)
-      shared = run.length === 0 ? held : shared.filter((mark) => held.some((other) => sameMark(other, mark)))
-      run.push(leaf)
-      continue
-    }
-    for (const held of run) spelled.push(withMarks(held, [...shared, highlightMark, ...nodeMarks(held).slice(1).filter((mark) => !shared.some((other) => sameMark(other, mark)))]))
-    run = []
-    spelled.push(leaf)
-  }
-  return spelled.slice(0, -1)
-}
-
-function withMarks(leaf: AdfNode, marks: readonly AdfMark[]): AdfNode {
-  const { marks: _, ...unmarked } = leaf
-  return marks.length === 0 ? unmarked : { ...unmarked, marks: [...marks] }
-}
-
-function trimmedEdges(leaves: readonly AdfNode[]): AdfNode[] {
-  for (let current = leaves; ; ) {
-    const merged = withoutEdgeBreaks(mergeAdjacentText(current, joinsNormally))
-    let changed = false
-    const trimmed: AdfNode[] = []
-    for (const [index, leaf] of merged.entries()) {
-      const edges = leafEdges(leaf, merged[index - 1], merged[index + 1])
-      if (edges === undefined) {
-        trimmed.push(leaf)
-        continue
-      }
-      changed = true
-      for (const edge of edges) trimmed.push(edge)
-    }
-    if (!changed) return merged
-    current = trimmed
-  }
-}
-
-function withoutEdgeBreaks(leaves: readonly AdfNode[]): AdfNode[] {
-  let first = 0
-  let last = leaves.length - 1
-  while (leaves[first]?.type === 'hardBreak') first += 1
-  while (last >= first && leaves[last]?.type === 'hardBreak') last -= 1
-  return leaves.slice(first, last + 1)
-}
-
-// spec/flavour.md, Inline nodes: edge whitespace leaves every stripping mark opening or closing beside it, and goes at a line edge.
-function leafEdges(leaf: AdfNode, previous: AdfNode | undefined, next: AdfNode | undefined): AdfNode[] | undefined {
-  const marks = nodeMarks(leaf)
-  const text = leaf.text
-  if (text === undefined || marks.some((mark) => mark.type === 'code')) return undefined
-  const lead = text.slice(0, text.search(/[^ \t]|$/))
-  const trail = text.slice(text.search(/[ \t]*$/))
-  const leadDepth = edgeDepth(marks, previous, lead)
-  const trailDepth = edgeDepth(marks, next, trail)
-  if (leadDepth === marks.length && trailDepth === marks.length) return undefined
-  if (lead === text) return leadDepth === undefined || trailDepth === undefined ? [] : [textLeaf(text, marks.slice(0, Math.min(leadDepth, trailDepth)))]
-  const edges: AdfNode[] = []
-  if (lead !== '' && leadDepth !== undefined) edges.push(textLeaf(lead, marks.slice(0, leadDepth)))
-  const core = text.slice(lead.length, text.length - trail.length)
-  if (core !== '') edges.push(textLeaf(core, marks))
-  if (trail !== '' && trailDepth !== undefined) edges.push(textLeaf(trail, marks.slice(0, trailDepth)))
-  return edges
-}
-
-function edgeDepth(marks: readonly AdfMark[], neighbour: AdfNode | undefined, whitespace: string): number | undefined {
-  if (whitespace === '') return marks.length
-  const lineEdge = neighbour === undefined || neighbour.type === 'hardBreak'
-  const neighbourMarks = lineEdge ? [] : nodeMarks(neighbour)
-  let shared = 0
-  while (shared < marks.length && sameMarkAt(marks, neighbourMarks, shared)) shared += 1
-  const stripping = marks.findIndex((mark, index) => index >= shared && edgeStrippingMarks.includes(mark.type))
-  const kept = stripping === -1 ? marks.length : stripping
-  return kept === 0 && lineEdge ? undefined : kept
-}
-
-function sameMarkAt(marks: readonly AdfMark[], others: readonly AdfMark[], index: number): boolean {
-  const mark = marks[index]
-  const other = others[index]
-  return mark !== undefined && other !== undefined && sameMark(mark, other)
-}
-
-function spellableLine(leaves: AdfNode[], container: LineContainer, path: ConvertErrorPath): Result<AdfNode[]> {
-  for (let current = leaves; ; ) {
-    const fallback = plainLineFallback(current, container, path)
-    if (!fallback.ok) return fallback
-    if (fallback.value === undefined) return success(current)
-    const fixed = withoutFallback(current, fallback.value)
-    if (fixed === undefined) return failure('unsupported-node-shape', 'a plain line keeps a spelling that dropping a mark does not change', path)
-    current = trimmedEdges(fixed)
-  }
-}
-
-function withoutFallback(leaves: readonly AdfNode[], fallback: PlainLineFallback): AdfNode[] | undefined {
-  if (fallback.kind === 'unspellable-run') return withoutMarks(leaves, fallback.runs)
-  const first = fallback.kind === 'opening-link' ? 0 : lineStart(leaves, fallback.line)
-  const mark = nodeMarks(leaves[first] ?? {})[0]
-  if (mark === undefined || mark.type !== (fallback.kind === 'opening-link' ? 'link' : 'code')) return undefined
-  let last = first
-  while (sameMarkAt(nodeMarks(leaves[last + 1] ?? {}), [mark], 0)) last += 1
-  // A code span is what binds the `]` a link definition reads, and dropping it keeps the link target.
-  const spans = leaves.slice(first, last + 1).some((leaf) => nodeMarks(leaf).length > 1 && nodeMarks(leaf).at(-1)?.type === 'code')
-  if (mark.type === 'link' && spans) return leaves.map((leaf, index) => (index < first || index > last ? leaf : withMarks(leaf, nodeMarks(leaf).filter((held) => held.type !== 'code'))))
-  return withoutMarks(leaves, [{ depth: 0, first, last }])
-}
-
-function lineStart(leaves: readonly AdfNode[], line: number): number {
-  let index = 0
-  for (let breaks = 0; breaks < line && index < leaves.length; index += 1) if (leaves[index]?.type === 'hardBreak') breaks += 1
-  return index
-}
-
-// The runs cover disjoint leaves, so one pass drops them all.
-function withoutMarks(leaves: readonly AdfNode[], runs: readonly MarkRun[]): AdfNode[] {
-  const depths = new Map<number, number>()
-  for (const run of runs) for (let index = run.first; index <= run.last; index += 1) depths.set(index, run.depth)
-  return leaves.map((leaf, index) => {
-    const depth = depths.get(index)
-    return depth === undefined ? leaf : withMarks(leaf, nodeMarks(leaf).filter((_, held) => held !== depth))
-  })
-}

src/markdown/emit/plain-reduction.test.ts

@@ -1,340 +0,0 @@
-import assert from 'node:assert/strict'
-import test from 'node:test'
-
-import type { AdfAttributes, AdfDocument, AdfMark, AdfNode } from '../../adf/document.ts'
-import { adfToPlainMarkdown, reduceToPlain } from './plain-reduction.ts'
-import { largestNesting } from '../../nesting.ts'
-
-const code: AdfMark = { type: 'code' }
-const em: AdfMark = { type: 'em' }
-const strong: AdfMark = { type: 'strong' }
-
-function document(...content: AdfNode[]): AdfDocument {
-  return { content, type: 'doc', version: 1 }
-}
-
-function plain(...content: AdfNode[]): string {
-  return plainDocument(document(...content))
-}
-
-function plainDocument(input: AdfDocument): string {
-  const markdown = adfToPlainMarkdown(input)
-  return markdown.ok ? markdown.value : `${markdown.error.code} at /${markdown.error.path.join('/')}`
-}
-
-function text(value: string, ...marks: AdfMark[]): AdfNode {
-  return marks.length === 0 ? { text: value, type: 'text' } : { marks, text: value, type: 'text' }
-}
-
-function node(type: string, attrs: AdfAttributes, ...content: AdfNode[]): AdfNode {
-  return { attrs, content, type }
-}
-
-function paragraph(...content: AdfNode[]): AdfNode {
-  return { content, type: 'paragraph' }
-}
-
-function said(value: string): AdfNode {
-  return paragraph(text(value))
-}
-
-function item(...content: AdfNode[]): AdfNode {
-  return { content, type: 'listItem' }
-}
-
-function bulletList(...content: AdfNode[]): AdfNode {
-  return { content, type: 'bulletList' }
-}
-
-function cell(type: string, ...content: AdfNode[]): AdfNode {
-  return { content, type }
-}
-
-function row(...content: AdfNode[]): AdfNode {
-  return { content, type: 'tableRow' }
-}
-
-function link(href: string, title?: string): AdfMark {
-  return { attrs: title === undefined ? { href } : { href, title }, type: 'link' }
-}
-
-test('refuses what the document guard refuses, and nothing else', () => {
-  assert.equal(plainDocument({ type: 'doc', version: Number.NaN }), 'not-an-adf-document at /')
-  assert.equal(plainDocument({ type: 'doc', version: 2 }), 'unsupported-document-version at /')
-  let deep: AdfNode = said('x')
-  for (let level = 0; level <= largestNesting; level += 1) deep = { content: [deep], type: 'layoutColumn' }
-  assert.match(plainDocument(document(deep)), /^unsupported-nesting-depth at \/content\/0(\/content\/0)+$/)
-  assert.match(plainDocument(document(paragraph(text('a'), text('b')), text('c'), text('d'), deep)), /^unsupported-nesting-depth at \/content\/3(\/content\/0)+$/)
-  let deepInline: AdfNode = text('x')
-  for (let level = 0; level <= largestNesting; level += 1) deepInline = { content: [deepInline], type: 'unknownInline' }
-  assert.match(plainDocument(document(paragraph(deepInline))), /^unsupported-nesting-depth at /)
-})
-
-test('refuses nesting past 500 levels wherever the reduction walks', () => {
-  const lowest = (bottom: AdfNode): string => {
-    let deep = bottom
-    for (let level = 0; level < largestNesting; level += 1) deep = { content: [deep], type: 'layoutColumn' }
-    return plainDocument(document(deep)).split(' ')[0] ?? ''
-  }
-  const wrapped: AdfNode = { content: [text('x')], type: 'unknownInline' }
-  const bottoms: AdfNode[] = [
-    bulletList(item(said('x'))),
-    node('taskList', {}, node('taskList', {}, node('taskItem', {}, text('x')))),
-    node('taskList', {}, node('taskItem', {}, wrapped)),
-    node('taskList', {}, node('blockTaskItem', {}, said('x'))),
-    node('panel', {}, said('x')),
-    node('expand', {}, said('x')),
-    node('decisionList', {}, node('decisionItem', {}, text('x'))),
-    node('table', {}, row(cell('tableCell', said('x')))),
-    node('mediaSingle', {}, node('caption', {}, text('x'))),
-    node('heading', { level: 1 }, wrapped),
-    node('codeBlock', {}, wrapped),
-    paragraph(wrapped),
-  ]
-  for (const bottom of bottoms) assert.equal(lowest(bottom), 'unsupported-nesting-depth', bottom.type)
-})
-
-test('spells a panel as an alert in the GitHub word for its colour', () => {
-  const panel = (panelType: string | undefined): string =>
-    plain(node('panel', panelType === undefined ? {} : { localId: '01a0d99b-1f56-7a50-889a-f4375f09ee05', panelType }, said('Check it.')))
-  assert.equal(panel('info'), '> [!NOTE]\n>\n> Check it.\n')
-  assert.equal(panel('note'), '> [!IMPORTANT]\n>\n> Check it.\n')
-  assert.equal(panel('tip'), '> [!TIP]\n>\n> Check it.\n')
-  assert.equal(panel('success'), '> [!TIP]\n>\n> Check it.\n')
-  assert.equal(panel('warning'), '> [!WARNING]\n>\n> Check it.\n')
-  assert.equal(panel('error'), '> [!CAUTION]\n>\n> Check it.\n')
-  assert.equal(panel('custom'), '> [!NOTE]\n>\n> Check it.\n')
-  assert.equal(panel(undefined), '> [!NOTE]\n>\n> Check it.\n')
-  assert.equal(plain(node('panel', { panelType: 'warning' })), '> [!WARNING]\n')
-})
-
-test('spells an expand and a nested expand as a folded callout titled by the marker line', () => {
-  const nested = node('nestedExpand', { title: 'Inner' }, said('Deep.'))
-  assert.equal(
-    plain(node('expand', { localId: '01a0d99b-1f57-7fec-94ae-50c2ee25c9de', title: 'Build log' }, said('Line.'), nested)),
-    '> [!NOTE]- Build log\n>\n> Line.\n>\n> > [!NOTE]- Inner\n> >\n> > Deep.\n',
-  )
-  assert.equal(plain(node('expand', {}, said('Line.'))), '> [!NOTE]-\n>\n> Line.\n')
-  assert.equal(plain(node('expand', { title: ' *Two*\nlines ' })), '> [!NOTE]- \\*Two\\* lines\n')
-  assert.equal(plain(node('expand', { title: '\ta \t b\t ' })), '> [!NOTE]- a \t b\n')
-  assert.equal(plain(node('expand', { title: '**x** [y](z) ==w==' }, said('b'))), '> [!NOTE]- \\*\\*x\\*\\* \\[y](z) ==w==\n>\n> b\n')
-})
-
-test('spells a task list as a bullet list whose items lead with their state', () => {
-  const task = (state: string, value: string): AdfNode => node('taskItem', { localId: '01a0d99b-1f58-7b95-829b-6f9860371d54', state }, text(value))
-  const nested = node('taskList', {}, task('TODO', 'Review'))
-  assert.equal(plain(node('taskList', {}, task('DONE', 'Write the spec'), nested, task('TODO', 'Ship it'))), '- [x] Write the spec\n  - [ ] Review\n- [ ] Ship it\n')
-  assert.equal(plain(node('taskList', {}, nested, task('DONE', ''), said('Stray'))), '- - [ ] Review\n- \\[x]\n- Stray\n')
-  assert.equal(plain(node('taskList', {}, node('taskList', {}), task('DONE', 'a'), said('b'), node('taskList', {}, task('TODO', 'c')))), '- \\[x] a\n- b\n  - [ ] c\n')
-  assert.equal(plain(node('taskList', {}, paragraph(), task('DONE', 'a'))), '- [x] a\n')
-  assert.equal(plain(bulletList(item(said('x'))), node('taskList', {}, task('DONE', 'a'), node('taskList', {}, task('TODO', 'c')))), '- x\n- \\[x] a\n  - [ ] c\n')
-  assert.equal(plain(node('taskList', {}), task('TODO', 'Loose')), 'Loose\n')
-  const blockTask = node('blockTaskItem', { state: 'DONE' }, said('First.'), said('Second.'))
-  const codeTask = node('blockTaskItem', { state: 'TODO' }, { content: [text('x')], type: 'codeBlock' })
-  assert.equal(plain(node('taskList', {}, blockTask, codeTask)), '- [x] First.\n\n  Second.\n- [ ]\n\n  ```\n  x\n  ```\n')
-  const listTask = node('blockTaskItem', { state: 'DONE' }, bulletList(item(said('a'))))
-  assert.equal(plain(node('taskList', {}, task('TODO', ''), listTask, node('taskList', {}, task('TODO', 'b')))), '- [ ]\n- [x]\n  - a\n  - \\[ ] b\n')
-  assert.equal(plain(node('taskList', {}, task('DONE', 'a'), node('taskList', {}, task('TODO', '')))), '- [x] a\n  - [ ]\n')
-})
-
-test('spells a decision list as a plain bullet list', () => {
-  assert.equal(plain(node('decisionList', {}, node('decisionItem', { state: 'DECIDED' }, text('Ship')), said('Stray'))), '- Ship\n- Stray\n')
-})
-
-test('spells a highlight as a == pair around the run, whatever its colour', () => {
-  const highlight = (color: string): AdfMark => ({ attrs: { color }, type: 'backgroundColor' })
-  assert.equal(plain(paragraph(text('a '), text('hi', highlight('#fff')), text(' there', highlight('#000')), text(' b'))), 'a ==hi there== b\n')
-  assert.equal(plain(paragraph(text('hi ', strong, highlight('#fff')), text('b'))), '**==hi==** b\n')
-  assert.equal(plain(paragraph(text('a', strong, highlight('#fff')), text('b', highlight('#fff'), em))), '==**a**_b_==\n')
-  assert.equal(plain(paragraph(text('a', highlight('#fff'), code), text('b', highlight('#fff')))), '`a`==b==\n')
-  assert.equal(plain(paragraph(text('=', highlight('#fff')), text(' '), text('a==b', highlight('#fff')))), '==\\=== ==a==b==\n')
-  assert.equal(plain(paragraph(text('x'), text('y', highlight('#fff')), text(' z'))), 'xy z\n')
-  assert.equal(plain(paragraph(text('この機能は'), text('日本語', highlight('#fff')), text('でのみ'))), 'この機能は==日本語==でのみ\n')
-  assert.equal(plain(paragraph(text('サーバー'), text('停止', highlight('#fff')), text('中 iPhone'), text('専用', highlight('#fff')), text('アプリ 기능은 '), text('한국어', highlight('#fff')), text('에서만'))), 'サーバー==停止==中 iPhone==専用==アプリ 기능은 ==한국어==에서만\n')
-  assert.equal(plain(paragraph(text('日==本==語'))), '日\\==本\\==語\n')
-})
-
-test('escapes text a renderer would take as a flavour marker, and only there', () => {
-  assert.equal(plain(said('==x== a == b a==b ===')), '\\==x\\== a == b a==b \\=\\==\n')
-  assert.equal(plain({ content: [said('[!NOTE] x'), said('[!TIP]')], type: 'blockquote' }), '> \\[!NOTE] x\n>\n> [!TIP]\n')
-  assert.equal(plain({ content: [said('[!NOTE]x')], type: 'blockquote' }, said('[!NOTE]')), '> [!NOTE]x\n\n[!NOTE]\n')
-  assert.equal(plain(bulletList(item(said('[x] a')), item(said('[ ]')))), '- \\[x] a\n- \\[ ]\n')
-  assert.equal(plain(bulletList(item(said('[x] a')), item(said('b'))), node('orderedList', { order: 1 }, item(said('[x] c')))), '- \\[x] a\n- b\n\n1. \\[x] c\n')
-  const task = (state: string, value: string): AdfNode => node('taskItem', { state }, text(value))
-  assert.equal(plain(node('taskList', {}, task('DONE', '[x] a'), task('TODO', '==b=='))), '- [x] [x] a\n- [ ] \\==b\\==\n')
-})
-
-test('unwraps the containers plain markdown has no spelling for to their body blocks in order', () => {
-  const column = (value: string): AdfNode => node('layoutColumn', { width: 50 }, said(value))
-  assert.equal(plain(node('layoutSection', {}, column('Left.'), column('Right.'))), 'Left.\n\nRight.\n')
-  assert.equal(plain(node('bodiedExtension', { extensionKey: 'k' }, said('Body.'))), 'Body.\n')
-  assert.equal(plain(node('bodiedSyncBlock', { resourceId: 'r' }, said('Synced.'))), 'Synced.\n')
-  const frame = (value: string): AdfNode => node('extensionFrame', {}, said(value))
-  assert.equal(plain(node('multiBodiedExtension', { extensionKey: 'k' }, frame('One.'), frame('Two.'))), 'One.\n\nTwo.\n')
-})
-
-test('keeps the CommonMark blocks in their spelling and drops their attributes and marks', () => {
-  const localId = { localId: '01a0d99b-1f56-7a50-889a-f4375f09ee05' }
-  assert.equal(plain(node('paragraph', localId, text('x')), node('heading', { level: 2, localId: '01a0d99b-1f57-7fec-94ae-50c2ee25c9de' }, text('h'))), 'x\n\n## h\n')
-  assert.equal(plain({ attrs: localId, content: [said('q')], marks: [{ type: 'breakout' }], type: 'blockquote' }), '> q\n')
-  assert.equal(plain(node('codeBlock', { language: 'ts', wrap: true }, text('a\r\nb\u0000'))), '```ts\na\nb\n```\n')
-  assert.equal(plain(node('codeBlock', { language: 'adf:x' }, text('a'), { type: 'hardBreak' }, text('b', strong))), '```\na\nb\n```\n')
-  assert.equal(plain(node('codeBlock', {})), '```\n```\n')
-  assert.equal(plain(node('rule', { color: '#000' })), '---\n')
-  assert.equal(plain(node('orderedList', { localId: '01a0d99b-1f58-7b95-829b-6f9860371d54', order: 3 }, item(said('c')))), '3. c\n')
-  assert.equal(plain(node('orderedList', {}, item(said('a')))), '1. a\n')
-  assert.equal(plain(node('orderedList', { order: -1 }, item(said('a')))), '1. a\n')
-  const code: AdfNode = { content: [text('x')], type: 'codeBlock' }
-  assert.equal(plain(node('orderedList', { order: 1e10 }, item(said('Alpha')), item(code), item())), '- 10000000000. Alpha\n- 10000000001.\n\n  ```\n  x\n  ```\n- 10000000002.\n')
-  const long = node('orderedList', { order: 1e10 }, item(said('y')))
-  assert.equal(plain(bulletList(item(said('x'))), long, bulletList(item(said('z')))), '- x\n- 10000000000. y\n- z\n')
-  assert.equal(plain(node('taskList', {}, node('taskItem', { state: 'DONE' }, text('t'))), long), '- \\[x] t\n- 10000000000. y\n')
-  assert.equal(plain(bulletList(item(said('a'), bulletList(item(said('x'))), long))), '- a\n  - x\n  - 10000000000. y\n')
-  const givesWay = node('orderedList', { order: 1e10 }, item(node('rule', {})), item(bulletList(item(bulletList(item())))))
-  assert.equal(plain(givesWay, bulletList(item(said('z')))), '- 10000000000.\n- 10000000001.\n  - -\n- z\n')
-  assert.equal(plain(node('orderedList', { order: 999999999 }, item(said('a'))), node('orderedList', { order: 5 }, item(said('b')))), '- 999999999\\. a\n- 5\\. b\n')
-  assert.equal(plain(node('heading', { level: 7 }, text('h'))), 'h\n')
-})
-
-test('spells an inline node as its text', () => {
-  assert.equal(plain(paragraph(node('mention', { id: 'a', text: '@Mikael' }), text(' and '), node('status', { color: 'red', text: 'Blocked' }))), '@Mikael and Blocked\n')
-  assert.equal(plain(paragraph(node('emoji', { shortName: ':tada:', text: '🎉' }), node('emoji', { shortName: ':smile:' }))), '🎉:smile:\n')
-  assert.equal(plain(paragraph(node('date', { timestamp: '1757721600000' }), text(' '), node('date', { timestamp: 'soon' }))), '2025-09-13\n')
-  assert.equal(plain(paragraph({ marks: [strong], ...node('mention', { text: '@Mikael' }) })), '**@Mikael**\n')
-  assert.equal(plain(paragraph(text('by '), node('mention', { id: '5b10a2' }), node('mention', {}))), 'by @5b10a2\n')
-})
-
-test('spells a card as a link to its url, or to its data url named by its data name, else a note', () => {
-  assert.equal(plain(paragraph(node('inlineCard', { url: 'https://example.com' }))), '<https://example.com>\n')
-  assert.equal(plain(paragraph({ ...node('inlineCard', { url: 'https://example.com' }), marks: [strong, link('https://other.com')] })), '**<https://example.com>**\n')
-  assert.equal(plain(paragraph(text('see '), node('inlineCard', { data: {} }))), 'see _(link card not included)_\n')
-  assert.equal(plain(paragraph(node('inlineCard', { data: { name: 'Spec', url: 'https://e.com/s' } }), text(' '), node('inlineCard', { data: { url: 'https://e.com/u' } }))), '[Spec](https://e.com/s) <https://e.com/u>\n')
-  assert.equal(plain(paragraph(node('inlineCard', { data: { name: 'Spec' } }), text(' '), node('inlineCard', { data: ['x'] }))), 'Spec _(link card not included)_\n')
-  assert.equal(plain(node('blockCard', { url: 'https://example.com/a b' })), '[https://example.com/a b](<https://example.com/a b>)\n')
-  assert.equal(plain(node('embedCard', { layout: 'center', url: 'https://example.com' })), '<https://example.com>\n')
-  assert.equal(plain(node('blockCard', { data: {} })), '_(link card not included)_\n')
-})
-
-test('keeps an external image wherever it stands and spells a stored file as its alt text, else a note', () => {
-  const media = (attrs: AdfAttributes): AdfNode => ({ attrs, type: 'media' })
-  const caption: AdfNode = node('caption', {}, text('The moon.'))
-  const external = media({ alt: 'Moon', height: 10, type: 'external', url: 'https://example.com/moon.png' })
-  assert.equal(plain(node('mediaSingle', { layout: 'wide', width: 50 }, external, caption)), '![Moon](https://example.com/moon.png)\n\nThe moon.\n')
-  assert.equal(plain(node('mediaSingle', {}, media({ alt: '', type: 'external', url: 'https://example.com/a.png' }))), '![](https://example.com/a.png)\n')
-  assert.equal(plain(node('mediaSingle', {}, media({ alt: ' Two\nlines ', type: 'external', url: 'u' }), media({ type: 'external', url: 'v' }))), '![Two lines](u)\n\n![](v)\n')
-  assert.equal(plain(node('mediaSingle', {}, media({ alt: 'Bad', type: 'external', url: 'a\\b <&amp;>' }))), '![Bad](<a%5Cb %3C%26amp;%3E>)\n')
-  assert.equal(plain(node('mediaSingle', {}, media({ alt: 'Photo', collection: 'c', id: 'i', type: 'file' }))), 'Photo\n')
-  assert.equal(plain(node('mediaGroup', {}, media({ alt: 'One', type: 'file' }), media({ type: 'file' }), external)), 'One\n\n_(image not included)_\n\n![Moon](https://example.com/moon.png)\n')
-  assert.equal(plain(external), '![Moon](https://example.com/moon.png)\n')
-  assert.equal(plain(paragraph(text('a '), node('mediaInline', { alt: 'clip', type: 'file' }), text(' '), node('mediaInline', { type: 'file' }))), 'a clip _(image not included)_\n')
-  assert.equal(plain(paragraph(text('See '), external, text(' for '), node('mediaInline', { type: 'external', url: 'https://e.com/i.png' }))), 'See [Moon](https://example.com/moon.png) for <https://e.com/i.png>\n')
-  assert.equal(plain(caption), 'The moon.\n')
-})
-
-test('spells an extension as its text attribute, else a note naming it, and a placeholder as nothing', () => {
-  assert.equal(plain(node('extension', { extensionKey: 'toc', text: 'Contents' }), node('extension', { extensionKey: 'jira-issues-table' })), 'Contents\n\n_(jira-issues-table not included)_\n')
-  assert.equal(plain(node('syncBlock', { resourceId: 'r' })), '_(synced block not included)_\n')
-  assert.equal(plain(node('extension', { extensionKey: 'jira\r\nissues\u0000' })), '_(jira issues not included)_\n')
-  assert.equal(plain(node('extension', { extensionKey: '\r\u0000' }), node('extension', { extensionKey: '\n' })), '_(extension not included)_\n\n_(extension not included)_\n')
-  const blank = paragraph(node('inlineExtension', { extensionKey: 'k', text: '\r' }), text(' '), node('mediaInline', { alt: '\u0000', type: 'file' }), text(' '), node('mention', { id: '5b10a2', text: '\r' }))
-  assert.equal(plain(blank), '_(k not included)_ _(image not included)_ @5b10a2\n')
-  assert.equal(plain(paragraph(text('a '), node('inlineExtension', { text: 'macro' }), text(' '), node('inlineExtension', {}), node('placeholder', { text: 'Type here' }))), 'a macro _(extension not included)_\n')
-})
-
-test('spells a node no row names, or one standing where no spelling holds it, as its blocks or its text', () => {
-  assert.equal(plain(node('futureBlock', {}, said('Inside.'))), 'Inside.\n')
-  assert.equal(plain(paragraph(text('a '), { content: [text('b')], text: 'c', type: 'futureInline' })), 'a c b\n')
-  assert.equal(plain(text('loose'), node('mention', { text: '@x' }), node('listItem', {}, said('item'))), 'loose@x\n\nitem\n')
-  assert.equal(plain(paragraph(text('a '), node('bulletList', {}, item(said('b')), item(said('c'))))), 'a  b c\n')
-  assert.equal(plain(bulletList(said('stray'), item(said('b')), text('loose'))), '- stray\n- b\n- loose\n')
-  assert.equal(plain(bulletList()), '')
-  assert.equal(plain(bulletList(item({ content: [text('a\n  \nb')], type: 'codeBlock' }))), '- ```\n  a\n\n  b\n  ```\n')
-  assert.equal(plain(bulletList(item({ content: [text(' ')], type: 'codeBlock' }))), '- ```\n  ```\n')
-  assert.equal(plain(bulletList(item(node('rule', {}), node('rule', {}), said('Install')), item(said('Configure')))), '- Install\n- Configure\n')
-  assert.equal(plain(bulletList(item(node('rule', {}), node('rule', {})), item(said('Configure')))), '-\n- Configure\n')
-  assert.equal(plain(bulletList(item(bulletList(item(bulletList(item())))))), '- -\n')
-  assert.equal(plain(node('nestedExpand', {}, node('tableCell', {}, said('c')))), '> [!NOTE]-\n>\n> c\n')
-})
-
-test('keeps a table as a pipe table headed by its first row, one line per cell', () => {
-  const table = node(
-    'table',
-    { layout: 'wide' },
-    row(cell('tableCell', said('Part')), cell('tableCell', said('Qty'))),
-    row(cell('tableHeader', said('Bolt'), bulletList(item(said('M8')))), { attrs: { background: '#fff' }, content: [paragraph(text('4'), { type: 'hardBreak' }, text('0'))], type: 'tableCell' }),
-  )
-  assert.equal(plain(table), '| Part | Qty |\n| --- | --- |\n| Bolt M8 | 4 0 |\n')
-  const spanned = node(
-    'table',
-    {},
-    row(cell('tableHeader', said('A')), cell('tableHeader', said('B')), cell('tableHeader', said('C'))),
-    row(node('tableCell', { colspan: 2, rowspan: 2 }, said('wide')), cell('tableCell', said('c'))),
-    row(cell('tableCell', said('d'))),
-    row(cell('tableCell')),
-  )
-  assert.equal(plain(spanned), '| A | B | C |\n| --- | --- | --- |\n| wide |  | c |\n|  |  | d |\n|  |  |  |\n')
-  const huge = node('table', {}, row(node('tableHeader', { colspan: 1e9, rowspan: 1e9 }, said('A')), cell('tableHeader', said('B'))), row(cell('tableCell', said('c'))))
-  assert.equal(plain(huge), '| A |  |  |  | B |\n| --- | --- | --- | --- | --- |\n| c |  |  |  |  |\n')
-  assert.equal(plain(node('table', {}, row(cell('tableHeader', paragraph(text('a|b', code), text(' '), text('x', link('https://e.com/|'))))))), '| a\\|b [x](https://e.com/%7C) |\n| --- |\n')
-  assert.equal(plain(node('table', {}, said('stray'))), '| stray |\n| --- |\n')
-  const titled = paragraph(text('t', link('https://e.com', 'a|b')))
-  const folded = [node('expand', { title: 'Log' }, said('x')), node('nestedExpand', {}, said('y'))]
-  assert.equal(plain(node('table', {}, row(cell('tableHeader', titled), cell('tableHeader', ...folded)))), '| [t](https://e.com) | Log x y |\n| --- | --- |\n')
-  assert.equal(plain(node('table', {}, row())), '')
-})
-
-test('keeps code, em, link, strike and strong and drops every other mark, keeping its text', () => {
-  const marks: AdfMark[] = [{ type: 'strike' }, { attrs: { type: 'sub' }, type: 'subsup' }, { type: 'underline' }, { attrs: { color: '#f00' }, type: 'textColor' }]
-  assert.equal(plain(paragraph(text('H'), text('2', ...marks), text('O', em, strong), text('!', { attrs: { size: 1 }, type: 'border' }))), 'H~~2~~_**O**_!\n')
-  assert.equal(plain(paragraph(text('x', code, strong), text(' '), text('y', { attrs: { x: 1 }, type: 'strong' }), text('z', em, em))), '**`x`** **y**_z_\n')
-  assert.equal(plain(paragraph(text('site', { attrs: { collection: 'c', href: 'https://e.com', id: 'i' }, type: 'link' }))), '[site](https://e.com)\n')
-})
-
-test('percent-encodes a link href no CommonMark escape writes until one does', () => {
-  assert.equal(plain(paragraph(text('a', link('a\\b')), text(' '), text('b', { attrs: { id: 'i' }, type: 'link' }), text(' '), text('c', link('/&amp;')))), '[a](a%5Cb) b [c](/%26amp;)\n')
-  assert.equal(plain(paragraph(text('t', link('https://e.com', 'two\nlines')), text(' '), text('u', link('https://e.com', 'a\\b')))), '[t](https://e.com "two lines") [u](https://e.com)\n')
-  assert.equal(plain(paragraph(text(']: a', link('/u'), code))), '[\\]: a](/u)\n')
-})
-
-test('drops the mark of a run CommonMark flanking or matching cannot spell', () => {
-  assert.equal(plain(paragraph(text('un'), text('-real', strong), text('istic'))), 'un-realistic\n')
-  assert.equal(plain(paragraph(text('a', em), text('b', strong), text('c', em))), '_a_**b**_c_\n')
-  assert.equal(plain(paragraph(text('x'), text('*', em), text('y'))), 'x\\*y\n')
-  const highlight: AdfMark = { type: 'backgroundColor' }
-  assert.equal(plain(paragraph(text('a'), text('b', highlight), text(' c'), text('d', highlight), text(' '), text('e', highlight))), 'ab cd ==e==\n')
-})
-
-test('breaks a line at a newline and trims whitespace at every edge CommonMark strips', () => {
-  assert.equal(plain(paragraph(text(' \n a \n b\n'))), 'a\\\nb\n')
-  assert.equal(plain(paragraph({ type: 'hardBreak' }, text('a'), { attrs: { text: '\n' }, type: 'hardBreak' }, text('b'), { type: 'hardBreak' })), 'a\\\nb\n')
-  assert.equal(plain(paragraph(text('a'), text(' b ', strong), text('c'))), 'a **b** c\n')
-  assert.equal(plain(paragraph(text(' '), text('b', strong), text(' \n'), text('c', strong), text(' '))), '**b**\\\n**c**\n')
-  assert.equal(plain(paragraph(text('a'), text(' b ', em, strong), text(' ', em), text('c', em))), 'a _**b**  c_\n')
-  assert.equal(plain(paragraph(text(' x ', code))), '`  x  `\n')
-  assert.equal(plain(node('heading', { level: 1 }, text(' h\ni '))), '# h i\n')
-  assert.equal(plain(paragraph(text('a\r\u0000b'))), 'ab\n')
-})
-
-test('drops the code mark of a span opening a line with backticks that read as a fence', () => {
-  assert.equal(plain(paragraph(text('``` x', code))), '\\`\\`\\` x\n')
-  assert.equal(plain(paragraph(text('a\n'), text('``` x', code))), 'a\\\n\\`\\`\\` x\n')
-  assert.equal(plain(paragraph(text('a '), text('``` x', code))), 'a ```` ``` x ````\n')
-})
-
-test('drops an empty paragraph and merges adjacent lists of one type', () => {
-  const ordered = (order: number, value: string): AdfNode => node('orderedList', { order }, item(said(value)))
-  assert.equal(plain(said('a'), paragraph(), paragraph(text('  ')), said('b')), 'a\n\nb\n')
-  assert.equal(plain(bulletList(item(said('a'))), paragraph(), node('decisionList', {}, node('decisionItem', {}, text('b')))), '- a\n- b\n')
-  assert.equal(plain(ordered(2, 'a'), ordered(3, 'b'), bulletList(item(said('c')))), '2. a\n3. b\n\n- c\n')
-  assert.equal(plain(bulletList(item(said('x'))), ordered(1, 'a'), ordered(5, 'b'), ordered(6, 'c')), '- x\n- 1\\. a\n- 5\\. b\n\n6. c\n')
-  assert.equal(plain(ordered(1, 'a'), ordered(1e10, 'y')), '- 1\\. a\n- 10000000000. y\n')
-  assert.equal(plain(node('taskList', {}, ordered(1e10, 'y')), bulletList(ordered(1e10, 'z'))), '- - 10000000000. y\n- - 10000000000. z\n')
-  const column = (list: AdfNode): AdfNode => node('layoutColumn', {}, list)
-  assert.equal(plain(node('layoutSection', {}, column(bulletList(item(said('a')))), column(bulletList(item(said('b')))))), '- a\n- b\n')
-})
-
-test('keeps the nodes the plain flavour spells and degrades only what it cannot', () => {
-  const tasks = node('taskList', {}, node('taskItem', { localId: '01a0d99b-1f58-7b95-829b-6f9860371d54', state: 'DONE' }, text('t')))
-  const reduced = reduceToPlain(document(node('panel', { localId: '01a0d99b-1f56-7a50-889a-f4375f09ee05', panelType: 'info' }, said('x')), tasks))
-  assert.deepEqual(reduced.ok ? reduced.value : undefined, document(node('panel', { panelType: 'info' }, said('x')), { content: [node('taskItem', { state: 'DONE' }, text('t'))], type: 'taskList' }))
-})

src/markdown/emit/plain-reduction.ts

@@ -1,405 +0,0 @@
-import type { AdfDocument, AdfNode } from '../../adf/document.ts'
-import { adfDocumentFault, nodeAttrs, nodeContent } from '../../adf/document.ts'
-import { commonMarkSpelling, largestListMarker, writeMarkdown, type SpellingMemo } from './adf-to-markdown.ts'
-import { blockNodeModel } from '../../adf/block-nodes.ts'
-import { failure, faulted, success, type ConvertErrorPath, type Result } from '../../result.ts'
-import { inlineLeaves, isBlockNodeType, oneLine, reduceInline, writableHref } from './plain-inline.ts'
-import { inlineNodeModel } from '../../adf/inline-nodes.ts'
-import { languageSlot } from '../code-language.ts'
-import { largestNesting } from '../../nesting.ts'
-import { taskMarker } from '../plain-conventions.ts'
-import { toEditorNormal } from '../../adf/editor-normal.ts'
-
-// depth: the level the node reduced stands at, counted as the emitter counts it.
-type Reduction = { depth: number; memo: SpellingMemo; path: ConvertErrorPath }
-
-type BlockReducer = (node: AdfNode, reduction: Reduction) => Result<AdfNode[]>
-
-type PlacedCell = { colspan: number; paragraph: AdfNode; rowspan: number }
-
-type Placed = { index: number; loose: AdfNode[] } | { index: number; loose?: undefined; node: AdfNode }
-
-const blockReducers: Readonly<Record<string, BlockReducer>> = {
-  blockCard: paragraphOfNode,
-  blockquote: (node, reduction) => contained({ type: 'blockquote' }, node, reduction),
-  bulletList: reduceList,
-  caption: (node, reduction) => paragraphOf(nodeContent(node), reduction),
-  codeBlock: reduceCodeBlock,
-  decisionList: (node, reduction) => reduceItems(node, reduction, (child, at) => (child.type === 'decisionItem' ? paragraphOf(nodeContent(child), at) : reduceStanding(child, at))),
-  embedCard: paragraphOfNode,
-  expand: reduceExpand,
-  extension: paragraphOfNode,
-  heading: reduceHeading,
-  media: reduceMedia,
-  mediaSingle: (node, reduction) => concatenated(nodeContent(node).map((child, index) => reduceStanding(child, childReduction(reduction, index)))),
-  nestedExpand: reduceExpand,
-  orderedList: reduceList,
-  panel: reducePanel,
-  paragraph: (node, reduction) => paragraphOf(nodeContent(node), reduction),
-  rule: () => success([{ type: 'rule' }]),
-  syncBlock: paragraphOfNode,
-  table: reduceTable,
-  taskList: reduceTaskList,
-}
-
-export function adfToPlainMarkdown(document: AdfDocument): Result<string> {
-  const reduced = reduceToPlain(document)
-  return reduced.ok ? writeMarkdown(reduced.value, 'plain') : reduced
-}
-
-export function reduceToPlain(document: AdfDocument): Result<AdfDocument> {
-  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}`, [])
-  // A refusal's path indexes the caller's document, so only the reduction's output normalizes (docs/decisions.md §Equality is deep).
-  const blocks = reduceBlocks(nodeContent(document), { depth: 0, memo: new Map(), path: [] })
-  return blocks.ok ? success({ content: nodeContent(toEditorNormal({ content: blocks.value, type: 'doc', version: 1 })).slice(), type: 'doc', version: 1 }) : blocks
-}
-
-function reduceBlocks(nodes: readonly AdfNode[], reduction: Reduction): Result<AdfNode[]> {
-  const placed: Placed[] = []
-  for (const [index, node] of nodes.entries()) {
-    const previous = placed[placed.length - 1]
-    if (!standsInline(node)) placed.push({ index, node })
-    else if (previous?.loose !== undefined) previous.loose.push(node)
-    else placed.push({ index, loose: [node] })
-  }
-  const blocks = concatenated(
-    placed.map((entry) => {
-      const at = { ...reduction, path: [...reduction.path, 'content', entry.index] }
-      return entry.loose === undefined ? reduceNode(entry.node, at) : paragraphOf(entry.loose, reduction)
-    }),
-  )
-  return blocks.ok ? plainSequence(blocks.value, reduction) : blocks
-}
-
-function reduceNode(node: AdfNode, reduction: Reduction): Result<AdfNode[]> {
-  if (reduction.depth > largestNesting) return failure('unsupported-nesting-depth', `the document nests deeper than the ${largestNesting} levels the emitter carries`, reduction.path)
-  const reducer = Object.hasOwn(blockReducers, node.type) ? blockReducers[node.type] : undefined
-  return (reducer ?? reduceBody)(node, reduction)
-}
-
-function reduceStanding(node: AdfNode, reduction: Reduction): Result<AdfNode[]> {
-  const blocks = standsInline(node) ? paragraphOf([node], reduction) : reduceNode(node, reduction)
-  return blocks.ok ? plainSequence(blocks.value, reduction) : blocks
-}
-
-function standsInline(node: AdfNode): boolean {
-  if (node.type === 'text' || inlineNodeModel(node.type) !== undefined) return true
-  return !isBlockNodeType(node.type) && node.content === undefined
-}
-
-function reduceBody(node: AdfNode, reduction: Reduction): Result<AdfNode[]> {
-  if (blockNodeModel(node.type)?.contentModel === 'inline') return paragraphOf(nodeContent(node), reduction)
-  return reduceBlocks(nodeContent(node), { ...reduction, depth: reduction.depth + 1 })
-}
-
-function childReduction(reduction: Reduction, index: number): Reduction {
-  return { ...reduction, depth: reduction.depth + 1, path: [...reduction.path, 'content', index] }
-}
-
-function concatenated(results: readonly Result<AdfNode[]>[]): Result<AdfNode[]> {
-  const blocks: AdfNode[] = []
-  for (const result of results) {
-    if (!result.ok) return result
-    for (const block of result.value) blocks.push(block)
-  }
-  return success(blocks)
-}
-
-// A list still taking the directive form gives way to its items' blocks.
-function plainSequence(blocks: readonly AdfNode[], reduction: Reduction): Result<AdfNode[]> {
-  let sequence = mergedLists(blocks.filter((block) => block.type !== 'paragraph' || nodeContent(block).length > 0))
-  for (let index = 0; index < sequence.length; index += 1) {
-    const listed = sequence[index]
-    if (listed === undefined || (listed.type !== 'bulletList' && listed.type !== 'orderedList')) continue
-    const block = numberedPastMarkers(listed)
-    const spelled = block === listed && commonMarkSpelling(block, reduction.path, reduction.depth, { flavour: 'plain', memo: reduction.memo })?.ok === true
-    if (spelled) continue
-    sequence = spliced(sequence, index, block === listed ? nodeContent(block).flatMap(nodeContent) : [block])
-    index = Math.max(0, index - 1) - 1
-  }
-  return success(sequence)
-}
-
-// The replacement merges with the lists beside it, so no two lists of one type stand adjacent.
-function spliced(sequence: readonly AdfNode[], index: number, replacement: readonly AdfNode[]): AdfNode[] {
-  const from = Math.max(0, index - 1)
-  return [...sequence.slice(0, from), ...mergedLists([...sequence.slice(from, index), ...replacement, ...sequence.slice(index + 1, index + 2)]), ...sequence.slice(index + 2)]
-}
-
-// A numbered list whose markers run past CommonMark's keeps its numbers as text in a bullet list.
-function numberedPastMarkers(list: AdfNode): AdfNode {
-  const order = nodeAttrs(list)['order']
-  if (list.type !== 'orderedList' || typeof order !== 'number' || order + nodeContent(list).length - 1 <= largestListMarker) return list
-  return numberedAsText(list)
-}
-
-function numberedAsText(list: AdfNode): AdfNode {
-  const order = Number(nodeAttrs(list)['order'])
-  return { content: nodeContent(list).map((item, offset) => itemOf(marked(nodeContent(item), `${order + offset}.`))), type: 'bulletList' }
-}
-
-// Adjacent lists of one marker read back as one list.
-function mergedLists(blocks: readonly AdfNode[]): AdfNode[] {
-  const merged: AdfNode[] = []
-  for (const block of blocks) {
-    let next = block
-    for (let previous = merged.at(-1); previous !== undefined && listMarker(next) !== undefined && listMarker(previous) === listMarker(next); previous = merged.at(-1)) {
-      merged.pop()
-      next = joinedLists(previous, next)
-    }
-    merged.push(next)
-  }
-  return merged
-}
-
-function listMarker(block: AdfNode): string | undefined {
-  if (block.type === 'orderedList') return '.'
-  return block.type === 'bulletList' || block.type === 'taskList' ? '-' : undefined
-}
-
-// Two numbered lists whose numbering breaks between them keep their numbers as text in one bullet list, and a task list joining a bullet list its markers.
-function joinedLists(first: AdfNode, second: AdfNode): AdfNode {
-  const breaks = first.type === 'orderedList' && nodeAttrs(second)['order'] !== Number(nodeAttrs(first)['order']) + nodeContent(first).length
-  const [head, tail] = breaks ? [numberedAsText(first), numberedAsText(second)] : first.type === second.type ? [first, second] : [tasksAsText(first), tasksAsText(second)]
-  return { ...head, content: [...nodeContent(head), ...nodeContent(tail)] }
-}
-
-// A task keeps its marker as text; a list item stands as one, and anything else nests in the item before it.
-function tasksAsText(list: AdfNode): AdfNode {
-  if (list.type !== 'taskList') return list
-  const items: AdfNode[] = []
-  for (const child of nodeContent(list)) {
-    const previous = isTask(child) || child.type === 'listItem' ? undefined : items.pop()
-    items.push(itemOf(previous === undefined ? taskAsText(child) : mergedLists([...nodeContent(previous), child])))
-  }
-  return { content: items, type: 'bulletList' }
-}
-
-function taskAsText(child: AdfNode): readonly AdfNode[] {
-  const marker = taskMarker(nodeAttrs(child)['state'])
-  if (child.type === 'taskItem') return [paragraph(nodeContent(child).length === 0 ? [text(marker)] : [text(`${marker} `), ...nodeContent(child)])]
-  if (child.type === 'blockTaskItem') return marked(nodeContent(child), marker)
-  return child.type === 'listItem' ? nodeContent(child) : [child]
-}
-
-function paragraph(content: readonly AdfNode[]): AdfNode {
-  return { content: [...content], type: 'paragraph' }
-}
-
-function text(value: string): AdfNode {
-  return { text: value, type: 'text' }
-}
-
-function listOf(items: readonly AdfNode[], type: string): AdfNode[] {
-  return items.length === 0 ? [] : [{ content: [...items], type }]
-}
-
-function paragraphOf(nodes: readonly AdfNode[], reduction: Reduction): Result<AdfNode[]> {
-  const content = reduceInline(nodes, 'paragraph', reduction.path, reduction.depth)
-  return content.ok ? success(content.value.length === 0 ? [] : [paragraph(content.value)]) : content
-}
-
-function paragraphOfNode(node: AdfNode, reduction: Reduction): Result<AdfNode[]> {
-  return paragraphOf([node], reduction)
-}
-
-function contained(shell: AdfNode, node: AdfNode, reduction: Reduction): Result<AdfNode[]> {
-  const content = reduceBlocks(nodeContent(node), { ...reduction, depth: reduction.depth + 1 })
-  return content.ok ? success([{ ...shell, content: content.value }]) : content
-}
-
-function reducePanel(node: AdfNode, reduction: Reduction): Result<AdfNode[]> {
-  const panelType = nodeAttrs(node)['panelType']
-  return contained(typeof panelType === 'string' ? { attrs: { panelType }, type: 'panel' } : { type: 'panel' }, node, reduction)
-}
-
-function reduceExpand(node: AdfNode, reduction: Reduction): Result<AdfNode[]> {
-  const held = nodeAttrs(node)['title']
-  const title = typeof held === 'string' ? withoutTrailingBlanks(oneLine(held).replace(/^[ \t]+/, '')) : ''
-  return contained(title === '' ? { type: node.type } : { attrs: { title }, type: node.type }, node, reduction)
-}
-
-// A backward scan: an unanchored-end regex retries from every blank in a long run.
-function withoutTrailingBlanks(text: string): string {
-  let end = text.length
-  while (end > 0 && (text.charAt(end - 1) === ' ' || text.charAt(end - 1) === '\t')) end -= 1
-  return text.slice(0, end)
-}
-
-function reduceHeading(node: AdfNode, reduction: Reduction): Result<AdfNode[]> {
-  const level = nodeAttrs(node)['level']
-  if (typeof level !== 'number' || !Number.isInteger(level) || level < 1 || level > 6) return paragraphOf(nodeContent(node), reduction)
-  const content = reduceInline(nodeContent(node), 'heading', reduction.path, reduction.depth)
-  return content.ok ? success([{ attrs: { level }, content: content.value, type: 'heading' }]) : content
-}
-
-function reduceCodeBlock(node: AdfNode, reduction: Reduction): Result<AdfNode[]> {
-  const leaves = inlineLeaves(nodeContent(node), 'paragraph', reduction.path, reduction.depth)
-  if (!leaves.ok) return leaves
-  const code = leaves.value.map((leaf) => leaf.text ?? '\n').join('')
-  const slot = languageSlot(nodeAttrs(node)['language'])
-  const block: AdfNode = { content: code === '' ? [] : [text(code)], type: 'codeBlock' }
-  return success([slot.kind === 'fence' ? { ...block, attrs: { language: slot.info } } : block])
-}
-
-function reduceList(node: AdfNode, reduction: Reduction): Result<AdfNode[]> {
-  const listed = reduceItems(node, reduction, (child, at) => (child.type === 'listItem' ? reduceBlocks(nodeContent(child), at) : reduceStanding(child, at)))
-  if (!listed.ok || node.type !== 'orderedList') return listed
-  const order = nodeAttrs(node)['order']
-  const start = typeof order === 'number' && Number.isInteger(order) && order >= 0 ? order : 1
-  return success(listed.value.map((list) => ({ ...list, attrs: { order: start } })))
-}
-
-function reduceItems(node: AdfNode, reduction: Reduction, itemBlocks: (child: AdfNode, at: Reduction) => Result<AdfNode[]>): Result<AdfNode[]> {
-  const items = concatenated(nodeContent(node).map((child, index) => listItem(itemBlocks(child, childReduction(reduction, index)))))
-  return items.ok ? success(listOf(items.value, node.type === 'orderedList' ? 'orderedList' : 'bulletList')) : items
-}
-
-function listItem(blocks: Result<AdfNode[]>): Result<AdfNode[]> {
-  return blocks.ok ? success([itemOf(blocks.value)]) : blocks
-}
-
-// A list item's first line reads as no rule and holds no line of spaces alone: the rule and the spaces give way.
-function itemOf(blocks: readonly AdfNode[]): AdfNode {
-  const rules = blocks.findIndex((block) => block.type !== 'rule')
-  const content = blankedCode(blocks.slice(rules === -1 ? blocks.length : rules))
-  return content.length === 0 ? { type: 'listItem' } : { content, type: 'listItem' }
-}
-
-function blankedCode(blocks: readonly AdfNode[]): AdfNode[] {
-  return blocks.map((block) => (block.type === 'codeBlock' ? { ...block, content: blankedLines(nodeContent(block)) } : block))
-}
-
-function blankedLines(code: readonly AdfNode[]): AdfNode[] {
-  const blanked = code.map((leaf) => leaf.text ?? '').join('').replace(/^[ \t]+$/gm, '')
-  return blanked === '' ? [] : [text(blanked)]
-}
-
-// A task list opening with a task and holding tasks and task lists alone keeps its spelling, a list nesting in the task before it; any other keeps its markers as text. A child reducing to nothing counts for neither.
-function reduceTaskList(node: AdfNode, reduction: Reduction): Result<AdfNode[]> {
-  const kept: { blocks: AdfNode[]; child: AdfNode }[] = []
-  for (const [index, child] of nodeContent(node).entries()) {
-    const at = childReduction(reduction, index)
-    const reduced = isTask(child) ? reduceTask(child, at) : reduceStanding(child, at)
-    if (!reduced.ok) return reduced
-    if (reduced.value.length > 0) kept.push({ blocks: reduced.value, child })
-  }
-  const regular = isTask(kept[0]?.child) && kept.every(({ child }) => isTask(child) || child.type === 'taskList')
-  const tasks: AdfNode[] = []
-  let nested: AdfNode[] = []
-  for (const { blocks, child } of kept) {
-    if (!regular) {
-      const standsAlone = !isTask(child) && child.type !== 'taskList'
-      for (const block of standsAlone ? [{ content: blocks, type: 'listItem' }] : blocks) tasks.push(block)
-      continue
-    }
-    if (isTask(child)) {
-      nestIn(tasks, nested)
-      nested = []
-    }
-    for (const block of blocks) (isTask(child) ? tasks : nested).push(block)
-  }
-  nestIn(tasks, nested)
-  if (regular) return success([{ content: tasks, type: 'taskList' }])
-  return success(listOf(nodeContent(tasksAsText({ content: tasks, type: 'taskList' })), 'bulletList'))
-}
-
-// The writer nests a list in the task before it, so one closing a block task item's blocks merges with it.
-function nestIn(tasks: AdfNode[], nested: readonly AdfNode[]): void {
-  const previous = tasks.at(-1)
-  if (previous?.type === 'blockTaskItem') tasks[tasks.length - 1] = { ...previous, content: mergedLists([...nodeContent(previous), ...nested]) }
-  else for (const block of mergedLists(nested)) tasks.push(block)
-}
-
-function isTask(node: AdfNode | undefined): boolean {
-  return node?.type === 'taskItem' || node?.type === 'blockTaskItem'
-}
-
-function reduceTask(task: AdfNode, at: Reduction): Result<AdfNode[]> {
-  const attrs = { state: nodeAttrs(task)['state'] === 'DONE' ? 'DONE' : 'TODO' }
-  if (task.type === 'taskItem') {
-    const content = reduceInline(nodeContent(task), 'paragraph', at.path, at.depth)
-    return content.ok ? success([{ attrs, content: content.value, type: 'taskItem' }]) : content
-  }
-  const blocks = reduceBlocks(nodeContent(task), at)
-  return blocks.ok ? success([{ attrs, content: blankedCode(blocks.value), type: 'blockTaskItem' }]) : blocks
-}
-
-// The marker leads the first paragraph, or stands as one where the blocks open with another.
-function marked(blocks: readonly AdfNode[], marker: string): AdfNode[] {
-  const [first, ...rest] = blocks
-  if (first?.type === 'paragraph') return [paragraph([text(`${marker} `), ...nodeContent(first)]), ...rest]
-  return [paragraph([text(marker)]), ...blocks]
-}
-
-function reduceTable(node: AdfNode, reduction: Reduction): Result<AdfNode[]> {
-  const rows: PlacedCell[][] = []
-  for (const [rowIndex, row] of nodeContent(node).entries()) {
-    const rowReduction = childReduction(reduction, rowIndex)
-    const cells: PlacedCell[] = []
-    for (const [cellIndex, cell] of (row.type === 'tableRow' ? nodeContent(row) : [row]).entries()) {
-      const paragraph = cellParagraph(cell, childReduction(rowReduction, cellIndex))
-      if (!paragraph.ok) return paragraph
-      cells.push({ colspan: span(nodeAttrs(cell)['colspan']), paragraph: paragraph.value, rowspan: span(nodeAttrs(cell)['rowspan']) })
-    }
-    rows.push(cells)
-  }
-  const grid = spannedGrid(rows)
-  const width = grid.reduce((widest, cells) => Math.max(widest, cells.length), 0)
-  const tableRows = grid.map((cells, rowIndex) => ({
-    content: Array.from({ length: width }, (_, column): AdfNode => ({ content: [cells[column] ?? { type: 'paragraph' }], type: rowIndex === 0 ? 'tableHeader' : 'tableCell' })),
-    type: 'tableRow',
-  }))
-  return success(width === 0 ? [] : [{ content: tableRows, type: 'table' }])
-}
-
-function span(value: unknown): number {
-  return typeof value === 'number' && Number.isInteger(value) && value > 1 ? value : 1
-}
-
-// A span keeps its cell under its header by empty cells where it covered; they number no more than the table's cells.
-function spannedGrid(rows: readonly PlacedCell[][]): (AdfNode | undefined)[][] {
-  const grid: (AdfNode | undefined)[][] = rows.map(() => [])
-  const covered = rows.map(() => new Set<number>())
-  let padding = rows.reduce((count, cells) => count + cells.length, 0)
-  for (const [rowIndex, cells] of rows.entries()) {
-    let column = 0
-    for (const cell of cells) {
-      while (covered[rowIndex]?.has(column) === true) column += 1
-      setCell(grid, rowIndex, column, cell.paragraph)
-      for (let row = rowIndex; row < Math.min(rows.length, rowIndex + cell.rowspan) && padding > 0; row += 1) {
-        for (let spanned = row === rowIndex ? 1 : 0; spanned < cell.colspan && padding > 0; spanned += 1) {
-          covered[row]?.add(column + spanned)
-          setCell(grid, row, column + spanned, { type: 'paragraph' })
-          padding -= 1
-        }
-      }
-      column += 1
-    }
-  }
-  return grid
-}
-
-function setCell(grid: (AdfNode | undefined)[][], row: number, column: number, cell: AdfNode): void {
-  const cells = grid[row]
-  if (cells !== undefined && cells[column] === undefined) cells[column] = cell
-}
-
-function cellParagraph(cell: AdfNode, reduction: Reduction): Result<AdfNode> {
-  const blocks = cell.type === 'tableCell' || cell.type === 'tableHeader' ? nodeContent(cell) : [cell]
-  const content = reduceInline(blocks, 'table-cell', reduction.path, reduction.depth)
-  return content.ok ? success(content.value.length === 0 ? { type: 'paragraph' } : paragraph(content.value)) : content
-}
-
-function reduceMedia(media: AdfNode, reduction: Reduction): Result<AdfNode[]> {
-  const attrs = nodeAttrs(media)
-  const url = attrs['url']
-  if (attrs['type'] !== 'external' || typeof url !== 'string') return paragraphOfNode(media, reduction)
-  const held = attrs['alt']
-  const alt = typeof held === 'string' ? oneLine(held).trim() : ''
-  const external: AdfNode = { attrs: alt === '' ? { type: 'external', url: writableHref(url) } : { alt, type: 'external', url: writableHref(url) }, type: 'media' }
-  const image: AdfNode = { attrs: { layout: 'center' }, content: [external], type: 'mediaSingle' }
-  return success([image])
-}

src/markdown/empty-keys.ts

@@ -1,30 +0,0 @@
-import type { DirectiveAttributes, DirectiveValue, Read } from './directive-syntax.ts'
-import type { EmptyKey } from '../adf/document.ts'
-import { emptyKeys } from '../adf/document.ts'
-import { unsupportedNodeShape } from './directive-syntax.ts'
-
-type EmptyKeysRead = { empty: ReadonlySet<EmptyKey>; rest: Map<string, DirectiveValue> }
-
-const emptyValue = 'empty'
-
-// spec/flavour.md, Attributes: no attribute value spells an empty object or array.
-export function spellEmptyKeys(held: Parameters<typeof emptyKeys>[0]): [string, string][] {
-  return emptyKeys(held).map((key) => [key, emptyValue])
-}
-
-export function spellsEmpty(value: DirectiveValue | undefined): boolean {
-  return value?.spelling === emptyValue
-}
-
-export function readEmptyKeys(attributes: DirectiveAttributes, keys: readonly EmptyKey[]): Read<EmptyKeysRead> {
-  const rest = new Map(attributes)
-  const empty = new Set<EmptyKey>()
-  for (const key of keys) {
-    const spelled = rest.get(key)
-    if (spelled === undefined) continue
-    if (!spellsEmpty(spelled)) return { fault: unsupportedNodeShape(`the reserved key ${key} reads ${key}=${emptyValue} alone: this one spells ${key}=${spelled.spelling}`) }
-    empty.add(key)
-    rest.delete(key)
-  }
-  return { value: { empty, rest } }
-}

src/markdown/line-container.ts

@@ -1 +0,0 @@
-export type LineContainer = 'heading' | 'paragraph' | 'table-cell'

src/markdown/list-break.ts

@@ -0,0 +1,5 @@
+import { spellDirectiveOpener } from './directive-syntax.ts'
+
+export const listBreakName = 'listBreak'
+
+export const listBreakSpelling = spellDirectiveOpener(listBreakName, undefined, '')

src/markdown/mark-spellings.ts

@@ -7,7 +7,6 @@ import { holdsEntityReference } from './commonmark/entity-references.ts'
 import { isAutolink } from './commonmark/grammar.ts'
 import { isMarkType, markAttributes } from '../adf/mark-attributes.ts'
 import { nodeAttrs, nodeMarks } from '../adf/document.ts'
-import { spellEmptyKeys } from './empty-keys.ts'
 import { vocabularyPairs } from '../adf/attribute-vocabulary.ts'
 
 type Spelling = { kind: 'code' | 'directive' | 'link'; spelling?: undefined } | { kind: 'emphasis'; spelling: string }
@@ -56,10 +55,7 @@ function isBareLink(nodes: readonly AdfNode[], href: string, marksInside: number
   return nodes.length === 1 && node !== undefined && node.type === 'text' && node.text === href && nodeMarks(node).length === marksInside
 }
 
-// `undefined` where the spelling holds no such attrs: only a directive spells attrs=empty.
-export function spellMarkAttributes(mark: AdfMark, spelling: MarkSpelling): string | undefined {
-  const pairs = vocabularyPairs(nodeAttrs(mark), spelling.attributes, [])
-  const empty = spellEmptyKeys(mark)
-  if (pairs === undefined || (empty.length > 0 && spelling.kind !== 'directive')) return undefined
-  return spellAttributes([...spellVocabulary(pairs), ...empty])
+export function spellMarkAttributes(mark: AdfMark, vocabulary: AttributeVocabulary): string | undefined {
+  const pairs = vocabularyPairs(nodeAttrs(mark), vocabulary, [])
+  return pairs === undefined ? undefined : spellAttributes(spellVocabulary(pairs))
 }