@quillmark/wasm 0.99.0 → 0.101.0

package/CHANGELOG.md

@@ -1,5 +1,112 @@
 # Changelog
 
+## v0.101.0 - 2026-08-03
+
+- refactor(core): gate the raw-plate seam behind a feature, and fixes from review
+- docs(core): state the conform gate's codes instead of linking a private item
+- refactor(core): bind a live session to its quill so apply takes a Document
+- feat(quillmark): the facade names what the read and preview flows return
+- docs(content,wasm): density pass over the island channel's prose
+- feat(content,core,wasm)!: reach islands through the op vocabulary
+- refactor(core)!: `Payload` becomes a read view
+- refactor(core)!: collapse the schema-free field projection
+- refactor(core)!: fold `Quill`'s file queries into `FileTreeNode`
+- fix(core): repoint the doc references the `from_yaml` removal orphaned
+- refactor(quillmark): move the facade gate off the front page, and stop tests reaching past it
+- docs: migration guide for the 0.101 surface removals
+- refactor(core)!: drop the lossy `QuillConfig::from_yaml`
+- refactor(core)!: `Document::from_main_and_cards` becomes crate-internal
+- feat(quillmark): the facade covers authoring, and the examples enter through the bound door
+
+
+## v0.100.0 - 2026-08-03
+
+A content field gets one resting form, and the last reserved `$` key with no
+reader is removed. All breaking changes are covered by
+`docs/migrations/0.99-to-0.100.md`. Stored documents load unchanged, but a row
+read through the bound door converges once: read-repair, not a schema-version
+event. One ordering matters, and the guide's "Legacy data" section states it —
+conform a stored population before exporting markdown from it.
+
+- refactor(core,wasm,python)!: content fields have one resting form, enforced at
+  load. `Quill::conform(&mut doc)` is the primitive and `Quill::parse(md)`
+  (parse, then conform) the convenience — the documented primary ingestion path,
+  `quill.parse` / `quill.conform` on both bindings. A `richtext` field rests as
+  the canonical content object, a `plaintext` field as its **literal string**, so
+  the stored shape is a property of the codec instead of the construction lane:
+  `equals` and content hashes stop separating semantically identical documents.
+  The typed writer commits `plaintext` as a string, and `revise_field` diffs it
+  through the literal codec (a byte-identical revise of `a \*b\*` used to commit
+  `a *b*`). `Document::parse` / `Document.fromMarkdown` stay exactly as they
+  were, demoted to the transport/repair door. Conform is idempotent, a byte no-op
+  on an already-canonical document, and reports a `conform::*` warning where the
+  strict write refuses rather than retyping or rejecting; a `$quill` naming
+  another quill errors before any mutation (#1160, #1162). See
+  `docs/migrations/0.99-to-0.100.md`
+- fix(core)!: markdown exported from a `plaintext` field resting as a content
+  object is markdown-escaped. Emit is schema-free and cannot tell a `plaintext`
+  content from a `richtext` one, so `a *literal* line` leaves as
+  `a \*literal\* line` and re-parses with the backslashes as characters — one
+  more layer per save cycle. Only the typed writer produced that rest, and the
+  string rest above deletes it rather than managing it: load, conform, and
+  re-store a population before exporting markdown from it. Markdown already
+  exported under ≤0.99 is corrupt at rest, its escapes indistinguishable from
+  authored ones, so re-export it from the conformed rows (#1159). See
+  `docs/migrations/0.99-to-0.100.md`
+- fix(core,wasm,python)!: a `plaintext` field resting as a string reads through
+  the **literal** codec, not markdown — `note: 'a *literal* line'` read back as
+  `a literal line` while render and validation kept the asterisks. Only the
+  string lane was wrong; the committed-object lane always decoded correctly, so
+  a consumer that pre-escaped a `plaintext` field to survive the read drops the
+  escaping. Alongside it, `reader.get_content` / `reader.getContent` returns a
+  content field's `Content` corpus whichever lane stored it, so a consumer
+  holding a corpus editor stops branching on the wire shape. `EditError` gains
+  `FieldNotContent` (`edit::field_not_content`) for a declared type that is not a
+  content leaf; core adds `Card::field_plaintext_content` (#1154). See
+  `docs/migrations/0.99-to-0.100.md`
+- refactor(core,wasm,python)!: card `$id` is removed — the reserved key, its
+  resolver (`Document::find_card` / `doc.cardIndexById` / `doc.card_index_by_id`),
+  the uniqueness contract (`EditError::CardIdCollision` / `EmptyCardId`, the
+  `parse::card_id_*` warnings, the storage rejection), `Card::id` /
+  `Payload::{id, set_id, take_id}` / `Document::{set_card_id, remove_card_id}`,
+  the `PayloadItem::Id` and `CardWire.id` wire members, and the projected `id` on
+  both bindings' card shape. Nothing in the engine read it and it never reached a
+  backend, so what is left after removing the machinery that served the resolver
+  is `$ext` with a reserved name. A block declaring `$id` no longer parses and a
+  blob carrying an `id` payload item no longer loads: a hard cutover, no
+  tolerate-and-ignore window. Per-card consumer keys move to `$ext` under a
+  namespace you own, with no uniqueness, no collision check, and no repair
+  (#1151). See `docs/migrations/0.99-to-0.100.md`
+- refactor(content)!: `Content`, `Line`, `Mark`, and `Island` take
+  `#[non_exhaustive]` — the four public structs the 0.99 sweep missed, that pass
+  having run as two issues split by crate. Their literals give way to `new` plus
+  the `with_*` setters on the same terms as the rest of the API; every field stays
+  `pub`, so reading and assigning are unchanged. `Delta`, `Segment`, and
+  `BaseLengthMismatch` stay open deliberately and now say so in their rustdoc.
+  A Rust source break only: nothing about the wire, the canonical bytes, or the
+  bindings moves (#1146). See `docs/migrations/0.99-to-0.100.md`
+- feat(core,wasm,python): `Diagnostic.args` — the facts `message` interpolates,
+  keyed by name, so a consumer with its own string table selects a sentence by
+  `code` and fills it itself. Values keep their JSON shape (a list arrives as a
+  list, a count as a number), engine prose never rides under a key, and a
+  formatter missing a key falls back to `message` wholesale. `prose/canon/ERROR.md`
+  § "Diagnostic args" tabulates the keys per code and a test fails when code and
+  canon disagree (#1130)
+- fix(core): the `$quill` mismatch message and hint name the pairing rather than
+  the verb. `check_quill_reference` gates every schema-bound door now, not the
+  render path alone, so a `quill.parse` failure no longer reads "was rendered
+  with". The codes (`quill::name_mismatch` / `quill::version_mismatch`) are
+  unchanged
+- test(fuzz): the resting-form invariant gains a target, stated as three
+  properties — conform is a fixed point, parse-then-conform equals typed-write
+  per content field, and a document through the markdown surface and back settles
+  after one pass (exactly, for `plaintext`, whose codec is lossless both ways)
+- docs: the cycle's stale pages are repaired. Both binding READMEs gain the bound
+  door and the corpus read, `revise_field` is documented per declared type on all
+  four surfaces instead of as a markdown-only richtext verb, and four canon claims
+  that outran the tree are corrected
+
+
 ## v0.99.0 - 2026-08-01
 
 The 1.0.0 API freeze lands ahead of the tag, and the content codec closes its
@@ -119,109 +226,6 @@ loads byte-identically and `0.99` writes the same bytes for the same content.
   `serde_saphyr` types stay out of `quillmark-core`'s public API (see the YAML
   engine entry above), so nothing downstream moves
 
-<!-- seed: commits since v0.98.0, confirm the entries above cover them, then delete this comment
-- chore(core): move the time format descriptions to parse_borrowed::<3>
-- build(deps): bump lopdf from 0.42.0 to 0.44.0
-- build(deps): bump thiserror in the cargo group across 1 directory
-- build(deps): bump taiki-e/install-action
-- chore(core): bump serde-saphyr to 1.0
-- Split lint back out of test
-- Link every shipped artifact in CI, and carry v0.99.0's notes forward
-- dense-prose pass over the CI scope
-- Cut CI to one job per shipped surface
-- Stop the release from pushing to a branch that takes only PRs
-- Fix three claims the independent review falsified
-- Correct the release notes' exhaustive-type count
-- dense-prose pass over the review's scope
-- Close the two payload doors the depth guard missed
-- Ship the license the workspace actually grants
-- Correct the release docs against the tree they describe
-- CLAUDE.md: tighten the Tests section to house voice
-- CLAUDE.md: drop `uv run` from the Python binding flow
-- CLAUDE.md: gate local binding builds, name the cheap profiles
-- chore(release): v0.99.0
-- Split serial.rs's fixed-point claim into the two it conflated
-- Make Fidelity the one place a loss class is spelled
-- Make an island's loss class injective instead of guarded
-- dense-prose and simplify passes over the handle-check work
-- Keep the colon out of embedded YAML values
-- Sweep the em-dash out of comments and prose
-- Refuse a core handle from a second copy, everywhere
-- Replace the em-dash ban with the rule the exemplars follow
-- dense-prose pass over the foreign-handle prose
-- Extend the policy to the writer/reader lane, and draw the read/write line
-- Keep the patched method names, and stop over-claiming in the warning
-- Tolerate foreign core handles on the by-reference methods
-- Correct the quill file-size cap doc and MiB units
-- Collapse the rustdoc gate onto --workspace
-- dense-prose pass over the release-readiness fixes
-- Close the release-readiness gaps found against v0.98.0
-- Drop the semver job
-- Trim the Python typing work to its load-bearing parts
-- Revert "Record KnownIslandType::ALL's slice shape in the 0.99 guide"
-- Record KnownIslandType::ALL's slice shape in the 0.99 guide
-- Close the Python Tier-1 gaps: single-card reads and a typed surface
-- Drop the top-level-await plugin the vite 8 test config cannot load
-- Shape the reserved-name lists as slices
-- Shape the island ALL as a slice; list the 0.99 guide as published
-- Prune rottable duplication from CLAUDE.md
-- Adopt the editor's dense-prose rewrite; compress CLAUDE.md
-- build(deps): bump the cargo group across 1 directory with 12 updates
-- build(deps): bump the actions group across 1 directory with 11 updates
-- build(deps): bump tsify from 0.4.5 to 0.5.6
-- build(deps): bump toml from 0.8.23 to 1.1.3+spec-1.1.0
-- build(deps): bump similar from 2.7.0 to 3.1.1
-- build(deps): bump serde-saphyr from 0.0.23 to 0.0.29
-- Run the semver job on release PRs, not on every one
-- Drop the dead check-cfg rustflag that crashed the semver job
-- docs: dense-prose pass over the new test comments
-- dense-prose pass over the branch
-- Gate the compatibility promise mechanically, and write it down
-- test(bindings): cover the WASM and Python exports nothing exercised
-- Close the struct half of the 1.0.0 non_exhaustive sweep, and seal Backend
-- test(pdfform): drive unbound text/checkbox/choice through the fixture
-- Move the workspace to edition 2024
-- build(deps-dev): bump vitest in /crates/bindings/wasm
-- build(deps-dev): bump typescript in /crates/bindings/wasm
-- prose: drop the readiness proposal and SECURITY.md
-- ci: drop the Windows matrix from the test job
-- Finish the coerce_value_strict cleanup in the fuzz crate
-- dense-prose pass across the code and docs
-- Revert the wasm job to `npm install`
-- Trim CI to the checks v1.0.0 actually needs
-- Cut the two CI costs that buy nothing
-- Clear the RUSTSEC vulnerabilities the audit job actually found
-- Pin the tree to LF so the Windows runner reads what the test wrote
-- Cleanup pass: cut the machinery the fix did not need
-- prose: record what landed against the v1.0.0 readiness findings
-- fuzz: cover the four JSON decode lanes the bindings expose
-- Declare and hold an MSRV
-- Ship the license text, verify the packages, scan the dependencies
-- Open the engine crates' public enums ahead of the 1.0.0 freeze
-- Hide the workspace-internal seams from the published surface
-- typst: quill-load defects become session warnings, not stderr
-- core: own the YAML boundary error, and budget the third entry point
-- prose: index the v1.0.0 readiness findings against their issues
-- prose: v1.0.0 production-readiness review
-- Drop issue markers; dense-prose the unreleased 0.99 guide
-- dense-prose pass over the PR 1097 scope
-- docs: record the op-wire key-order change in the unreleased guide
-- content: carry the `<u>` bit on the event, not in a shared set
-- content: one key sorter for the canonical form
-- content: bound opaque JSON payload depth on the Value lane
-- content: make a vocabulary promotion carry its own legacy form
-- content: simplify pass over the codec-gap changes
-- content: house voice on the codec-gap comments
-- content: close the three v1.0.0 codec gaps before the freeze
-- content: cut the enumerated halves of the two open-set tests
-- content: prune tests that assert what a neighbour already pins
-- content: fold the authored-lane scan into the shared cell walk
-- content: split the wire lanes on reserved-name reuse (#1084, #1085, #1086)
-- docs: trim the migration index to a routing table; drop duplicate links
-- refactor(typst): re-export span_scan/extract instead of forwarding
--->
-
-
 ## v0.98.0 - 2026-07-28
 
 Five breaking changes, all covered by `docs/migrations/0.97-to-0.98.md`.
@@ -370,7 +374,7 @@ Stored documents are unaffected: a `0.97` blob loads byte-identically and
 - **breaking** core,wasm,python: a schema-bound read view — `Quill::view(&doc)` / `quill.view(doc)`, the read twin of `quill.writer(doc)`. `view.get(addr)` interprets each field by its declared type (a `richtext` field → markdown, a `plaintext` field → its literal text via the plaintext codec, every other type → its canonical value verbatim), returns absent as `undefined` / `None`, and — the authority the quill-free `getMarkdown` lacks — throws `UnknownField` for a name the schema does not declare and `FieldRichtextDecode` for a content field holding an undecodable value. Core `TypedReader::get` returns a `ReadValue` (`Markdown`/`Plaintext`/`Value`); `view.card(i)` is the card cursor; core adds `Card::field_plaintext` (the `to_plaintext` twin of `field_markdown`). **`getMarkdown`'s field half retires**: `getMarkdown` / `get_markdown` / `get_card_markdown` are now body-only (WASM `getMarkdown` takes a `CardAddr`, a present `field` throws; Python drops the `name` parameter) — a field's markdown is read through `view.get`. The quill-free body projection stays on `Document` (#978)
 - **breaking** content: one delta-application contract — implicit trailing retain is `try_apply`'s semantics (a short delta retains the untouched remainder; the error is over-consumption only), `apply` panics on an over-long delta instead of clamping (clamping is silent corruption), and `extend_to_base` is removed. `split_line` / `join_line` rebase marks through their one-char `\n` splice with `map_pos` — the same mapping the text-delta channel uses — so marks no longer drift across line ops and `apply_field_change` canonicalizes once (a single terminal normalize instead of one per stage); line sync rebuilds in one forward pass instead of per-`\n` `Vec` splices. Mark ops are specified in final-text coordinates (post-delta, post-line-op — the frame they validate against) (#926, #987)
 - **breaking** core: storage blobs tagged `@0.81.0` / `@0.82.0` fail as an unknown schema version — the read-only `V0_81_0` / `V0_82_0` DTO trees and their forward migrations are retired (nothing persisted on this lineage predates `@0.92.0`; `0.82.0` was yanked). `V0_92_0` stays the oldest shape read, and its payload types back the current write path. DOCUMENT_STORAGE.md records variant retirement as the policy when no stored population remains (#929)
-- **breaking** core,wasm,python: the markdown projection stops appending a trailing newline — `to_markdown` projects a *value*, not a file, so `field_markdown` / `body_markdown` (WASM `getMarkdown` / `exportMarkdown`, Python `export_markdown` / `get_markdown`) no longer grow a `\n`; `writer.set("subject", "Hello")` reads back as `"Hello"`, not `"Hello\n"`. `.qmd` files still end in one newline (owned by `Document::to_markdown`, the file writer) and the content fixed point is unchanged (import is newline-insensitive) (#965)
+- **breaking** core,wasm,python: the markdown projection stops appending a trailing newline — `to_markdown` projects a *value*, not a file, so `field_markdown` / `body_markdown` (WASM `getMarkdown` / `exportMarkdown`, Python `export_markdown` / `get_markdown`) no longer grow a `\n`; `writer.set("subject", "Hello")` reads back as `"Hello"`, not `"Hello\n"`. The content fixed point is unchanged (import is newline-insensitive) (#965)
 - **breaking** all: rename the content genus off its codec's name — crate `quillmark-richtext` → `quillmark-content`, type `RichText` → `Content` (and `RichTextLine`/`RichTextContainer`/`RichTextMark`/`RichTextIsland` → `ContentLine`/…), const `RICHTEXT_MEDIA_TYPE` → `CONTENT_MEDIA_TYPE` and its wire string `application/quillmark-richtext+json` → `application/quillmark-content+json`, `#[serde(skip)]` companion caches `FieldSchema::{default,example}_corpus` → `_content`, `SegmentMap.corpus: Range<usize>` → `.content`, Typst-emitter `EmittedContent` → `Emission` (it is markup + source map, not a Typst `content` value). Schema tokens `richtext` / `plaintext`, `FieldType::{RichText,PlainText}` variants, and the codec-specific `field_richtext` / `FieldRichtext*` / `apply_field_richtext_change` / `richtext(inline)` surface are unchanged — those name codecs, not the model. Canonical body JSON is nameless, so stored documents don't migrate; `contentMediaType` consumers pin to the new spelling. Retires the informal "corpus" noun to end the code/prose split (#976)
 - **breaking** core,wasm,python: `getMarkdown` / `get_markdown` / `get_card_markdown` stop conflating an absent field with a present-but-not-richtext one — a present field that does not decode as richtext (a scalar/array/object a `storeField` wrote) now throws `FieldRichtextDecode` instead of reading back `undefined` / `""`; absence still returns the absent shape. Core `Card::field_markdown` becomes `Option<Result<String, RichtextDecodeError>>` (the projection twin of `field_richtext`). Rule: absence returns, mismatch raises; read the raw value with `get` (#968)
 - feat(core,wasm): typed, anchor-preserving field revise — `TypedWriter::revise_field` / `CardWriter::revise_field` and `writer.reviseField` / `writer.card(i).reviseField` wrap core `Card::revise_field_checked` (diff-rebase surviving anchors, then schema-conform the result); the schema-bound verb lives on the writer, where the schema is (#957, #966)

package/README.md

@@ -94,10 +94,37 @@ For an example-filled starter use `quill.seedDocument()`. Throws on an
 invalid quill reference.
 
 ### `Document.fromMarkdown(markdown)`
-Parse markdown to a parsed document. Throws a JS `Error` (with `.diagnostics`
-attached, see [Errors](#errors)) on any parse failure, including a missing
-root `$quill` metadata line, malformed YAML, and inputs over the 10 MiB
-`parse::input_too_large` limit.
+Parse markdown to a parsed document, quill-free: the **transport door**
+(migrations, `$ext` stamping, a quill that will not load, opening a document to
+fix its `$quill`). Throws a JS `Error` (with `.diagnostics` attached, see
+[Errors](#errors)) on any parse failure, including a missing root `$quill`
+metadata line, malformed YAML, and inputs over the 10 MiB
+`parse::input_too_large` limit. A content field rests as authored; `quill.parse`
+below is the bound door that lands it at its canonical rest.
+
+### `quill.parse(markdown)` / `quill.conform(doc)`
+The **bound door**, and the primary ingestion path. `quill.parse` is
+`Document.fromMarkdown` followed by `conform`: the returned document's declared
+content fields rest at one form per codec (a `richtext` field as the canonical
+content object, a `plaintext` field as its literal string), so `getStored`
+answers "corpus or string?" by the field's declared codec rather than by how the
+document was built. Parse warnings and the `conform::*` warnings both ride
+`doc.warnings`.
+
+`quill.conform(doc)` is the same walk in place on a document that arrived any
+other way (`fromJson`, a stored row), returning the `conform::*` `Diagnostic[]`
+(`[]` when everything rested). It is idempotent and a byte no-op on an
+already-canonical document, YAML comments included, so calling it on every load
+is safe. A `!must_fill` marker anywhere in a field's value skips that field; a
+value the strict write refuses stays as authored under a warning. Both throw
+when the document declares a `$quill` this quill does not answer to, before any
+mutation.
+
+```ts
+const doc = quill.parse(markdown);          // rests canonical
+const stale = Document.fromJson(row);
+const diags = quill.conform(stale);         // converges in place
+```
 
 ### `doc.toMarkdown()`
 Emit canonical Quillmark Markdown. Type-fidelity round-trip safe:
@@ -259,7 +286,11 @@ card's. Reads are total over the field axis (`getStored` → `undefined`, `isFil
 an absent field; only an out-of-range card throws); field writes throw on a body
 address. `getStored` is the verbatim transport read, distinct from the interpreted
 `quill.reader(doc).get`; `getMarkdown` is the body markdown read (a `CardAddr`; a field's
-markdown is read through `quill.reader(doc).get(field)`). Card-scoped verbs take a
+markdown is read through `quill.reader(doc).get(field)`). A content field's stored
+form follows how the document was built (a canonical content object when the
+typed writer committed it, the authored string when a markdown parse produced
+it), so for the corpus 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 }, {...})`
@@ -324,6 +355,24 @@ ed.card(2).set("body", "**note**");                 // composable card, resolved
 is lazy: it never throws; an out-of-range index throws `IndexOutOfRange` at the
 write.
 
+#### `DocumentReader` / `CardReader`: the read twin
+
+`quill.reader(doc)` carries the writer's ephemerality and its schema authority:
+
+```ts
+const v = quill.reader(doc);
+v.get("subject");                                   // by declared type: richtext → markdown, plaintext → literal text
+v.getContent("subject");                            // the same read as a Content corpus, whichever lane stored it
+v.getBody();                                        // the main body markdown (quill-free)
+v.card(0).get("body");                              // a card field, resolved by its $kind
+```
+
+`get` projects and `getContent` returns the corpus; both decode through the codec
+the field's **declared type** names, which is why they bind the quill and the
+verbatim `doc.getStored` does not. An undeclared name throws `UnknownField`, a
+type that is not a content leaf throws `FieldNotContent`, and an undecodable
+value throws `FieldRichtextDecode`; an absent field reads back `undefined`.
+
 ### `engine.render(quill, parsed, opts?)` vs. `engine.open(quill, parsed)`
 
 Use **`engine.render`** for one-shot exports (PDF/SVG/PNG): compiles, emits

package/backends/pdfform/wasm.d.ts

@@ -32,14 +32,13 @@ export type PayloadItem =
  *
  * `$` system entries are hoisted to named fields: `kind` (the `$kind`, empty
  * string when none), optional `quill` (the `$quill` `name@version`, main card
- * only), optional `id` (`$id`), optional `ext` (`$ext`), and optional `seed`
+ * only), optional `ext` (`$ext`), and optional `seed`
  * (the `$seed` per-kind overlay map, main card only). `payloadItems` carries
  * user fields and comments in order.
  */
 export interface Card {
     kind: string;
     quill?: string;
-    id?: string;
     ext?: Record<string, unknown>;
     seed?: Record<string, unknown>;
     payloadItems: PayloadItem[];
@@ -63,7 +62,6 @@ export interface Card {
 export interface CardInput {
     kind: string;
     quill?: string;
-    id?: string;
     ext?: Record<string, unknown>;
     seed?: Record<string, unknown>;
     payloadItems?: PayloadItem[];
@@ -242,13 +240,42 @@ export type LineOp =
 | { op: "setContainers"; line: number; containers: ContentContainer[] }
 | { op: "setContinues"; line: number; continues: boolean };
 
+/**
+ * An island edit: the only channel that reaches an island's payload, a table's
+ * cells or an image's url.
+ *
+ * Both ops move one island entry and leave the field's text and marks alone, so
+ * an island edit keeps every identity anchor in the field. That is why a table
+ * edit lowers to `applyChange` rather than `install`, which drops them all.
+ *
+ * `set` addresses an existing island by `id`; an `id` no island carries throws
+ * rather than passing silently. `insert` places a new island's slot at `at` (a
+ * post-delta USV position) together with its entry, so a slot never exists
+ * without an island behind it; its `id` must be non-empty and unused. Deleting
+ * an island needs no op: a `delta` that removes its slot drops the island.
+ *
+ * A `set` stores the `loss` it is given: nothing re-derives the class from the
+ * new `props`, so a write that changes what markdown can carry must say so.
+ *
+ * An island is *inline* (a slot inside a paragraph) unless its line says
+ * otherwise. A **block** island is one bundle of all three channels, in the
+ * order they apply: `delta` inserts the `\n` that opens the line, `islandOps`
+ * inserts the slot, `lineOps` tags the line `{ op: "setKind", kind: "island" }`.
+ * `{ op: "split" }` cannot open that line, since line ops run after island ops.
+ */
+export type IslandOp =
+| ({ op: "set" } & ContentIsland)
+| ({ op: "insert"; at: number } & ContentIsland);
+
 /**
  * A committed content edit bundle for `applyChange`: a text `delta` (default no
- * text change), then `lineOps`, then `markOps` (mark ranges are in post-delta
- * coordinates). Every field is optional.
+ * text change), then `islandOps`, then `lineOps`, then `markOps` (mark ranges
+ * are in final-text coordinates: every earlier channel applied). Every field is
+ * optional.
  */
 export interface ChangeBundle {
     delta?: Delta;
+    islandOps?: IslandOp[];
     lineOps?: LineOp[];
     markOps?: MarkOp[];
 }
@@ -593,6 +620,16 @@ export interface Diagnostic {
      */
     path?: string;
     hint?: string;
+    /**
+     * The facts `message` interpolates, keyed by name. With `code`, the
+     * substitution unit needed to word this diagnostic in another language;
+     * `prose/canon/ERROR.md` § \"Diagnostic args\" tabulates the keys per code.
+     *
+     * Declared optional explicitly because `tsify` does not read
+     * `skip_serializing_if`: without this, a field the runtime omits is
+     * declared required. `sourceChain` carries that mismatch.
+     */
+    args?: Record<string, unknown>;
     sourceChain?: string[];
 }
 
@@ -714,11 +751,16 @@ export class Document {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * **Apply** a committed content edit `bundle` (`{ delta?, lineOps?, markOps? }`)
-     * at `addr`, the editor splice: text delta first, then line ops, then mark
-     * ops (mark ranges in final-text coordinates), each all-or-nothing. An absent
+     * **Apply** a committed content edit `bundle`
+     * (`{ delta?, islandOps?, lineOps?, markOps? }`) at `addr`, the editor
+     * splice: text delta first, then island ops, then line ops, then mark ops
+     * (mark ranges in final-text coordinates), each all-or-nothing. An absent
      * `addr.field` targets the body, an absent `addr.card` the main card.
      *
+     * The island channel keeps a table or image edit on the op path: it moves
+     * the island alone, so the anchors elsewhere in the field survive an edit
+     * `install` would clear.
+     *
      * Throws on an out-of-range card, a field that is not richtext, a malformed
      * bundle, or an op that applies out of bounds (the value is unchanged on a
      * failed apply).
@@ -739,13 +781,6 @@ export class Document {
      * verbs.
      */
     card(index: number): Card;
-    /**
-     * The index of the composable card whose `$id` equals `id`, or
-     * `undefined` when none carries it. Resolves the durable card handle
-     * without a hand-rolled scan over [`cards`](Self::cards); `$id` is
-     * unique per document, so at most one card matches.
-     */
-    cardIndexById(id: string): number | undefined;
     clone(): Document;
     /**
      * Schema version this build writes via [`toJson`](Document::to_json).
@@ -813,8 +848,7 @@ export class Document {
     getMarkdown(addr?: CardAddr): string;
     /**
      * Read the **verbatim stored value** at `addr`: the raw payload value of a
-     * field (a content object for a richtext field, a scalar/array/object
-     * otherwise), or the **body content** when `addr.field` is absent. A bare
+     * field, or the **body content** when `addr.field` is absent. A bare
      * string is `Addr` shorthand for `{ field }`. Reads are total over the field
      * axis: an absent field is `undefined`; only an out-of-range `addr.card`
      * throws `edit::index_out_of_range`. Needs no schema, so it lives on
@@ -822,6 +856,16 @@ export class Document {
      * the interpreted schema-plane [`reader.get`](Self::reader_get). For the
      * markdown projection use [`getMarkdown`](Self::get_markdown) (body) or
      * `reader.get` (a field's declared type).
+     *
+     * **A content field at rest has one stored form per codec**: a `richtext`
+     * field holds the canonical content object, a `plaintext` field its literal
+     * string. A document that came through the bound door (`quill.parse` /
+     * `quill.conform`) is at rest, so this read no longer depends on which lane
+     * built it. A document that came through the transport door
+     * (`Document.fromMarkdown`, a legacy stored row) may rest as authored until
+     * it is conformed, and this read reports what is there. For the corpus
+     * either way, use the schema-plane `reader.getContent`, which decodes
+     * through the codec the field's declared type names.
      */
     getStored(addr: Addr | string): unknown;
     /**
@@ -1054,6 +1098,12 @@ export class Document {
      */
     readonly main: Card;
     readonly quillRef: string;
+    /**
+     * The non-fatal diagnostics of the load that produced this document: parse
+     * warnings, plus the `conform::*` warnings when it came through
+     * `quill.parse`. Session state, not document value: `equals` and the
+     * storage DTO exclude it, and `fromJson` / `loadJson` clear it.
+     */
     readonly warnings: Diagnostic[];
 }
 
@@ -1185,6 +1235,23 @@ export class Quill {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Land `doc`'s declared content fields at their canonical rest **in
+     * place**, returning the `conform::*` diagnostics for the values that would
+     * not commit (an empty array when everything rested).
+     *
+     * The read-repair verb: a document that arrived through the transport door
+     * (`fromMarkdown`, `fromJson`, a stored row) converges here, and is then
+     * eligible for rewrite under its current schema tag. Idempotent, and a
+     * no-op on an already-canonical document: an equal value is not rewritten,
+     * so YAML comments and stored bytes survive.
+     *
+     * A `!must_fill` marker anywhere in a field's value skips that field (the
+     * marker is the state), and a value the strict write refuses stays as
+     * authored with a diagnostic. Throws when `doc` declares a different
+     * `$quill`, before any mutation.
+     */
+    conform(doc: Document): Diagnostic[];
     /**
      * Build a quill from a file tree. Pure: no backend, no engine; the
      * declared backend is resolved later, at render time.
@@ -1195,6 +1262,21 @@ export class Quill {
      * canonical shape.
      */
     static fromTree(tree: Map<string, Uint8Array>): Quill;
+    /**
+     * Parse `markdown` and conform it against this quill: the **primary
+     * ingestion path**, and the bound twin of the schema-free
+     * `Document.fromMarkdown`. The returned document rests at its canonical
+     * form (a `richtext` field as a content object, a `plaintext` field as its
+     * literal string), so `getStored` no longer answers "corpus or string?"
+     * with "depends how this document was built".
+     *
+     * Parse warnings and the `conform::*` diagnostics both land on
+     * `doc.warnings`. Throws on a parse failure, or when `markdown` declares a
+     * `$quill` this quill does not answer to: nothing conforms under the wrong
+     * schema. To open a document whose `$quill` is stale, use the transport
+     * door (`Document.fromMarkdown`, `setQuillRef`, then `quill.conform`).
+     */
+    parse(markdown: string): Document;
     /**
      * The resolved-value view of `doc` against this quill's schema: for every
      * declared field the value the render projection would use and the