@quillmark/wasm 0.103.0 → 0.105.0

package/CHANGELOG.md

@@ -1,5 +1,204 @@
 # Changelog
 
+## v0.105.0 - 2026-08-14
+
+- feat(core,wasm,python)!: a `Content` nested inside a composite field is
+  readable at its own codec. `TypedReader::get_content_at(name, path)` (and the
+  `CardReader` twin, `reader.getContentAt(addr, path)` in JS,
+  `reader.get_content_at(name, path)` in Python) walks a `PathSegment` path
+  through the field schema — `items` for an index, `properties` for a key — to
+  the leaf whose declared type names the codec, then decodes through the same
+  dispatch the whole-field read uses. So an `array<richtext>` element, an
+  `object`'s content property and a leaf under both each read back the same
+  `Content` whatever their resting form, where before every one of them
+  answered `FieldNotContent` and the consumer had to decide for itself what the
+  stored bytes meant (#1243). The empty path *is* `get_content`. A path naming
+  nothing in the stored value reads absent rather than throwing: an editor's
+  row index goes stale between derive and read, and that is the axis a repeater
+  mutates. `Addr` deliberately gains no element axis — the path is the read's
+  own argument, since `storeField` / `isFill` / `applyChange` could not answer
+  one. **Breaking**: `EditError::FieldDecode` and `EditError::FieldNotContent`
+  each gain an `at: Vec<PathSegment>` field carrying the in-field path, so the
+  diagnostic anchors at `main.paragraphs[1]` and parses back to those segments;
+  `field` stays a bare field name and `args` is unchanged. `FieldNotContent`
+  now names the type *reached*, so a `string[]` element reports `string` rather
+  than the field's `array`.
+- feat(core,wasm)!: `must_fill:` on a field declares the **obligation** axis.
+  `default:` carried the fill value and the obligation signal on one bit, so
+  only that 2x2's diagonal was reachable; a safe value that still wants a
+  human's confirmation (`default: UNCLASSIFIED` with `must_fill: true`) and a
+  genuinely optional field with nothing to suggest (`must_fill: false`) now
+  each have a spelling. Left unset it derives `default.is_none()`, so no
+  existing quill's blueprint marker set changes. `Quill::validate` gains a
+  second trigger under the one `validation::must_fill` code, named by a
+  `trigger` arg: `marker` for a `!must_fill` tag the document carries, and
+  `unauthored` where the schema obliges a cell the document leaves absent or
+  present-null. The second closes a hole — `validate_fills` walked only the
+  payload, so a hand-written or programmatically built document drew no
+  completeness signal whatever `Quill.yaml` declared. **Breaking**: a merely
+  incomplete document no longer validates clean. Absence is still never
+  *malformed* and still never gates render, but a consumer reading "any
+  diagnostic ⇒ not done" now sees a warning per unauthored obliged cell on
+  documents that were silent. The obligation keys on cell presence rather than
+  the resolved source rung, so a must-fill leaf inside a container someone
+  touched still warns; a typed dict is never itself a cell and recurses to its
+  leaves, while an array is one cell, `[]` being a real answer. Authoring the
+  field's blank discharges it and `field: null` does not: null ≡ absent stays
+  unqualified on the value ladder, but obligation asks whether a human made a
+  call. Seeding stamps the marker on example-seeded obliged cells, so a fresh
+  seed and an empty document report the same cells, and the transform schema
+  carries `quillmark:must_fill` (#1255).
+- fix(core,wasm,pdfform)!: a field's **blank** — its spelling of "explicitly
+  nothing" — is a property of the field rather than a member of its type's
+  domain, and an `enum`'s is `""`. The render floor for a defaultless enum
+  returned `values.first()`: a choice nobody made, indistinguishable at the
+  plate from a deliberate one and reachable from a cosmetic `values:` reorder.
+  An unanswered enum now renders `""`, so a reorder is render-safe for every
+  document and only removing or renaming a member breaks
+  ([VERSIONING.md](prose/canon/VERSIONING.md)). **The accepted domain widens to
+  `values ∪ blank` for *every* enum**, defaulted ones included: `format: ""`
+  was a fatal `EnumViolation` and now coerces, validates and reaches the plate.
+  **A plate must therefore branch exhaustively over `values ∪ blank`** — an
+  `else` fallback re-opens exactly the fabrication the blank closes, and a
+  downstream package that asserts membership fails the compile outright. Note
+  `data.at(key, default: X)` is not a guard here: blank-filled render makes
+  every declared key present, so its `default:` is dead code and the blank
+  flows through. **Breaking**: `zero_value` → `blank`, `FieldSource::Zero` →
+  `Blank` and its wire token `"zero"` → `"blank"`; `""` declared in `values:`
+  is a load error (`quill::enum_blank_member`), the engine supplying the blank
+  instead; and `date: ""` renders blank rather than falling back to a
+  `default:`, settling a three-way disagreement between coercion, validation
+  and the floor. `default: ""` stays valid and keeps its meaning — `values:`
+  enumerates choices, `default:` is a value, and the blank is a legal value
+  that is never a choice. Additive: `ui.blank_title` labels an enum's blank and
+  rides the transform schema as `quillmark:blank_title`; that schema's `enum:`
+  leads with the blank, so a standard JSON-Schema validator accepts what the
+  engine accepts, and pdfform Choice widgets lead their options with it too. A
+  consumer's picker must keep the blank selectable and re-selectable — returning
+  to it is how an author clears a cell back to unset.
+  `integer`, `number` and `boolean` keep `0` / `false` as their blank,
+  indistinguishable from an authored zero — a permanent seam, since a wire
+  `none` would cost the totality the floor exists to buy. Full guide:
+  [0.104 → 0.105](docs/migrations/0.104-to-0.105.md) (#1254).
+- fix(fixtures,docs): the three fixture plates that dispatch on `$kind` read it
+  with a bare `card.at("$kind")`, which panics on a kindless card, and guarded
+  declared fields against an absence blank-filled render makes impossible.
+  Plate authors copy the fixtures rather than `PLATE_DATA.md`, so the fixtures
+  were teaching both the unsafe metadata read and a dead presence check.
+  `classic_resume` carried the live consequence: `url` is declared with no
+  `default:`, so the floor delivers `""`, `default: none` never fires, and the
+  package's `url != none` test always passes — an empty Courier element where
+  the block should have been skipped. Its `subheading-*` guard cost an empty
+  grid row the same way. Declared fields now guard their *value*, and
+  `docs/quills/typst-backend.md` states the rule as a table over the three key
+  kinds. `fixture_quills_render_test` renders every fixture quill's seed
+  document — the net that was missing, since `classic_resume`'s plate had no
+  test reaching it (#1256, #1257).
+- test(typst): `plaintext` reaches regions and navigation by inheritance — the
+  render floor coerces its resting literal to a content object, the backend
+  classifies that object by `contentMediaType` alone, and the shared lowering
+  emits it with a segment map — and every step was load-bearing and untested,
+  with the classification predicates named for richtext so the sharing read as
+  a coincidence. Pinned at engine altitude, because a test driving the backend
+  directly hand-builds the content object, bypassing the floor's coercion, and
+  would stay green through a regression that silently empties `regions()`. The
+  predicates are `is_content_field` / `is_content_array_field` /
+  `is_inline_content_field`, and `PREVIEW.md` names plaintext beside richtext
+  in its producer list (#1247, #1250).
+
+## v0.104.0 - 2026-08-13
+
+- feat(core,wasm): a quill declares, per body, the block constructs its plate
+  does not typeset (`main.body.unsupported`, `card_kinds.<k>.body.unsupported`;
+  names from `heading`, `rule`, `code`, `list`, `quote`, `table`, `image`).
+  A body holding one anyway draws the non-fatal `plate::unsupported_construct`,
+  a fifth warning family, on the pre-render walk `Quill::parse` runs beside
+  `conform`: one diagnostic per (body, construct) carrying the count in `args`
+  and the body's path, so occurrences collapse rather than scatter. The
+  declaration also rides `QuillConfig::schema()` to the editor, which is the
+  half a render-time warning could not serve: it answers before the gesture.
+  Nothing verifies a declaration — a plate that drops an undeclared construct
+  stays as silent as before. `usaf_memo` declares `rule`; empty everywhere
+  else, so no existing quill's schema or warnings change.
+- fix(fixtures): `usaf_memo`'s `render-body` drained its heading buffer in the
+  three shapes that used to discard it. A heading with nothing after it (the
+  buffer died with the loop, taking a list item's bullet with it), a heading
+  whose next element opened a *different* list item (its text was delivered
+  into that item), and a heading following a heading (the assignment overwrote
+  the earlier one) each lost their text with nothing in the render to say so.
+  The run-in style is unchanged where it was right: a heading joins the next
+  block of its own item, or the next paragraph at top level.
+- fix(content)!: `to_markdown` writes `***` for a thematic break, not `---`.
+  `- ` + `---` is four dashes separated by spaces, which re-imports as a
+  top-level break, so a rule as a bullet item's first block lost its item on
+  every markdown round-trip. The canonical spelling is now the one with the
+  fewest other readings (`---` is also a setext underline and the root-block
+  front-matter opener). Exported markdown changes for documents holding a
+  rule; the content model, wire data and rendered output do not.
+- refactor(core,pdfform,cli,wasm)!: the `enum:` modifier on `type: string`
+  retires. `type: enum` with a `values:` list is the one spelling of a finite
+  string domain; `enum:` on any type is now `quill::field_parse_error`, whose
+  message names the replacement — it is the only diagnostic a quill written
+  against the modifier ever received, since the deprecation shipped in 0.94
+  with no warning code behind it. `QuillConfig::schema()` re-emits every
+  domain as `values:`, so a consumer reading `enum:` off the schema echo (the
+  wasm `QuillFieldSchema.enum`, dropped here) reads `values:` instead. The
+  `usaf_memo` and `sample_form` fixtures migrate; wire data and rendered
+  output are unchanged, the projections being domain-keyed already.
+- fix(core): `build_transform_schema` keys a field's finite domain on the
+  domain itself rather than the `Enum` token, joining the render floor, the
+  pdfform widget kind and the blueprint annotation. Under the retired
+  spelling every `usaf_memo` enum — `classification`, `format`, `action` —
+  projected as a bare `{"type":"string"}`, so a consumer building a
+  JSON-Schema validator from the transform schema accepted
+  `classification: "banana"` while pdfform drew the six-option dropdown for
+  the same field and `QuillConfig` rejected the value at coercion (#1237)
+- fix(core)!: geometry addresses parse segment-wise, so `locate` and
+  `fieldBoxes` answer for an address deeper than one segment. The translation
+  boundary folded a plate address's whole tail into one `Field`, so
+  `references.0` minted `main.references.0` — a string that reparses as a field
+  literally named `0`, and that the reverse direction refused outright. Both
+  spellings returned `None`, leaving caret placement and whole-field highlight
+  dead for **every** `array<richtext>` element (the flagship memo's
+  `references` among them) and for every nested key a pdfform widget binds
+  (`address.city`). `region.rs` now reads and renders a plate tail one segment
+  at a time: an all-digit segment is an array index, `$body` the body terminal,
+  anything else a field or map key.
+- change(wasm, python)!: `RenderedRegion.field`, `FieldRegion.field` and
+  `ContentHit.field` spell an array element bracketed — `main.references.0`
+  becomes `main.references[0]` — on `regions()`, `fieldAt`, `positionAt` and
+  `RenderResult.regions`. This is the spelling schema validation already emits,
+  so a `Diagnostic.path` and the geometry address for one place are now the same
+  string. A consumer finding an address's children by prefix (`startsWith(`${field}.`)`)
+  needs the `[` opener too, and any heuristic reading a trailing all-digit field
+  name as a lost index is dead.
+- feat(wasm): `doc.pathFor(addr)` mints an `Addr` as the canonical `DocPath`
+  string `Diagnostic.path` carries and `session.locate` / `session.fieldBoxes`
+  take; `doc.cardPath(i)` is the card's own root. `Document` computed the
+  kind-qualified root for every addressed write and did not hand it out, so a
+  consumer building a path restated the kind lookup, the `Addr` defaults and the
+  range guard — and a wrong-kind path is compared as a string, matching nothing
+  and drawing no highlight without throwing. Both are quill-free (the stored
+  `$kind` verbatim) and total on the index axis: a path is an anchor, not a
+  read, so a per-keystroke call needs no `try` (#1225)
+- change(wasm)!: `@quillmark/wasm` declares `engines: { node: ">=24" }`, the
+  tier CI builds and tests the bindings on and the one both devcontainers hand a
+  contributor. Nothing in the package requires it at runtime, so a Node 22
+  install fails `engines` checking without failing at import.
+- docs: `docs/migrations/0.103-to-0.104.md` carries the four breaks — the
+  retired `enum:` modifier, the bracketed index spelling, the `***` thematic
+  break and the Node floor — with the prefix-match, trailing-digit and stored
+  -markdown shapes a consumer has to fix, and the two additive surfaces
+  (`pathFor` / `cardPath`, and the `plate::unsupported_construct` family a
+  code-routing consumer gains an arm for).
+- test(core): three characterization tests pin the render floor's two
+  type-domain edges (a defaultless enum, top-level and nested in a typed
+  dictionary) and an authored empty `date` beside an empty `string`, so the
+  coercion difference between the two is one test's diff. Every shipped quill
+  declares a `default:` on every enum and none authors an empty `date`, so the
+  fixture suite reached neither path. A fourth carries a `!must_fill` tag on two
+  example-seeded cells through seed → store → load → conform. Refs #1234
+
 ## v0.103.0 - 2026-08-09
 
 - docs: `docs/integration/operations.md`, carrying what the other integration
@@ -50,32 +249,6 @@
   documents and stored blobs are unaffected. See
   `docs/migrations/0.102-to-0.103.md`
 
-<!-- seed: commits since v0.102.0, confirm the entries above cover them, then delete this comment
-- ci: tag the merge commit, and serialize a release against itself
-- ci: drop the tagger GitHub App from the release workflows
-- Cut SECURITY.md, and operations.md down to what only it can say
-- Drop the audit gate; keep the reachability finding in ci.yml's note
-- Fix two wrong claims, a dead property, and the stdout bug the review found
-- dense-prose pass over the added prose, and read the fixture once
-- Close four production-readiness gaps: audit gate, ops docs, CLI tests, PDF fuzzing
-- Drop the README's claim about the deleted sentinel patch
-- dense-prose pass: cut the restatement the change introduced
-- docs: the 0.102 → 0.103 step, and correct the surface it describes
-- The gate is the only door to the core surface
-- docs(migration): a span guide for 0.92 → 0.102
-- Cut over-specified style rules; author preference wins
-- dense-prose: remove the em-dash ban
-- dense-prose: drop the line-budget clause
-- dense-prose: wrong is worse than missing; relax em-dash ban
-- docs: dense-prose pass over the conform-scope and date-grammar prose
-- docs: migration guides are era-stamped, not immutable
-- docs(migrations): give the datetime split its corpus audit step
-- docs: scope conform to content fields, state the date corpus precondition
-- Tighten the failure-delivery prose
-- Deliver init's conflict as a rejection, not a synchronous throw
--->
-
-
 ## v0.102.0 - 2026-08-04
 
 The pre-1.0 vocabulary reset. Verbs, diagnostic codes, and two words that meant

package/README.md

@@ -6,12 +6,11 @@ Maintained by [TTQ](https://tonguetoquill.com).
 
 ## Overview
 
-Use Quillmark in browsers/Node.js with explicit in-memory trees (`Map<string, Uint8Array>` / `Record<string, Uint8Array>`).
+Quillmark in browsers and Node, over explicit in-memory trees
+(`Map<string, Uint8Array>` / `Record<string, Uint8Array>`).
 
-The package exposes **one import surface**:
-
-- `@quillmark/wasm` (the root), the **canonical API**: `init`, resolving to
-  `Quill` and `Document`, and an `Engine` that renders them.
+The package has one import surface: `@quillmark/wasm`, whose `init` resolves to
+`Quill` and `Document`, plus an `Engine` that renders them.
 
 `Quill` and `Document` are the internal Typst-less core build's own classes,
 handed out verbatim by `init`, so editor/validation code (`Quill.fromTree`,
@@ -101,11 +100,8 @@ the same value again is fine, so several entry points may each
 
 **Both failures reject.** `runtime::init_conflict` and `runtime::init_failed`
 alike ride the returned promise, so one `catch` around `await init(...)` covers
-the gate. See [Errors](#errors) for the rule this follows.
-
-**You cannot forget.** The core surface has no static export, so a call site
-that skips the await has no name to call. The precondition is structural rather
-than a convention: no load order can make one entry point pass and another fail.
+the gate. The core surface has no static export, so a call site that skips the
+await has no name to call.
 
 **Vite's dev server** pre-bundles dependencies, which moves the package away
 from its binary. Exclude it:
@@ -136,29 +132,14 @@ depend only on `quill.backendId`, and answer from the descriptor's required
 `formats`/`canvas` manifest: never loading the multi-MB backend binary and
 never cloning the quill. Use them as non-failing pre-render probes.
 
-### `Quill.fromTree(tree)`
-Build + validate a `Quill` from an in-memory tree. Pure: the declared backend
-is resolved at render time, not here. Loads no backend binary.
-
-### `new Document(quillRef)`
-A blank document: a main card carrying only `$quill`, an empty body, and no
-composable cards: the programmatic blank canvas. Absent fields resolve at
-render time (schema `default`, else type-empty zero), so nothing the caller
-did not set reaches the output. Build it up with `storeFields` / `insertCard`.
-For an example-filled starter use `quill.seedDocument()`. Throws on an
-invalid quill reference.
-
-### `Document.fromMarkdown(markdown)`
-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
+### The two doors: `Document.fromMarkdown` vs `quill.parse` / `quill.conform`
+
+`Document.fromMarkdown` is the quill-free **transport door** (migrations, `$ext`
+stamping, a quill that will not load, opening a document to fix its `$quill`).
+It needs a root `~~~` block carrying a `$quill` line, and a content field rests
+as authored.
+
+`quill.parse` is the **bound door**, and the primary ingestion path. It 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`
@@ -181,61 +162,17 @@ const stale = Document.fromJson(row);
 const diags = quill.conform(stale);         // converges in place
 ```
 
-### `doc.toMarkdown()`
-Emit canonical Quillmark Markdown. Type-fidelity round-trip safe:
-`Document.fromMarkdown(doc.toMarkdown())` returns a document equal to `doc`
-under [`doc.equals`](#docequalsother). The output is **not** guaranteed
-byte-equal to the original source: YAML quoting, key ordering, and
-whitespace are normalised. Use `equals` (not string comparison) to test
-semantic equality.
-
-### `doc.toJson()`
-Serialize the document to a versioned storage DTO: a JSON **string**
-carrying a `schema` version. Use this (not `toMarkdown`) to persist a
-document across a process restart or crate upgrade: the wire format is
-frozen per `schema` version, whereas Markdown syntax evolves. Parse-time
-`warnings` are not part of the DTO.
-
-The string is produced inside the module by `serde_json`; the JS `JSON`
-global is not involved. It is standard JSON text, so callers may
-`JSON.parse` it to inspect it, but it is intended as an opaque blob you
-persist and hand back.
-
-`toJson()` is **deterministic**: a `Document` that is `equals` to another
-serializes to a byte-identical string: across repeated calls, and across
-any crate upgrade that keeps the same `schema` version (every release does until
-the `Document` model changes; see [Storage compatibility](#storage-compatibility-across-versions)).
-Field order is fixed and object key order is preserved, so content hashes
-and string-equality dirty-checks over the output are stable.
-
-### `Document.fromJson(json)`
-Reconstruct a `Document` from a storage DTO string produced by `toJson`.
-Round-trips losslessly:
-
-```ts
-const stored = doc.toJson();        // persist this string
-const restored = Document.fromJson(stored);
-restored.equals(doc);               // true
-```
-
-Throws a JS `Error` on malformed JSON, an unknown `schema` version, or a
-malformed payload. The restored document has no parse-time `warnings`.
+### Storage compatibility across versions
 
-### `Document.tryFromJson(json)`
-Like `fromJson`, but returns `undefined` instead of throwing when `json` is
-not a valid storage DTO. Use it to branch on format without a heuristic or
-`try`/`catch` as control flow:
+Persist `doc.toJson()`, not `doc.toMarkdown()`: the DTO wire format is frozen
+per `schema` version, whereas Markdown syntax evolves, and `toMarkdown` output
+is normalised rather than byte-equal to the source. `Document.tryFromJson`
+discriminates the two formats without exceptions as control flow:
 
 ```ts
-// "JSON canonical, Markdown fallback": no exceptions, no string sniffing
 const doc = Document.tryFromJson(content) ?? Document.fromMarkdown(content);
 ```
 
-`undefined` means only "not a storage DTO"; `fromMarkdown` still throws on
-genuinely malformed Markdown.
-
-### Storage compatibility across versions
-
 The `schema` value (`quillmark/document@0.93.0`) 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.93.x` patch release reads
@@ -269,53 +206,17 @@ In short: persist the `toJson` string, upgrade freely, never downgrade. The
 full design (including how migrations are added) is in
 `prose/canon/DOCUMENT_STORAGE.md`.
 
-### `doc.equals(other)`
-Structural equality between two `Document` handles. Compares `main` and
-`cards` by value; parse-time `warnings` are intentionally excluded.
-
-Use this to debounce upstream prop updates: keep the last parsed `Document`
-and compare instead of re-parsing on every keystroke.
-
-### `doc.cardCount`
-O(1) getter for the number of composable cards (excluding the main card).
-Use this to validate indices before calling card mutators (`removeCard`,
-`storeField({ card, field }, …)`, etc.) without allocating the full `cards` array.
-
-### `quill.validate(doc)`
-
-Returns `Diagnostic[]`: the document validated against the quill schema,
-without invoking the backend. An empty array means the document is valid.
-Each diagnostic carries the canonical `validation::*` `code`, `path`, and
-`hint`. Includes the non-fatal `validation::must_fill` warning for each
-`!must_fill` marker left in the document (render zero-fills these rather
-than failing), so filter by `severity`/`code` for blockers vs. hints:
-
-```ts
-const diagnostics = quill.validate(Document.fromMarkdown(markdown));
-const errors = diagnostics.filter(d => d.severity === "error");
-```
+### Cards, seeds, and addresses
 
 To render a form editor, read field definitions from `quill.schema` (walk
 `fields` in key order: declaration order is display order) and the authored
 values from the `Document` payload: there is no separate form-view projection.
+`quill.validate(doc)` scores it without invoking the backend.
 
-### `quill.seedDocument()`
-
-Returns a starter `Document` seeded from the schema: each field's `example:`
-is committed and every other field is left absent (the render layer fills
-`default:` → type-empty zero). Illustration-first: a field with both an
-`example` and a `default` renders its example. Use as the initial state for a
-"new document" editor.
-
-```ts
-const doc = quill.seedDocument();
-const markdown = doc.toMarkdown();
-```
-
-For per-card seeding, `quill.seedMain()` returns just the `$kind: main` card
-and `quill.seedCard(kind)` returns a starter composable card (or `undefined`
-if the kind is not declared). Both return the read `Card` shape of
-`doc.main` / `doc.cards`, which `doc.insertCard` accepts directly:
+`quill.seedDocument()` returns a starter document with each field's `example:`
+committed; `quill.seedMain()` and `quill.seedCard(kind)` seed one card. All
+return the read `Card` shape of `doc.main` / `doc.cards`, which `doc.insertCard`
+accepts directly:
 
 ```ts
 doc.insertCard(quill.seedCard("note"));                 // seed → append
@@ -412,7 +313,7 @@ write.
 
 #### `DocumentReader` / `CardReader`: the read twin
 
-`quill.reader(doc)` carries the writer's ephemerality and its schema authority:
+`quill.reader(doc)` carries the writer's ephemerality and schema authority:
 
 ```ts
 const v = quill.reader(doc);
@@ -439,24 +340,10 @@ tells you which pages to repaint (`dirty ∩ visible`). Apply is transactional:
 on throw, every read keeps serving the last-good compile. Don't open a session
 per export, and don't re-open per edit: `apply` instead.
 
-### `engine.render(quill, parsed, opts?)`
-Render a pre-parsed `Document` against `quill`. Throws an
-`engine::backend_not_found` error if no registered backend matches the quill's
-declared backend.
-
-### `engine.open(quill, parsed)` + `session.render(opts?)`
-Open once, render all or selected pages (`opts.pages`).
-
-The session also exposes `pageCount`, `backendId`, `supportsCanvas`,
-`warnings` (non-fatal diagnostics of the current compile: set at `open`,
-refreshed by each committed `apply`),
-`apply(doc)` for in-place recompiles, `pageSize(page)`, and
-`paint(ctx, page, opts?)` for canvas previews. See below.
-
 A document that compiles to zero pages still produces a valid session
-(`pageCount === 0`); `paint(ctx, 0)` and `pageSize(0)` then throw
-`page index 0 out of range (pageCount=0)`. Branch on `pageCount === 0` to
-render a "no pages to preview" UI without relying on the throw.
+(`pageCount === 0`); `paint(ctx, 0)` and `pageSize(0)` then throw. Branch on
+`pageCount === 0` to render a "no pages to preview" UI rather than relying on
+the throw.
 
 ### Canvas Preview
 
@@ -480,58 +367,47 @@ canvas.style.width  = `${result.layoutWidth}px`;
 canvas.style.height = `${result.layoutHeight}px`;
 ```
 
-- `layoutScale` (default 1) sets the canvas's display-box size:
-  `layoutWidth = widthPt * layoutScale`. For on-screen canvases this is
-  CSS pixels per point. Defaults to 1 (one CSS pixel per pt).
-- `densityScale` (default 1) is the backing-store density multiplier.
-  Fold `window.devicePixelRatio`, in-app zoom, and `visualViewport.scale`
-  (pinch-zoom) into a single value here. Pass `devicePixelRatio` for
-  crisp output on high-DPI displays.
-- The effective rasterization scale is `layoutScale * densityScale`. If
-  that would exceed the safe maximum (16384 px per side), `densityScale`
-  is clamped proportionally; `result.clamped` reports it and
-  `result.effectiveDensityScale` is the density actually applied. A
-  clamped page renders soft at the same `canvas.style` size.
-- `paint` writes the whole backing store with `putImageData`, which
-  ignores the 2D context transform, `globalAlpha`, and clip. Give each
-  visible page its own `<canvas>` element: you cannot composite two pages,
-  a sub-rect, or a context transform through `paint`.
-- `paint` is always a full repaint: setting the backing-store width /
-  height clears it. No `clearRect` required. Each call re-rasterizes from
-  scratch (no per-page raster cache), so keep a page's canvas alive while
-  it stays near the viewport rather than pooling one canvas across pages:
-  an idle canvas retains its pixels for free, whereas reusing a canvas on
-  scroll re-runs a full render.
-- `pageCount` and `pageSize(page)` are stable for the session's
-  lifetime (immutable snapshot): cache them.
-- Worker support: pass an `OffscreenCanvasRenderingContext2D` and the
-  same call signature works. `layoutWidth` / `layoutHeight` are
-  informational in that mode (no CSS layout box); fold everything into
-  `densityScale`. Loading the WASM module inside a Worker is the host's
-  responsibility.
-- Backend support: gated by `supportsCanvas`. Probe upfront with
-  `engine.supportsCanvas(quill)` (or `session.supportsCanvas`) before mounting
-  a canvas-based UI; the throw on `paint` / `pageSize` remains the
-  enforcement contract and includes the resolved `backendId` for
-  debugging.
+- `layoutScale` sets the display-box size (`layoutWidth = widthPt * layoutScale`);
+  fold `devicePixelRatio`, in-app zoom, and `visualViewport.scale` into
+  `densityScale`. Their product is the rasterization scale, clamped at 16384 px
+  per side (`result.clamped`, `result.effectiveDensityScale`).
+- `paint` writes the whole backing store with `putImageData`, which ignores the
+  2D context transform, `globalAlpha`, and clip. Give each visible page its own
+  `<canvas>`: no compositing, sub-rect, or transform reaches through `paint`.
+- `paint` is always a full repaint, and there is no per-page raster cache. Keep
+  a page's canvas alive while it stays near the viewport: an idle canvas retains
+  its pixels for free, whereas pooling one canvas across pages re-renders on
+  every scroll.
+- `pageCount` and `pageSize(page)` are stable for the session's lifetime: cache
+  them.
+- In a Worker, pass an `OffscreenCanvasRenderingContext2D`; the layout
+  dimensions are informational there. Loading the WASM module inside the Worker
+  is the host's responsibility.
+- Backend support is gated by `supportsCanvas`. Probe upfront with
+  `engine.supportsCanvas(quill)`; the throw on `paint` / `pageSize` remains the
+  enforcement contract and names the resolved `backendId`.
 
 ### Schema model
 
-A field's *cell* is inferred from whether its schema declares a `default:`:
+A field carries two independent axes, and no `required` one.
+
+**Value** — what the cell holds. With a `default:`, `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, an `example` takes the cell as
+a suggested value, and an absent field blank-fills.
 
-- **Unendorsed** (no `default:`): `quill.blueprint` renders the
-  `!must_fill` marker in the value cell (carrying the field's `example` as a
-  suggested value when one exists). An absent Unendorsed field zero-fills
-  silently. A `!must_fill` marker left in the document is non-fatal: it emits
-  the `validation::must_fill` warning and still renders. Partial documents
-  are accepted; `engine.render(quill, doc)` only throws for malformed
-  input.
-- **Endorsed** (with `default:`): `quill.blueprint` renders the
-  default value with a type-only `# <type>` annotation (shippable as-is),
-  and the default is used when the document omits the field.
+**Obligation** — whether a human must author the field, declared by
+`must_fill:` and deriving from `default:`'s absence when left unset. An obliged
+field carries the `!must_fill` marker in `quill.blueprint`, and
+`quill.validate(doc)` emits the non-fatal `validation::must_fill` warning while
+the document leaves it unauthored — from either of two triggers, named by the
+diagnostic's `trigger` arg: `marker` for a marker the document still carries,
+`unauthored` for a cell the schema obliges and the document never filled.
+Authoring the field's blank discharges the obligation; clearing the key does
+not.
 
-`QuillFieldSchema` has no `required` axis. A `!must_fill` marker left in the
-document emits the non-fatal `validation::must_fill` warning.
+Neither axis gates render. Partial documents are accepted, and
+`engine.render(quill, doc)` throws only for malformed input.
 
 ### Errors
 
@@ -562,16 +438,12 @@ guard.
 
 `QuillmarkError` is a **structural interface, not a class**: the WASM layer
 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).
+`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. `message` is derived from `diagnostics`
-(`diagnostics[0].message` for single-diagnostic errors; an aggregate
-`"<N> error(s): <first.message>"` summary for compilation failures).
-
-Read `err.diagnostics[0]` for the primary diagnostic; iterate the array for
-compilation failures. The same shape applies to every throw site:
+backend compilation errors, and `message` is derived from it. 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).
@@ -582,6 +454,9 @@ compilation failures. The same shape applies to every throw site:
   text.
 - `engine.render` / `session.render`: backend compilation failures and
   validation errors.
+- `engine.render(quill, parsed)` against a quill whose *name* differs
+  (`quill::name_mismatch`) or whose *version* falls outside the document's
+  selector (`quill::version_mismatch`): a throw, never a warning.
 - Any method taking a `Quill` or `Document`: a handle from a *second* copy of
   `@quillmark/wasm` is refused with `runtime::foreign_handle`, hinting `npm ls
   @quillmark/wasm`. Two copies are two WASM memories and two `Quill`/`Document`
@@ -604,11 +479,11 @@ call returns: `try { return engine.render(quill, doc); } finally
 { doc.free(); }`: is safe even on the first render, while the backend
 binary is still loading.
 
-The package floor is Node 22+ (`engines: { node: ">=22" }`) and current
+The package floor is Node 24+ (`engines: { node: ">=24" }`) and current
 evergreen browsers; `--weak-refs` itself only needs Node 14.6+. The `using`
-sugar ([explicit resource management][erm]) needs Node 24 and is optional.
-Where it hasn't landed, an explicit `try` / `finally` runs on the Node 22
-floor:
+sugar ([explicit resource management][erm]) is on that floor and optional;
+an explicit `try` / `finally` is the equivalent, and the form that also runs
+in a browser that hasn't shipped it:
 
 ```ts
 const session = await engine.open(quill, doc);
@@ -623,15 +498,6 @@ try {
 
 [erm]: https://github.com/tc39/proposal-explicit-resource-management
 
-## Notes
-
-- Parsed markdown requires a root `~~~` block (a bare three-tilde fence;
-  `~~~card-yaml` is also accepted as a non-canonical alias)
-  with a `$quill` system-metadata line. Empty input surfaces a dedicated
-  "Empty markdown input cannot be parsed" message.
-- A `$quill` mismatch during `engine.render(quill, parsed)` is a thrown error, not a warning: rendering with a quill whose *name* differs (`quill::name_mismatch`) or whose *version* falls outside the selector (`quill::version_mismatch`) is rejected.
-- Output schema APIs live on `Quill`, not the engine.
-
 ## Changelog
 
 See the [changelog](https://github.com/borb-sh/quillmark/blob/main/CHANGELOG.md)