@quillmark/wasm 0.104.0 → 0.105.0

package/CHANGELOG.md

@@ -1,5 +1,111 @@
 # 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
@@ -93,33 +199,6 @@
   fixture suite reached neither path. A fourth carries a `!must_fill` tag on two
   example-seeded cells through seed → store → load → conform. Refs #1234
 
-<!-- seed: commits since v0.103.0, confirm the entries above cover them, then delete this comment
-- Carry the thematic-break and unsupported-construct work into the guide
-- Dense-prose pass over the new comments and docs
-- Let a quill declare the constructs its plate does not typeset
-- Drain the memo's heading buffer instead of dropping it
-- Canonicalize a thematic break to `***`
-- Close the 0.104 release gaps: the migration guide, and four changelog entries
-- Retire the enum: modifier; project a field's domain by capability
-- Pin the render floor's two type-domain edges and the seeded fill tag
-- Raise the Node floor to 24
-- dense-prose pass over the added prose
-- docs: dense-prose pass on the text-type sections
-- docs: give the text-type choice a decision procedure
-- docs: state the backend seam's scope and reserve its namespaces
-- docs: drop the private intra-doc link from pathFor
-- fix(core): state the unspellable-tail conditions instead of linking a private fn
-- chore(wasm): density pass, and gate a core-build dead function
-- docs: dense-prose pass over the geometry-address translation
-- docs: dense-prose pass over the pathFor / cardPath prose
-- test(wasm): execute the static-export exemption instead of listing it
-- feat(wasm): mint a DocPath from an Addr (#1225)
-- fix(core)!: parse geometry addresses segment-wise (#1223)
-- docs: carry the 0.103 CLI break, and the init gate into the quickstart (#1222)
-- SCHEMAS.md: a declared type change rewrites stored values (#1221)
--->
-
-
 ## v0.103.0 - 2026-08-09
 
 - docs: `docs/integration/operations.md`, carrying what the other integration

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`
@@ -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)