@quillmark/wasm 0.132.0 → 0.134.0

package/CHANGELOG.md

@@ -1,5 +1,423 @@
 # Changelog
 
+## v0.134.0 - 2026-11-02
+
+Upgrade path: [0.133 → 0.134](docs/migrations/0.133-to-0.134.md). Every
+content value is the content model, and offsets in content values and changes
+cross WASM in UTF-16 code units, where they counted scalar values. Python's
+`revise_body`, `revise_field` and `revise_document` return a dict receipt,
+where they returned a list of `Diagnostic`, so a loop over the result runs
+over its keys: read `receipt["warnings"]`.
+
+### Content v2
+
+- feat(content)!: **the content model.** One value per body or `richtext`
+  field: flat text, blocks and containers with ids, marks, anchors apart from
+  marks, and islands whose cells and notes are slots of nested content.
+  Nothing derived is stored: an item's number is computed, and runs are told
+  apart by container id. The line form moves under `quillmark_content::lines`
+  and stays what the renderers and markdown codecs read; `migrate` moves
+  values between the two, minting ids deterministically.
+- feat(content)!: **the line form's op lane is removed.** `lines::ops`
+  (`ChangeBundle`, `LineOp`, `MarkOp`, `IslandOp` and their decoders),
+  `Card::apply_body_change`, `Card::apply_field_change`, the `Normalized`
+  `apply_*` methods and `EditError::ContentApply` go: a `Change` through
+  `Card::apply` is the one edit. `quillmark::session` no longer re-exports
+  them. The parity corpus's op-wire cell reads the `Change` `diff` takes
+  from the empty value.
+- feat(content): **`Change`, the one way a value is edited.** Splice,
+  `setBlock`, `container`, `mark`, `anchor`, `island` and `nested` steps,
+  with `invert`, `compose`, `map_pos` and a word-aligned `diff`, each a
+  property-tested law. A change yields a valid value or fails and changes
+  nothing.
+- feat(content)!: **a block's record rides the `\n` that opens it.** A
+  split names the right half and the left keeps its id, so Enter at the end
+  of any block, the last included, leaves the text on its id; a join keeps
+  the left block's id and kind. `blocks[0]` is the record no splice reaches,
+  so `diff` and `replace` keep the stored first id, and `repair` gives the
+  first piece of a block it splits beside an island the block's record.
+- feat(content): **`gestures::split_block` and `join_blocks`** build Enter
+  and Backspace as one splice each, inserting ahead of a block's opening
+  `\n` at its start so the text keeps its id.
+- feat(content): **`gestures::inherited_marks(content, at)`** answers the
+  marks typed text carries: `strong`, `emph`, `underline` and `strike` grow
+  at their end, `code`, `link` and an `x-` mark at neither edge,
+  `font_family` at both.
+- feat(bindings)!: **every WASM offset is UTF-16.** A region's `span`,
+  `positionAt`'s and `locate`'s `pos`, a typed revise's `Revised.delta` and
+  the deltas `reattach` takes count in UTF-16 code units, as content values
+  and changes do; core takes a host's units through `LiveSession::*_in`,
+  `Engine::render_in`, `Revised::delta_in` and `Document::reattach_in`.
+- feat(content): **`repair` makes a merged state valid.** A missing
+  container leaves a path, a container under two paths takes its first
+  block's, a later run gets a derived container, an orphan slot or record
+  goes, text beside a table splits off, and a collapsed range anchor is
+  dropped. Total and deterministic.
+- feat(content): **repair is how a merged state reads, and a write-back is
+  optional.** Peers holding one merged state compute one value without
+  writing. Any peer may write back a repair that only deletes or sets; one
+  that inserts (a block split beside an island, a heading's hard break, a
+  missing cell) is written back by a single writer, since two peers would
+  each insert their own. `Repair::inserts` says which, `inserts: true` on
+  the wire, and a missing cell reports `Repair::EmptyCell`.
+- feat(core)!: **storage moves to `quillmark/document@0.134.0`**, each body
+  and richtext field the content model. An older row loads migrated, with the
+  same ids on every load. A value holds each anchor id once over its text
+  and every slot, so a stored value holding one twice loads keeping its
+  first holder.
+- feat(core)!: **`Card::apply`, `revise` and `replace`** write a body or
+  richtext field and answer a `Receipt`: the applied change, the new hash,
+  and the dropped and moved anchors. Each takes the hash its writer read and
+  refuses a stale one with `edit::stale_base`. `Card::write` takes the
+  `Edit` each builds its change from, and `write_in` takes a host's units.
+- feat(wasm)!: **`doc.read`, `apply`, `revise`, `replace`, `annotated` and
+  `hash(addr)`, and `invert` and `diff`**, offsets in UTF-16 code units.
+  Every content payload crossing the binding is the model. `overwrite`,
+  `reviseContent`, `applyChange` and `mapMarks` are removed: call `replace`
+  and `apply`. `compose`, `rebase` and `repair` stay unbound until the
+  editor or collaboration calls them.
+- feat(wasm)!: **the editing gestures and `mapPos(change, pos, assoc?)`.**
+  `splitBlock`, `joinBlocks`, `deleteRange`, `indent`, `outdent`, `wrap` and
+  `inheritedMarks` take a `Content` and answer the `Change` to apply, offsets
+  in UTF-16. `mapPos` carries a position across a `Change`, where it took a
+  line delta, and answers a `MapResult`.
+- feat(python)!: **the same surface in snake case**, offsets in code points.
+- feat(core)!: **a content write names its card by `$id`.** An id no card
+  holds refuses with `edit::unknown_card_id`. `Document::card_index` and
+  `card_by_id` find a card by id. WASM `Addr.card` and Python `card=`
+  take a card's `$id` on every verb, and `apply`, `revise` and
+  `replace` take nothing else, so a card moved or inserted between a read and
+  its write, its body equal to the one read, no longer takes the write.
+- feat(content)!: **the receipt names every anchor a change loses.** An
+  island a splice deletes, or a slot a props step no longer names, names the
+  anchors of its slots, each with the `island` and `slot` that held it.
+  `revise` and `replace` name every anchor they lose; `apply` every one but
+  those its own `anchor` steps removed. `Applied.dropped` and
+  `Receipt.dropped_anchors` are `change::Dropped`, an `AnchorContext` and a
+  `SlotRef`; WASM spells it `DroppedAnchor`.
+- feat(content)!: **`diff` refuses an invalid target.** `diff` and `replace`
+  return the `Invariant` an invalid `after` breaks, where they returned zero
+  steps, and reach every valid one step-wise. WASM and Python `diff` answer
+  the `Change`.
+- feat(content)!: **every offset-addressed step can hold to what its writer
+  read.** `mark` steps and an `anchor` placement take an optional `quote`,
+  the text their range covered, and an `island` insert an optional `block`,
+  the id of the block it lands in; a mismatch is `ApplyError::Stale`, as a
+  splice's `delete` is. `Applied.applied` and `invert` fill both in.
+  `MarkStep::Add`, `MarkStep::Remove`, `AnchorStep::Set` and
+  `IslandStep::Insert` carry the new fields.
+- feat(content)!: **`map_pos` answers a `MapResult`.** A position always
+  lands, inside deleted text on the deletion's `assoc` edge and inside an
+  island a splice deleted on the island's slot, with `deleted`,
+  `deleted_before`, `deleted_after` and `deleted_across` saying what went
+  around it. A splice that deletes an island and names none in `removed` is
+  refused, where it mapped a position inside that island as kept. New
+  `mapping::StepMap` and `Mapping`, a list of step maps with mirror links, so
+  a position a step deleted and its rebased mirror put back maps home.
+- feat(content)!: **reserved `x-` names on three vocabularies.** A block
+  kind, mark type or island type spelled `x-` and more decodes into
+  `BlockKind::Ext`, `MarkKind::Ext` or `IslandType::Ext`, its attrs or props
+  held as written, and re-encodes to the same bytes; any other unknown name
+  still refuses. Validation is structural only. An `x-` block reads as a
+  paragraph, an `x-` mark formats nothing, and an `x-` island renders and
+  exports to markdown as nothing, which the annotated read spells as its
+  token so a revise keeps it; a content write's revise or replace that
+  removes one refuses with `edit::drops_ext_island`, and `apply` removes it.
+  Steps set and remove them. `MarkStep::Remove`'s `tag` is a `String`,
+  `BlockKind::tag` and `MarkKind::tag` return `&str`, and `IslandType` is no
+  longer `Copy`.
+- feat(content): **`rebase(base, change, over)` moves a change past another
+  made from the same value**, after ProseMirror's `rebaseSteps`. Each step
+  maps through the inverse of its change's earlier steps, then `over`, then
+  those steps rebased, and holds to its `delete`, `quote` or `block` on the
+  value it now reads; a step `over` deleted the text of, or whose id is gone,
+  is a `rebase::Conflict` naming it. A step by id that would overwrite what
+  `over` changed (a block's kind or path, a container, an island's props)
+  conflicts rather than undoing it, as does a splice that deletes an island
+  or block `over` changed, so a diff's `setBlock` names only the fields it
+  changes.
+  `Mapping::map_point` and `project` map
+  as `apply` moves a point anchor and inside one slot.
+- feat(core)!: **a stale `base` rebases the write instead of refusing it.**
+  Each card keeps, in memory only, a log of its recent writes per value: one
+  snapshot of the value, and each write's normalized change and the hash it
+  left. A base rebases while the writes since it hold at most `LOG_STEPS`
+  (4096) steps, thousands of keystrokes, and the base the newest write read
+  whatever its size; past twice that, the oldest writes fold into the
+  snapshot, so the log holds one copy of the value however large.
+  `apply`, `revise` and `replace` with a base the log holds rebase over the
+  changes since, and a revise or replace diffs from the value the base
+  names. The receipt's new `rebased` says so. A conflict refuses with
+  `edit::rebase_conflict`, carrying `step` and `reason`; a base the log does
+  not reach is `edit::stale_base` as before. `Card::read_at` answers the
+  value a base names, and `BaseError::Conflict` carries `step` and
+  `reason`.
+- fix(content): **`replace` moves an anchor between the prose and a cell**,
+  where it refused with `DuplicateId`: it carries only an anchor the new
+  value names nowhere. A props step naming a slot in `slots` that the props
+  do not name says so, apart from one naming a slot the island holds.
+- feat(content)!: **a block or island keeps its id when a change moves
+  it.** Block and island ids are unique at the end of a change, as anchor
+  ids are, so a step may insert a copy before another deletes the original;
+  a step naming an id held twice between steps is `ApplyError::BadStep`.
+  `diff` keeps the id of a block or island moved either way, where it
+  re-minted one moved toward the front.
+- perf(content): **`apply` runs a change in one pass.** Each step works on
+  the blocks it touches, checks only what it touched, and answers its
+  inverse as it applies; the whole value is validated once, at the end.
+  `invert` reads those inverses back, and a receipt lowers the value or
+  compares anchors only where something was dropped or rewritten. A
+  4000-step change to 288k characters applies in 26 ms, where it took 96 s,
+  and inverts in 30 ms, where it took 496 s; a revise of it takes 0.1 s and
+  a rebase 0.2 s, where they took 294 s and 396 s. An inverse's mark steps
+  restore each run of marks that differs, not one range over all of them.
+  `tests/speed.rs` is the gate, run in CI in a release build.
+- perf(content): **converting a change or value to UTF-16 finds each
+  offset by binary search**, where it walked the text from its start: the
+  4000-step change crosses each way in about 20 ms, where it took 12 s out
+  and 19 s in.
+- perf(core): **`content_hash` digests the content value as written**,
+  whose keys are already in order, rather than sorting a copy; the bytes are
+  the same.
+
+### Card identity
+
+- feat(core)!: **every composable card carries a `$id`.** It emits after
+  `$kind`, is minted where none is written (`c` and five base32 letters of a
+  fixed SHA-256 sequence, so equal markdown parses to equal ids), and a parse
+  re-mints a malformed or repeated one with `parse::card_id_reminted`. A
+  null `$id` (`$id:`, `~`) is no `$id`.
+  `insert_card` refuses a bad or held id (`edit::invalid_card_id`,
+  `edit::duplicate_card_id`). An older row mints its ids on load. `$id`
+  never reaches the plate JSON.
+- feat(core)!: **a whole-document revise pairs cards by `$id` first.** An
+  incoming card spelling a stored card's id revises it, the most similar of
+  several spelling one keeps it, and the rest align by text as before. A
+  revised card keeps its stored id; an inserted one keeps a fresh id or mints
+  past every stored one. A list field's items align by text, so an item
+  inserted ahead of an anchored one leaves the anchor on its own item.
+- feat(core)!: **a comment selector names its card.** `AnchorSelector` and
+  `DocumentAnchor` gain `card_id`, and `reattach` resolves a selector's card by
+  it wherever the card moved. WASM spells it `cardId` on `AnchorContext`,
+  `DocumentAnchor` and the `Card` / `CardInput` `id`; Python `card_id` and the
+  card dict's `id`.
+
+### Two-way annotated read
+
+- feat(content)!: **a revise reads the annotated read back.** A
+  `qm-anchor` tag the writer kept pins its anchor's start where it stands,
+  one it dropped leaves the anchor to the diff, and one naming nothing stored
+  reports `qm-anchor[ref]`. The read marks a tag it moved off its anchor's
+  start `at="span"` or `at="line"`, which pins nothing.
+- feat(content)!: **an island markdown cannot spell reads as a
+  `qm-island` token**, `<qm-island ref="ID"></qm-island>`, which a revise
+  keeps as stored: a table's unnamed keys, an equation's unwritable TeX, an
+  image's extra props. A token naming no stored island reports
+  `qm-island[ref]`; a cold import drops every token, reported as
+  `qm-island`. A `Base::Read` merge compares the sides as annotated reads,
+  so a token survives it and a moved tag pins through it.
+
+### Anchors on every text surface
+
+- feat(content)!: **a table cell's and a footnote note's anchors join the
+  comment contract.** `Content::anchor_sites` reads every anchor with its
+  `Surface`, prose or a cell, and `anchor_contexts`, the annotated read's
+  `anchors` and every `dropped_anchors` receipt list cell anchors, a cell's
+  text as its `line`. `RemoveAnchor` removes an id from every cell, an anchor
+  `Add` refuses an id a cell holds, and an island op refuses a cell anchor
+  whose id the value already holds (`ApplyError::AnchorIdCollision`). A revise
+  keeps a cell's anchor where its island continues and the cell's text is
+  unchanged. `locate_site` and `reattach` search the cells with the prose.
+
+### Scoped reads
+
+- feat(core): **the annotated read of one address.** `Card::body_annotated`
+  and `field_annotated` (WASM `doc.annotatedAt(addr)`) read one body or
+  richtext field as the revise at that address reads it back, and as its
+  `baseMarkdown`.
+
+### Guarded revise
+
+- feat(core)!: **a revise states what its writer read.** `Base::Hash` is the
+  hash of the value read (`Card::body_hash`, `Card::field_hash`,
+  `Document::hash`, `content_hash`, and the typed writer's `hash` /
+  `field_hash` through the schema: SHA-256 over `quillmark/hash@1` and the
+  key-sorted canonical JSON), and a value that now hashes otherwise refuses
+  the write with `edit::stale_base`. `Base::Read` is the markdown read, annotated or not:
+  when the value has changed since, the writer's edit and the change merge by
+  line (`quillmark_content::delta::merge_lines`), so a person's edit made
+  between an LLM's read and its write lands beside the LLM's, and runs of
+  lines both changed refuse with `edit::rebase_conflict`. Both carry `current`,
+  the hash now. The verbs are `revise_body_against`, `revise_field_against`,
+  the writers' `revise_document_against`, and the free
+  `revise_import_against`. `EditError` gains `Base(BaseError)` and
+  `BoundParseError` gains `Base`.
+- feat(wasm): **`BaseOptions` on every revise.** The writer's `reviseBody` /
+  `reviseField` / `reviseDocument` take an optional
+  `{ baseHash?, baseMarkdown? }`, read through the writer's `hash()` /
+  `hashAt(addr)` or the quill-free `doc.hashAt(addr)` / `doc.hash()`.
+- feat(python): **`base_hash` and `base_markdown` on the writer's revise
+  verbs**, read through the writer's `hash()` / `hash_at(field=None,
+  card=None)` and the quill-free `doc.hash_at` / `doc.hash()`.
+
+### Markdown export
+
+- feat(content): **an export can name what it does not spell.**
+  `export::to_markdown_checked` returns `Exported { markdown, losses }`, the
+  markdown read back and compared with the content: each `ExportLoss` is a
+  mark written over other text or dropped, an island that reads back
+  otherwise, or `Text` where the text or its blocks do. Core mints one
+  `export::lost_construct` warning per loss (`lost_construct`), its
+  `construct` the mark's wire type, the island's type or `text`, a mark's
+  `start` and `end` beside it.
+- fix(content): **a `*`, `_` or `~~` mark over edge whitespace keeps its
+  text.** `bar ` in bold wrote no bold at all, its delimiter never closing
+  against a space; it now writes `**bar** `, the mark over `bar`.
+- perf(content): **`to_markdown` reads each line's marks alone**, so export is
+  linear in the marks where it scanned every mark per line.
+- feat(content)!: **a markdown import reports the bidi controls it drops**,
+  under `parse::dropped_construct` with `construct: "bidi"`. `Dropped` gains
+  `Bidi`.
+
+### Comments
+
+- feat(content): **anchor contexts and exact re-attachment.** The `anchor`
+  module reads each prose anchor's quote, prefix and suffix off the stored
+  text as it is, an inline island's `U+FFFC` slot included
+  (`anchor_contexts`), finds the one range a context names (`locate`), and
+  re-adds a dropped anchor through the `Add` arm (`Content::reattach`), a range
+  over exactly its quote and a point at the one place its context meets. The
+  rule never guesses: a quote of `MIN_ANCHOR_QUOTE` (four) scalar values or
+  more, or island slots alone, its context agreeing on `ANCHOR_AGREE_USV`
+  (eight) each side or as far as it reaches where the field's edge cut it, a match overlapping inserted text where a
+  delta is given, and exactly one such place. `Delta::inserted_spans` is
+  public. (#2349)
+- feat(core): **`Document::reattach` and `Revised.dropped_anchors`.**
+  `Document::anchor_contexts` / `anchor_context(id)` read each anchor's
+  `AnchorSelector { id, path, quote, prefix, suffix }`, and
+  `Document::reattach(selectors, deltas)` places dropped anchors at their
+  paths, path-strict, an id live anywhere in the document, a cell's included,
+  answered without a write. `Revised` gains `dropped_anchors`, each
+  `AnchorRead { id, line }`, at every rung that revises one body or field, and
+  `revise_import` takes the `&Normalized` it names them from. The facade
+  re-exports `AnchorSelector`, `Reattached`, `AnchorRead` and `DocPath`.
+  (#2349)
+- feat(wasm): **`anchorContexts`, `anchorContext`, `reattach` and
+  `droppedAnchors`.** The selector crosses flat, its `path` a `DocPath`
+  string; `reattach(selectors, deltas?)` takes a `Record<path, Delta>` and
+  returns `{ reattached, orphaned }`. The `Revised` receipt of
+  `writer.reviseBody` and `writer.reviseField` gains
+  `droppedAnchors: { id, line }[]`. (#2349)
+- feat(python)!: **the revise verbs return the whole receipt.**
+  `writer.revise_body` / `revise_field` return `{ delta, warnings,
+  dropped_anchors }` and `revise_document` `{ dropped_anchors, warnings, from }`,
+  its warnings the same `Diagnostic` objects, where each returned a list of
+  them. `doc.anchor_contexts()`, `doc.anchor_context(id)` and
+  `doc.reattach(selectors, deltas=None)` expose the handle. (#2349)
+- docs(canon): **`COMMENTS.md` states the comment-anchor contract**: the
+  thread outside the document, the id it shares with its anchor, the matching
+  rule, drift, table cells, and the hosting rule. (#2349)
+
+### Removed
+
+- refactor(wasm)!: **WASM API no consumer uses.** `Document.revise` (the
+  0.133 markdown revise; `revise` is now the content-lane write),
+  `rebase`, `loadStored`, `storeFields`, `Quill.seedMain`,
+  `Document.markdownRules`, `assignInstances`, `CardReader` and
+  `reader.card(i)`, `CardWriter.index` / `kind`, the writer's and reader's
+  `document` getters and `LiveSession.backendId` are removed. The migration
+  guide's § Removed names each replacement.
+- refactor(core,pdf)!: **public items nothing outside their crate uses.**
+  `BUNDLE_MEDIA_TYPE` is removed; `QuillConfig::is_snake_case_identifier`,
+  `quillmark_pdf::CHECK_GLYPH` and `FieldSpec::assert_finite_rect` are
+  crate-private; `SessionHandle::update` has no default, and the
+  `backend::update_unsupported` code no built-in backend raised is gone.
+- refactor(content)!: **`serial::line_kind_to_value` is removed**, and
+  `serial::line_kind_from_value`, `container_from_value` and
+  `mark_from_value` are crate-private: decode a whole value through
+  `lines::serial::from_canonical_value`.
+
+### Dependencies
+
+- build(deps): **`serde-saphyr` 2.0**, with the YAML error sanitizer
+  stripping its new API names from messages; **Typst's `hayro` 0.7** for the
+  PDF form backend's raster; `pyo3` 0.30.1 and `lopdf` 0.46.
+- ci(release): PyPI publishes only where `PUBLISH_PYPI` is set.
+
+## v0.133.0 - 2026-10-29
+
+Upgrade path: [0.132 → 0.133](docs/migrations/0.132-to-0.133.md). The
+blueprint is retired: a model writes the JSON authoring document, so a prompt
+built from `quill.blueprint` moves to `quill.authoringSchema`. A root
+`example.md` is an ordinary file: a quill's example is what its `Quill.yaml`
+declares, so move each value onto its field before upgrading.
+
+### LLM authoring
+
+- feat(core,cli,wasm,python)!: **LLMs author documents as JSON; the blueprint
+  is retired.** The authoring document is the values form lifted to the whole
+  document, `{fields, body, cards: [{kind, fields, body}]}`, every rich-text
+  field and body a Markdown string and `null` absent.
+  `QuillConfig::authoring_schema()` is its JSON Schema, built by
+  `build_transform_schema` under the new `SchemaCodec::Text`: every cell admits
+  `null`, every declared object refuses an undeclared key, a variant-bearing enum is a `oneOf` per world, and each slot carries
+  its `title`, `description`, `default` and `examples`.
+  `Quill::to_authoring` exports a document, a field stored as `null` absent, and `Quill::from_authoring` imports
+  and conforms one, refusing a malformed shape with `authoring::invalid_shape`,
+  its RFC 6901 pointer in `args.pointer`. Export never fails: an undecodable
+  or string-held content leaf passes as stored, so every export validates
+  against the schema and imports back unchanged.
+  WASM `authoringSchema` / `toAuthoring` / `fromAuthoring`, Python
+  `authoring_schema` / `to_authoring` / `from_authoring`, and
+  `quillmark schema --authoring` expose them. `QuillConfig::blueprint()`,
+  `quill.blueprint`, `quillmark blueprint` and `print_blueprint` are deleted;
+  `quillmark validate` renders the empty and seeded documents.
+  `build_transform_schema` takes a `SchemaCodec`. The blueprint's load rules go
+  with it: a multi-line `description:` and an enum member holding `>`, `;` or
+  `|` load, and `quill::description_multiline` and
+  `quill::format_literal_reserved_char` are deleted. (#2331)
+
+### Examples
+
+- feat(core)!: **`example:` and a body's `description` and `example` join the
+  quill schema.** A slot at any depth declares at most one `example:`, a value
+  of its type checked at load as `default:` is, under
+  `quill::example_{type_mismatch,not_in_enum,format_violation,held_stored,on_namespace,over_max,over_length}`
+  and `quill::richtext_example_import`. It answers no cell. A body's `description` is text for the writer and its
+  `example` markdown that imports without a drop; either beside
+  `enabled: false` is `quill::invalid_body`. `schema()` carries them,
+  `FieldSchema` and `BodyCardSchema` gain the fields, and WASM types them as
+  `QuillFieldSchema.example` and `QuillCardBody.{description,example}`. (#2329)
+- feat(core,cli,wasm,python)!: **the example document is derived.**
+  `Quill::example_document()` returns `Option<Document>`: the seeded document
+  with every declared `example:` committed and each kind's `body.example` as
+  its body, `None` where the quill declares none. A root `example.md` is an
+  ordinary file: `EXAMPLE_FILE` and `quill::example_reference` are deleted,
+  WASM `exampleDocument()` and Python `example_document()` no longer throw, and
+  `quillmark validate` validates and renders the derived document, warning
+  `cli::example_file_ignored` while a root `example.md` remains. The
+  fixture quills declare the values their `example.md` held. (#2329)
+
+### Content
+
+- feat(content,core,wasm): **`reviseContent` revises a body or field to a
+  content and keeps its prose anchors.** WASM `doc.reviseContent(addr, rt)`,
+  over core's `Card::revise_body_content` / `revise_field_content` and the
+  content crate's `delta::carry_anchors`, diffs a content built elsewhere
+  against the stored value, carries each prose anchor whose id `rt` does not
+  hold, and returns the `Revised` receipt with its text `delta`. `rt`'s own
+  anchors and island ids land as they are.
+- feat(content)!: **normalizing content moves no text.** A table's slot
+  sharing its line with prose is canonical: `Content::normalize` leaves the
+  line as given, where it inserted a `\n` on each side, and `to_markdown`
+  breaks it instead. `overwrite`, `reviseContent` and
+  `serial::from_authored_value` take the shape where they threw `block island
+  in a line's prose`, an `IslandOp::Set` on such a table lands, and a stored
+  row holding it loads as stored under the same tag. Typst sets the table as a
+  block where its slot sits, closing a heading around it, and a hard break
+  after a line the slot ends clears. WASM gains `normalize(content)`, the form
+  `overwrite` stores. (#2330)
+
 ## v0.132.0 - 2026-10-27
 
 Upgrade path: [0.131 → 0.132](docs/migrations/0.131-to-0.132.md). A row

package/README.md

@@ -182,38 +182,9 @@ const doc = Document.storageVersionOf(content)
   : Document.fromMarkdown(content);
 ```
 
-The `schema` value (`quillmark/document@0.131.0` for a document holding a font
-mark, `@0.129.0` for any other) is the **model version**, not the running crate
-version. It is a hand-set constant, bumped only when the `Document` model
-itself changes, so every `0.131.x` patch release reads and writes those same
-values.
-
-- **Upgrading is safe.** A newer build reads documents an older build's
-  *writer* produced. Each schema version's wire format is frozen and never
-  changes; when the model does change, the new build ships a migration that
-  converts old payloads on `fromStored`. A document you commit as your
-  canonical on-disk format keeps loading across crate upgrades until its tag
-  is retired: 0.130 reads `@0.124.0` and `@0.129.0` only, so resave an older
-  row with a 0.124 to 0.129 build before taking 0.130, as that release's
-  migration guide shows. The other exception is a row a host authored a
-  content construct of its own into — a line `kind`, container, mark `type`
-  or island `type` outside the vocabulary. Those are refused from 0.113 on;
-  see that release's migration guide. An island `loss` is not one of them:
-  0.115 drops the key, so a row spelling one opens whatever the class and
-  comes back without it. From 0.126 on, a row whose `$quill` is a lone major,
-  `memo@1`, or whose body nests past 12 levels is refused too; rewrite it
-  before upgrading, as that release's migration guide shows.
-- **Downgrading is not.** `fromStored` rejects a `schema` version it does not
-  read, newer than the build or retired, rather than guessing at its format.
-  Don't feed documents written by a newer build back into an older one.
-
-`Document.currentStorageVersion()` is the newest tag this build writes. A
-save writes the oldest tag that holds the row, so a fresh row can carry an
-older tag still read: a row holding no font mark, `table` element, merged
-table cell or table `head` 0.130 cannot draw saves as
-`quillmark/document@0.129.0`. A tag other than `currentStorageVersion()` is
-therefore not a mismatch. Use `storageVersionOf` after `fromStored` throws,
-to tell "a version this build does not read" from "corrupt":
+The tag model, what upgrading reads, and the one-time rewrites a release asks of stored rows are in [Persistence](https://quillmark.dev/integration/persistence/).
+
+`Document.currentStorageVersion()` is the newest tag this build writes, and a save writes the oldest tag that holds the row, so a tag other than it is not a mismatch. Use `storageVersionOf` after `fromStored` throws, to tell "a version this build does not read" from "corrupt":
 
 ```ts
 try {
@@ -224,13 +195,7 @@ try {
 }
 ```
 
-`storageVersionOf` does not validate the payload: it only reads the
-`schema` field, returning `undefined` for non-JSON, non-objects, or
-payloads that don't carry one.
-
-In short: persist the `toStored` string, resave rows under a retired tag
-before upgrading past it, never downgrade. The full design (including how
-migrations are added) is in `prose/canon/DOCUMENT_STORAGE.md`.
+`storageVersionOf` does not validate the payload: it only reads the `schema` field, returning `undefined` for non-JSON, non-objects, or payloads that don't carry one.
 
 ### Cards, seeds, and addresses
 
@@ -240,12 +205,21 @@ values from the `Document` payload: there is no separate form-view projection.
 `quill.validate(doc)` scores it without invoking the backend.
 
 `quill.exampleDocument()` returns the quill's example, a filled-in page whose
-values are made up, pinned to the quill's `name@MAJOR.MINOR`; `undefined`
-when the quill has no `example.md` at its root.
+values are made up: the seeded document with each `example` the schema
+declares committed, a field's as its value and a body's as the body;
+`undefined` when the quill declares none.
+
+An LLM writes a document as JSON: `quill.authoringSchema` is its JSON Schema,
+`quill.fromAuthoring(reply)` builds and conforms the `Document` (the JSON twin of
+`quill.parse`), and `quill.toAuthoring(doc)` exports any document back, every
+rich-text field and body a Markdown string. A shape error throws
+`authoring::invalid_shape` at its JSON path; a value of the wrong type lands
+with a `conform::*` warning and `quill.validate(doc)` reports it at its
+document path.
 
 `quill.seedDocument()` returns a starter document: one card per kind, each
 carrying the kind's `seed` from `Quill.yaml` and no other field;
-`quill.seedMain()` and `quill.seedCard(kind)` seed one card. All
+`quill.seedCard(kind)` seeds one composable card. Both
 return the read `Card` shape of `doc.main` / `doc.cards`, which `doc.insertCard`
 accepts directly:
 
@@ -282,16 +256,10 @@ the content object, a `text` field as its literal string), and as authored
 through the transport door. For the `Content` either way read
 `quill.reader(doc).getContent(addr)`, which decodes through the codec the
 field's declared type names. Card-scoped verbs take a
-`CardAddr` (`{ card? }`) first: `doc.getExt({ card: 2 })`, and the batch below.
-
-Batch mutation: `doc.storeFields({}, {...})` / `doc.storeFields({ card: index }, {...})`
-apply a whole object atomically: on any invalid field nothing is applied and
-the thrown error carries one diagnostic per offending field (`path` = field
-name). The address is first (never shape-overloaded, since `card` is a legal
-field name), and parses strictly: a stray key throws rather than silently
-reading as `{}`. The main card is `{}`, or **`MAIN_CARD_ADDR`** (from
-`@quillmark/wasm`), a frozen alias that spells the intent:
-`doc.storeFields(MAIN_CARD_ADDR, {...})`.
+`CardAddr` (`{ card? }`) first: `doc.getExt({ card: 2 })`. An address parses
+strictly: a stray key throws rather than silently reading as `{}`. The main
+card is `{}`, or **`MAIN_CARD_ADDR`** (from `@quillmark/wasm`), a frozen alias
+that spells the intent: `doc.getExt(MAIN_CARD_ADDR)`.
 
 ### Typed writes: `commit*` is the default, `store*` is the quill-free primitive
 
@@ -308,13 +276,12 @@ on `Document` itself (**store** = verbatim, **set** = typed):
   on the typed path an undeclared name is a typo, not a fallback. The batch form
   (`setAll`) is all-or-nothing: an undeclared name aborts the whole write and its
   per-field diagnostics name every offending field, so a whole-form submit
-  surfaces every typo `storeFields` would silently absorb. (The raw wasm class
-  carries the quill-taking `_commitField` / `_commitFields` / `_addCard` /
+  surfaces every typo the opaque store would silently absorb. (The raw wasm
+  class carries the `_commitField` / `_commitFields` / `_addCard` / `_revise` /
   `_reviseField` ABI the writer delegates to, hidden from the `.d.ts`.)
 
 - **`store*`: the deliberate quill-free primitive.** `doc.storeField(addr, value)`
-  / `doc.storeFields(cardAddr, {...})` validate only the field
-  name/depth/kind and store the value verbatim, no quill required. Reach for it
+  validates only the field name/depth/kind and stores the value verbatim, no quill required. Reach for it
   on purpose when you *want* the opaque store: quill-agnostic storage/migration
   infra that has no bundle and must write regardless of a drifted schema;
   store-now-validate-later editors holding in-progress input that `commit`
@@ -346,7 +313,7 @@ ed.card(2).reviseBody("**note**");                  // a composable card's body;
 is lazy: it never throws; an out-of-range index throws `IndexOutOfRange` at the
 write.
 
-#### `DocumentReader` / `CardReader`: the read twin
+#### `DocumentReader`: the read twin
 
 `quill.reader(doc)` carries the writer's ephemerality and schema authority:
 
@@ -355,7 +322,7 @@ const v = quill.reader(doc);
 v.get("subject");                                   // the values form: every content leaf as its codec's text, else as stored
 v.getContent("subject");                            // the same read as a `Content`, whichever lane stored it
 v.bodyMarkdown();                                   // the main body markdown (quill-free)
-v.card(0).bodyMarkdown();                           // a card's body markdown; its fields read through get
+v.get({ card: 0 });                                 // a card's body markdown; its fields read through get
 v.resolve();                                        // the render view: blank-filled, coerced, each field tagged with its rung
 ```
 
@@ -450,15 +417,7 @@ if (cssPxPerPt > 0) {                        // 0 while the canvas has no layout
 
 ### Schema model
 
-A field declares no `required` key: nothing is required.
-
-**`default:`** — what an unanswered field renders. With one, `quill.blueprint`
-renders that value under a type-only `# <type>` annotation and the render path
-uses it when the document omits the field. Without one, the blueprint leaves the
-cell empty and an absent field blank-fills.
-
-An unanswered field draws no diagnostic. Partial documents are accepted, and
-`engine.render(quill, doc)` throws only for malformed input.
+A field declares no `required` key and an unanswered field draws no diagnostic; [`default`](https://quillmark.dev/quills/quill-yaml-reference/#default) is what an unanswered field renders.
 
 ### Errors
 
@@ -492,19 +451,11 @@ throws a real `Error` and attaches the property, so there is no constructor to
 `instanceof` against. Narrow with `isQuillmarkError`, which also works on errors
 from any build or WASM instance in the page.
 
-`diagnostics` is always non-empty: length 1 for most failures, length N for
-backend compilation errors, and `message` is derived from it. `diagnostics[0]`
-is an error. A failed Typst `engine.render` or `engine.open` also carries the
-quill's load warnings after its errors, so read each entry's `severity`. The
-same shape applies to every throw site:
+`diagnostics` is always non-empty and its first entry is an error; [Error Handling](https://quillmark.dev/integration/error-handling/) has the shape, the code namespaces and the warnings that follow. The same shape applies to every throw site:
 
 - `Document.fromMarkdown`: parse errors (missing root `$quill` metadata, YAML
   errors, `parse::input_too_large` for inputs > 10 MiB).
-- `Document` mutators (`storeField`, `insertCard`, the writer's
-  `set`, etc.): mutator failures carry a namespaced `edit::*` `code` on
-  `diagnostics[0]` (`edit::invalid_field_name`, `edit::unknown_field`,
-  `edit::index_out_of_range`, `edit::field_coercion_failed`, …). Route on
-  `diagnostics[0].code`, never on message text.
+- `Document` mutators (`storeField`, `insertCard`, the writer's `set`, etc.): a namespaced `edit::*` `code` on `diagnostics[0]`.
 - `engine.render` / `session.render`: backend compilation failures and
   validation errors.
 - An object argument carrying a key its verb does not read: the render
@@ -512,8 +463,8 @@ same shape applies to every throw site:
   key counts, a non-enumerable one and one holding `undefined` included. The
   argument must be a plain object, its prototype `null`, `Object.prototype`
   of any realm, or a null-prototype object whose keys count too, so a `Map`, a
-  class instance or `Object.create({ … })` throws. A payload item, the fields
-  object `storeFields` takes, and a `$ext` or `$seed` value read their own
+  class instance or `Object.create({ … })` throws. A payload item and a
+  `$ext` or `$seed` value read their own
   enumerable keys alone: a non-enumerable or inherited key there is neither
   read nor refused.
   The diagnostic names the key or what was passed, and carries no `code`: it