@quillmark/wasm 0.114.0 → 0.116.0

package/CHANGELOG.md

@@ -1,5 +1,382 @@
 # Changelog
 
+## v0.116.0 - 2026-09-26
+
+Upgrade path: [0.115 → 0.116](docs/migrations/0.115-to-0.116.md).
+
+### What blocks a render
+
+- feat(core)!: **a card no kind claims, and a body under `body.enabled: false`,
+  render and warn.** A render fails only where the engine would have to invent
+  what the author wrote: a value that will not read as its declared cell's
+  type, or markup the grammar cannot read. Input no declaration claims
+  displaces nothing, so it renders and warns; SCHEMAS.md § "What blocks a
+  render" sorts every validation code into incomplete, malformed and
+  unclaimed. `validation::unknown_card` and `validation::body_disabled` are
+  `Severity::Warning` from `Quill::validate`, `unknown_card` carries
+  `allowed`, and an unclaimed card keeps its place in `$cards` with its
+  fields verbatim. `ValidationError::UnknownCard` and `BodyDisabled` are
+  deleted. This is the release's silent break: a pipeline that relied on the
+  render failing catches nothing. (#1877)
+- feat(core)!: **an undeclared key warns `validation::unknown_field`**, at
+  every depth of a claimed card: a card field, a typed dictionary's property,
+  an array element's, a matrix member's column, and a cell inside a variant
+  container no world declares. `args` carry `suggestion`, the closest declared
+  field the document leaves unwritten, or `container` and `variant` for a
+  variant cell written beside its discriminant rather than under it. (#1871)
+- feat(quillmark,cli)!: **a one-shot render carries validate's warnings.**
+  `Quillmark::render`, WASM `engine.render` and Python `render` put every
+  `Quill::validate` warning on the result's `warnings` ahead of the compile's,
+  so the unclaimed input the page left out is on the result a pipeline reads.
+  A session's warnings stay its current compile's. (#1931)
+- feat(core)!: **a card-yaml block with no `$kind` fails the parse** as
+  `parse::missing_kind`, located at its opener, with a hint naming both fixes:
+  a `$kind:` line, or a backtick fence. Such a block was a card missing its
+  kind line or tilde-fenced code, and reading it as either was a guess. Every
+  card now carries `$kind`: `ResolvedCard.kind` is `String` (`string` in
+  TypeScript), and a stored card with no `$kind` folds into the body above it
+  on load, its payload as a code block, then its body. (#1905)
+- feat(core)!: **a card-yaml payload that is not a mapping fails at its
+  fence** as `parse::payload_not_mapping`, located at the opener, with `actual`
+  and `info` args and a hint naming the backtick fence, where it was an
+  unlocated `parse::invalid_structure` on a card and `parse::missing_quill` on
+  the root. (#1873)
+
+### `!must_fill` is removed
+
+- refactor(core)!: **`!must_fill` and `validation::must_fill` are gone.** The
+  marker said a cell held a placeholder rather than an answer, and the schema
+  half of the warning read `default:`'s absence as an obligation. `default:`
+  is the value an unanswered cell renders, `?` moves the render floor, and
+  null ≡ absent holds on every surface. A value under the marker keeps its
+  value: in markdown the tag drops as any unknown tag does, warned
+  `parse::unsupported_yaml_tag` at the tagged node's rooted path (which that
+  code now carries), and a stored row of any earlier tag is read past its
+  `fill` keys. Deleted: `store_fill`,
+  `is_fill`, the `QuillValue` fill set, `FieldSchema::{must_fill,
+  example_content}`, `edit::fill_on_mapping`,
+  `parse::fill_marker_unsupported_position`, WASM `storeFill` / `isFill`, and
+  the card wire's `fill` / `nestedFills`. (#1906, #1933)
+- refactor(core)!: **the storage tag is `quillmark/document@0.116.0`.** A
+  field item carries no `fill` or `nested_fills`, and a row carrying either,
+  or any key its type does not name at the document, card, payload or item
+  level, fails the load, as does a nested comment spanning lines, which
+  `to_markdown` would have written as bare YAML. Every earlier tag still
+  reads. A row's bytes move on its next save, so content hashes
+  recompute and a 0.115 build refuses the row from then on.
+- feat(core,wasm,python)!: **a card-wire payload item refuses an unknown
+  key.** A 0.115 integration still sending `{value, fill: true}` committed the
+  placeholder as an answer, and an item typo vanished; `insertCard` throws and
+  `insert_card` raises `ValueError` instead. (#1933)
+- feat(core): **a `?` on a cell's type renders it `none` when unanswered**,
+  so a plate can tell "0 votes against" from "nobody entered a tally". `?` and
+  `default:` are exclusive (`quill::optional_default`), a namespace takes no
+  `?` (`quill::optional_namespace`), and the transform schema projects
+  `type: [t, "null"]`. (#1880)
+
+### The blueprint and the seed
+
+- feat(core)!: **seeding commits no `example:`.** An example documents a
+  cell's shape rather than answering it, and `body.example` is guide text
+  quills write as instructions. `seed_document`, `seed_main` and `seed_card`
+  commit the `$seed` overlay alone; every other body is empty and every other
+  field absent. (#1923)
+- feat(core,wasm,python)!: **the blueprint answers nothing on the author's
+  behalf.** A defaultless cell is empty (`title: # string`) with its
+  `example:` on a `# e.g.` line above it; every body is empty, a
+  `body.example` riding a `# body e.g.` line that closes the payload and a
+  kind under `body.enabled: false` closing with `# no body`; a card's
+  description rides its `$kind` line; a `default: []` table is led by the
+  whole field commented out holding its row; and a matrix names its columns
+  in an `# e.g.` line, a column with no example showing its
+  `<type>[<format>]`. (#1874, #1942)
+- feat(core,wasm,python)!: **`FORMAT_RULES` is `MARKDOWN_RULES`**, headed
+  `Quillmark Markdown rules:` (`markdownRules` / `markdown_rules`), and keeps
+  only what departs from plain Markdown and YAML. `blueprint_instruction` is
+  deleted in every binding: a prompt is the consumer's to write. (#1942)
+- feat(core)!: **`to_markdown` writes a multi-line string as a `|` literal
+  block** (`|-` without a trailing newline), at every depth, where it wrote
+  one double-quoted line. A string a block would not hold verbatim stays
+  quoted. The value round-trips unchanged; the markdown bytes move. (#1883)
+
+### The quill authoring contract
+
+- feat(core)!: **a field's and a card kind's label is a top-level `title`**,
+  beside `description`, which `schema()` emits and the blueprint prints as
+  `# <title> — <description>`. `ui.title` fails the load, a `{field}` token
+  in a `title` is `quill::title_template`, and a `title` on an array's `items`
+  is `quill::title_on_items`. (#1922)
+- refactor(core,wasm)!: **`body.unsupported` is removed**, with
+  `plate::unsupported_construct`, `Quill::unsupported_constructs` and the WASM
+  `QuillBlockConstruct`. Nothing verified a declaration against the plate and
+  no editor read it; a `Quill.yaml` still declaring it fails
+  `quill::invalid_body`.
+- fix(core)!: **an unquoted `quill.version` reads as written**: `version:
+  1.10` is `1.10`, where it loaded as `1.1`, and `1.1e1` fails
+  `quill::invalid_version`.
+- feat(core)!: **a `plaintext(inline)` value ending in a newline names `|-`
+  as the fix.** `validation::not_inline`, `edit::field_not_inline` and
+  `conform::field_not_inline` carry `trailingNewline: true`, and
+  `ValidationError::NotInline` / `EditError::FieldNotInline` gain
+  `trailing_newline`. (#1918)
+- fix(core): `quill::invalid_name` suggests a name the loader accepts.
+
+### The render date
+
+- feat(core)!: **the host supplies the render date; a `date` field may hold
+  `today`.** The engine reads no clock. `Quillmark::open` / `render`,
+  `Quill::compile_data` / `compile_checked` / `resolve`,
+  `QuillConfig::compile_data` / `compile_checked`, `TypedReader::resolve` and
+  `Backend::open` take a required `today: CalendarDate`; a plate's
+  `datetime.today()` returns it whatever its `offset:`. The CLI (`--today`)
+  and the WASM and Python bindings default to the local date. A `date` value
+  is `YYYY-MM-DD` or `today`, and the blueprint annotates `date<YYYY-MM-DD |
+  today>`. `CalendarDate`'s parse fails with `ParseDateError`, which tells a
+  day the calendar lacks from a string that is no date. (#1900, #1930)
+- feat(fixtures)!: `usaf_memo`'s blank `date` renders a fill-in field where it
+  rendered today's date.
+
+### Plates and the Typst backend
+
+- feat(typst)!: **a dictionary carries the `$ink` twin its fields print
+  through.** A scalar printed off `data` kept its click target only as a
+  direct read in the plate. `data`, each card, and each typed dictionary or
+  table row carry `$ink` and `$path` wherever a field has ink: compute with the
+  dictionary, print its ink (`ink(row).org`). A date's ink prints its default
+  display, and `display(row, "due", "[year]")` formats one by dictionary and
+  key. The keys are visible to `keys()`, `pairs()`, `len()`, `==` and a
+  spread. (#1868)
+- feat(typst)!: **a plate imports the quill's `.typ` files by Typst's path
+  rules.** The plate loads at its `plate_file` path and every `.typ` file
+  outside `packages/` beside it, so a bare path resolves from the importing
+  file and a `/`-rooted one from the quill root. Plate diagnostics name the
+  declared `plate_file`, where they named `main.typ`, and a vendored package's
+  file under its spec (`@local/p:0.1.0/lib.typ`), apart from a quill module
+  of the same path. (#1869)
+- feat(typst): **a `typst:` key the backend does not read warns
+  `typst::unknown_key`**, `typst.packages` included; a package is vendored
+  under `packages/`, never fetched. A package manifest without `version` or
+  `entrypoint` is skipped at load.
+- refactor(typst): the `when` / `value-or` plate helpers are dropped; a plate
+  reads an optional cell with `!= none`.
+- fix(typst): a negative scalar's ink lexes, and region queries stay linear.
+
+### Rendering, the CLI and the bindings
+
+- feat(core)!: **one raster ceiling, 16384 px a side**, `MAX_RASTER_SIDE`,
+  owned by core, where core refused past 16384² px of area and the WASM
+  painter clamped by side on its own. A PNG export long on one axis that fit
+  by area now fails `backend::invalid_raster_scale`.
+- feat(wasm)!: **`paint(ctx, page, scale)` takes one scale and returns
+  nothing**; `PaintOptions` and `PaintResult` are deleted, and a missing or
+  non-finite scale throws `backend::invalid_raster_scale`.
+- feat(cli): **`quillmark workspace` exports a plate for Typst's own
+  tooling**: the generated helper for one document, every vendored package
+  and the backend's fonts, with the `typst watch` command over them. A rerun
+  replaces the `packages/` and `fonts/` an earlier export wrote. The facade
+  re-exports it as `quillmark::typst_workspace`. (#1869)
+- feat(cli): **`quillmark check` prints a document's every diagnostic**, and
+  `--strict` exits `1` on a warning, for a CI gate over a repository of
+  documents; `render` prints the warnings for what the page leaves out.
+  (#1872)
+- fix(cli)!: `render` takes its format from an `-o` extension naming one, and
+  a `-f` the extension contradicts exits `1` before writing.
+- feat(core,wasm,python): `Quill.emptyDocument()` / `Quill.empty_document()`
+  reach the bindings, and WASM `isInline` / `isPlain` export the content
+  predicates. (#1919)
+
+### Fixes
+
+- fix(core): the YAML prescan keeps comments, tags and anchors with the value
+  they sit on across continuation lines, dash lines, block scalars, multi-line
+  flow collections, a value below its key, nested keys with an inner `:` or a
+  leading `-`/`?`, and a removed item's trailing comment; a `$seed` overlay edit keeps the comment on
+  its `$seed` line.
+- fix(core): `to_markdown` projects a content object at every depth of a
+  field's value, and a container under a sequence item's first key
+  round-trips.
+- fix(core): a folded island past `isl-{u64::MAX}` mints a fresh id, and a
+  folded card's `$ext` stays out of the body.
+- fix(core): the unknown-key walk stays linear in a mapping's keys.
+- fix(core): a `$seed.<kind>.$body` for a kind under `body.enabled: false`
+  warns `validation::seed_unknown_field`, where the seed dropped it silently.
+- fix(cli): `validate -v` reports a backend load warning once, where each of
+  the three canonical renders repeated it.
+- fix(quillmark): the facade re-exports `ParseDateError`.
+
+
+## v0.115.0 - 2026-09-22
+
+Upgrade path: [0.114 → 0.115](docs/migrations/0.114-to-0.115.md).
+
+### The quill authoring contract
+
+- feat(core)!: **a `matrix` member mapping takes the ordinary ladder.** Two
+  rules decided what a stored member spelling meant — a bare scalar is the tick,
+  and a mapping naming no `held` is held — and the second retires. A member is
+  an `object` of a synthesized `held: {type: boolean, default: false}` beside
+  its columns, so a mapping is the member object already and the tick it names
+  no key for resolves as every other absent cell does, to its `default:`. The
+  old rule overrode that ladder for one key in one type, and bought a spelling
+  convenience for it: two mappings one key apart meant opposite ticks, the
+  shorter one ticked, and any producer building the member object without
+  conforming — an editor writing a column before the tick, a serde-built
+  payload, `{}` — set a tick it never wrote. `{ detail: X }` is now unheld with
+  its detail retained, which is what `{ held: false, detail: X }` already meant;
+  the bare scalar and every mapping naming `held` are unchanged. What remains is
+  exactly `conform_variant`'s bare-scalar rule, so `SCHEMAS.md` §Matrix lists
+  three things as the type's own rather than four. The flip is silent — the
+  value is well-typed under both readings, and a defaultless column's
+  `validation::must_fill` leaves with the tick it was gated on — so the upgrade
+  guide leads with it. (#1860)
+- feat(core): **a typed dictionary's property opens a variant world.**
+  `variants:` was card-level, so a conditional block had to sit at the top of a
+  card even where the fields it governs belong to a dictionary. The rule was
+  never about depth: what stays one level deep is the gap between a field's
+  *declared* shape and its *live* one, and a dictionary's own shape is the
+  schema's — so a world opened there deepens the address and leaves the gap
+  alone. `header.classification` reads, binds, branches and strands exactly as
+  `classification` does, one step down. Every other position would deepen the
+  gap and still refuses one: an array element, whose liveness would vary per
+  index against a form bound once; a matrix column, inside a grid the page
+  prints in full; and another variant's cell, which would make the plate's one
+  branch a tree. `quill::variant_placement` now names the position carrying the
+  ban rather than restating the old rule, and the ban is **sticky** — an object
+  inside any of them inherits it instead of laundering a world into a position
+  that cannot hold one. The surfaces that dispatch on the container before
+  walking the type needed nothing (coercion, validation, the render floor,
+  conditional `must_fill`, the transform schema, `acroform` binding); the three
+  that scanned card fields now descend, so `validation::out_of_variant` finds a
+  strand at `main.header.classification.controlled_by`, the blueprint seats a
+  world's cells — live or commented — at the dictionary's indent, and the seed
+  resolves a nested discriminant before walking its field set.
+- feat(core)!: **`ui.layout: table` contracts its columns.** The key was checked
+  for its outer shape alone — `type: array` whose `items` is an `object` — so a
+  row holding a container loaded clean and no editor could draw it: the author
+  wrote a key, the loader took it, and a surface ignored it with no signal at
+  either end. A column that is not a leaf is now
+  `quill::table_column_not_flat`, naming the column (`appendices[].entries`)
+  rather than the field. This splits the key along a seam it always had: a
+  **contract** that every column is a leaf, settled at load, and a **request**
+  to draw a grid, which an editor still declines for a width or a cell renderer
+  it does not have. Shape leaves the decline list, since shape was never a
+  consumer's judgement to make. The boundary is containment, not height — prose
+  is a column whatever its `inline`, because how tall a cell renders is the
+  editor's call and what it contains is not. `FieldType::is_leaf` is the one
+  definition, an exhaustive match a new type cannot skip, and `acroform`'s
+  `is_scalar_or_prose` is gone in favor of it: the same question had two
+  answers in two crates. Part of #1859.
+- feat(core,wasm,python): **the empty document has a constructor.**
+  `Quill::empty_document()` is `Document::new` under the quill's own reference,
+  so the three canonical documents are three constructors beside
+  `QuillConfig::blueprint()` and `Quill::seed_document()`, and no caller spells
+  `name@version` to reach the one a plate is bound to render. `quiver_test.rs`
+  reads it rather than formatting the two-line markdown itself. The bindings
+  carry it as `Quill.emptyDocument()` / `Quill.empty_document()`.
+- feat(cli)!: **`quillmark validate` compiles the plate.** It renders the empty
+  document, the blueprint and the seed through the quill's backend at the
+  backend's first declared format, and reports each failure as a
+  `cli::canonical_document_failed` error naming which of the three it is,
+  followed by the backend's own diagnostics. The contract that a plate renders
+  the empty document was checked for the fixtures quiver alone, and `render`
+  with no input file renders the seed, the fullest of the three: a plate that
+  reads a blank badly passed both. A quill whose plate does not compile now
+  exits `1` where it exited `0`, and a backend that does not resolve is
+  `cli::backend_unresolved` followed by the engine's own diagnostic. A render's
+  warnings join the `-v` list, and `validate --no-render` is the configuration
+  read on its own. Closes #1844.
+
+### The content model
+
+- refactor(content)!: **an island stores its value, not its provenance.** `Loss`
+  had one minting rule — a table cell dropping an inline image's url — and no
+  reader: export dispatches on an island's `type`, the Typst emitter and the
+  acroform binder never looked, and an `islandOps` `set` stored whatever class
+  the op named. Two cells written `| a cat |` and `| ![a cat](cat.png) |` mint
+  equal `props` and differ only in the markdown behind them, which the
+  projection has no syntax to carry back out, so the class survived neither a
+  `to_markdown` → `from_markdown` hop nor re-derivation from the row holding it
+  — which is why the content fixed point had to be stated modulo it. An
+  island's canonical form is `{id, type, props}`, the fixed point is exact, and
+  the closed vocabularies cover the four discriminators a projection dispatches
+  on. `Loss`, `Island::loss`, `Island::with_loss`, `IslandType::default_loss`,
+  `ContentIsland.loss` and `ContentLossClass` are deleted; a stored row spelling
+  `loss` opens with the key ignored and absent from what comes back, and a
+  `loss` on an authored island or an `islandOps` entry is ignored rather than
+  refused. A host that surfaced the class surfaces the drop at the import
+  instead, where the markdown it is about is still in hand. Closes #1757.
+- refactor(content,core,wasm,python)!: **a block island's line is a `para`, and
+  `LineKind::Island` is gone.** The kind was a second copy of a fact the island
+  beside it already carried: markdown writes a `table` as a block and an `image`
+  inline, so `IslandType::block_only` settled which line a lone slot sat on and
+  `normalize` wrote that answer back over whatever was stored. Every read site
+  now asks the island — export already dispatched on the type, the Typst emitter
+  already lowered `Island` as `Para`, and the one fact the kind alone still
+  answered, "this block renders one line", moves to the new public
+  `Content::block_island_at`, which `normalize` reads beside
+  `takes_continuations` when it clears a stranded `continues`. Landing a block
+  island is two channels rather than three: the delta opens the line, the island
+  op fills it, and the `setKind` goes. The TS `ContentLineKind` loses its
+  `{ kind: "island" }` arm, so a host branching on it typechecks red; a `setKind`
+  still naming `island` lands as the `para` it would have settled to.
+- refactor(core)!: **the storage tag is `quillmark/document@0.115.0`.** The two
+  lines above move canonical bytes — the `loss` key for every document holding
+  an island, the line kind for every document holding a table — so content
+  hashes recompute once on those rows. `DocumentV0_112_0` freezes with a raw
+  `body` and the new `DocumentV0_115_0` carries the `CanonicalContent`; the hop
+  between them is that body's decode, and `V0_93_0 → V0_112_0` becomes a retag
+  now that both trees spell `body` raw. Stored rows need no migration: the
+  content decoder reads `island` as `para` wherever it meets it, permanently,
+  since the same spelling rests untagged inside every `richtext` field and
+  `$seed` overlay, where no hop reaches it. Closes #1647.
+
+### Schema, validation and the resolved view
+
+- refactor(core)!: **a schema is loaded, not deserialized.** `QuillConfig`,
+  `CardSchema` and `FieldSchema` serialize and no longer implement
+  `Deserialize`, and `FieldSchema::from_quill_value` is crate-internal. A field
+  arrives in two steps — the parse, which folds the sibling keys (`inline:`,
+  `values:`, `members:`, `max:`) into the type payload, and the shape walk,
+  which rejects an `object` without `properties`, an `array` without `items`,
+  an empty `properties` map, and the placements — and only `parse_fields` ran
+  both, so a config assembled through serde carried states no `Quill.yaml` can
+  reach, absorbed downstream without a diagnostic. Gating the serde path
+  instead would have duplicated the walk and collapsed its diagnostic codes
+  into `quill::field_parse_error` at that boundary. The way to a config is
+  `QuillConfig::from_yaml_with_warnings`, or a `Quill` read off a file tree;
+  serialization is untouched, so `schema()`, `schema_yaml()` and every emission
+  read the same loaded form they did. Closes #1836.
+- refactor(core,wasm)!: **a matrix roster is one flat mapping; group headings
+  are gone.** A block's `group:` was declared in the schema and absent from the
+  value, the address and the vocabulary — the blueprint emits
+  `matrix<a | b | c>` off one flat key space, so the partition reached the
+  visual editor and nowhere else, buying one shared `properties` map for a
+  schema concept, its load rules and a reserved key. `members:` is now
+  `{id: Title}` directly, `MatrixGroup`, `MATRIX_GROUP_KEY` and the TypeScript
+  `QuillMatrixGroup` are deleted, and `FieldType::Matrix` carries an
+  `IndexMap<String, String>` read through the new `FieldType::matrix_roster`,
+  which replaces `matrix_members`. The projection stops writing `group` onto
+  every member, which returns `group` to the column names a quill may declare,
+  and `quill::duplicate_matrix_member` retires: the roster is a mapping, so it
+  has one slot per id exactly as the stored value does and a duplicate is
+  unspellable on both sides. Closes #1851.
+
+### The blueprint
+
+- feat(core)!: **a dormant variant world is its own cells, commented out.** A
+  variant-bearing enum's blueprint named every world it could not show, one
+  `# when CUI: controlled_by, poc, category` line each — the one place on the
+  surface where a cell was named rather than shown, dropping the position,
+  obligation, type, description and example a cell carries. Every world now sits
+  under a `# when <MEMBER>:` header in declaration order: the selected world's
+  cells live, every other world's the same cells with a `# ` in front, at the
+  slot they would occupy live. A reader activates a world by setting the
+  discriminant and deleting `# `. One builder and one emitter serve both, so a
+  dormant line is byte-for-byte the live line, and the block round-trips through
+  `Document::parse` as the comments it is, reaching neither the validator nor
+  the render floor. Closes #1846.
+
+
 ## v0.114.0 - 2026-09-18
 
 ### Schema, validation and the resolved view

package/README.md

@@ -150,8 +150,7 @@ document was built. Parse warnings and the `conform::*` warnings both ride
 other way (`fromStored`, 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
+is safe. 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.
 
@@ -175,9 +174,9 @@ const doc = Document.storageVersionOf(content)
   : Document.fromMarkdown(content);
 ```
 
-The `schema` value (`quillmark/document@0.112.0`) is the **model version**,
+The `schema` value (`quillmark/document@0.116.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.112.x` patch release reads
+the `Document` model itself changes, so every `0.116.x` patch release reads
 and writes that same value.
 
 - **Upgrading is safe.** A newer build reads documents an older build's
@@ -187,8 +186,10 @@ and writes that same value.
   canonical on-disk format keeps loading across crate upgrades: there is no
   need to pin old wasm to read old data. The exception is a row a host
   authored a content construct of its own into — a line `kind`, container,
-  mark `type`, island `type` or `loss` outside the vocabulary. Those are
-  refused from 0.113 on; see that release's migration guide.
+  mark `type` or island `type` outside the vocabulary. Those are refused from
+  0.113 on; see that release's migration guide. An island `loss` is not one of
+  them: 0.115 drops the key, so a row spelling one opens whatever the class and
+  comes back without it.
 - **Downgrading is not.** `fromStored` rejects an *unknown* (i.e. newer)
   `schema` version rather than guessing at a format it predates. Don't feed
   documents written by a newer build back into an older one.
@@ -218,8 +219,9 @@ To render a form editor, read field definitions from `quill.schema` (walk
 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 with each field's `example:`
-committed; `quill.seedMain()` and `quill.seedCard(kind)` seed one card. All
+`quill.seedDocument()` returns a starter document: one card per kind, each body
+empty, every field absent (no `example:` is 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:
 
@@ -246,7 +248,7 @@ card is an object literal: one `{ type: "field", key, value }` per field in
 `{ card?, field? }`, absent `card` = main, absent `field` = body, and a bare
 string is shorthand for `{ field }`. So `doc.storeField("qty", 3)` targets the
 main card's `qty`, `doc.storeField({ card: 2, field: "qty" }, 3)` a composable
-card's. Reads are total over the field axis (`getStored` → `undefined`, `isFill` → `false` for
+card's. Reads are total over the field axis (`getStored` → `undefined` for
 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`; `bodyMarkdown` is the body markdown read (a `CardAddr`; a field's
@@ -287,7 +289,7 @@ on `Document` itself (**store** = verbatim, **set** = typed):
   `_reviseField` ABI the writer delegates to, hidden from the `.d.ts`.)
 
 - **`store*`: the deliberate quill-free primitive.** `doc.storeField(addr, value)`
-  / `doc.storeFields(cardAddr, {...})` (and `storeFill`) validate only the field
+  / `doc.storeFields(cardAddr, {...})` validate only the field
   name/depth/kind and store the value verbatim, no quill required. Reach for it
   on purpose when you *want* the opaque store: quill-agnostic storage/migration
   infra that has no bundle and must write regardless of a drifted schema;
@@ -352,43 +354,47 @@ tells you which pages to repaint (`dirty ∩ visible`). `update` is transactiona
 on throw, every read keeps serving the last-good compile. Don't open a session
 per export, and don't re-open per edit: `update` instead.
 
+Both take the render date as an optional last argument (`YYYY-MM-DD`, default
+the local date): what a `today` date field and a plate's `datetime.today()`
+render as. A session keeps the date it opened with, so a preview left open past
+midnight renders yesterday's until it is reopened.
+
 A document that compiles to zero pages still produces a valid session
-(`pageCount === 0`); `paint(ctx, 0)` and `pageSize(0)` then throw. Branch on
+(`pageCount === 0`); `paint(ctx, 0, scale)` and `pageSize(0)` then throw. Branch on
 `pageCount === 0` to render a "no pages to preview" UI rather than relying on
 the throw.
 
 Their `warnings` differ in reach. `engine.render` returns one list for the
-whole pipeline: `doc.warnings` (parse, `conform::*`,
-`plate::unsupported_construct`) ahead of the compile's own. A session outlives
+whole pipeline: `doc.warnings` (parse and `conform::*`), then every
+`quill.validate(doc)` warning, then the compile's own. A session outlives
 the document it opened from, so `session.render` and `session.warnings` carry
-the compile half alone — read `doc.warnings` beside them.
+the compile's alone — read `doc.warnings` and `quill.validate(doc)` beside them.
 
 ### Canvas Preview
 
-`session.paint(ctx, page, opts?)` rasterizes a page directly into a
+`session.paint(ctx, page, scale)` rasterizes a page directly into a
 `CanvasRenderingContext2D` (main thread) or
 `OffscreenCanvasRenderingContext2D` (Worker), skipping PNG/SVG byte
 round-trips.
 
-The painter owns `canvas.width` / `canvas.height`: it sizes the backing
-store itself. Consumers own `canvas.style.*` (or the layout system that
-sets them) and read `layoutWidth` / `layoutHeight` from the returned
-`PaintResult`.
+`scale` is backing-store pixels per point. The painter owns `canvas.width` /
+`canvas.height`, reducing `scale` where it must so neither exceeds 16384 px;
+consumers own `canvas.style.*`. A canvas styled to fill its page box
+needs nothing back from the paint:
 
 ```ts
-const result = session.paint(canvas.getContext("2d"), 0, {
-  layoutScale: 1,                            // layout px per pt (page geometry unit)
-  densityScale: window.devicePixelRatio,     // backing-store density
-});
-
-canvas.style.width  = `${result.layoutWidth}px`;
-canvas.style.height = `${result.layoutHeight}px`;
+canvas.style.width = "100%";                 // the box sets the display size
+const cssPxPerPt = canvas.clientWidth / session.pageSize(0).widthPt;
+if (cssPxPerPt > 0) {                        // 0 while the canvas has no layout box
+  session.paint(canvas.getContext("2d")!, 0, cssPxPerPt * window.devicePixelRatio);
+}
 ```
 
-- `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`).
+- Fold `devicePixelRatio`, in-app zoom, and `visualViewport.scale` into `scale`.
+- A canvas with no layout box (`display: none` on it or an ancestor, detached,
+  in a zero-width container) has `clientWidth` 0, and a 0 scale throws
+  `backend::invalid_raster_scale`: skip the paint, and paint when a
+  `ResizeObserver` reports a width.
 - `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`.
@@ -400,33 +406,28 @@ canvas.style.height = `${result.layoutHeight}px`;
   cache them between committed `update`s only. After one, the count is
   `ChangeSet.pageCount`, and every page in `ChangeSet.dirtyPages` needs its
   `pageSize` re-read.
-- In a Worker, pass an `OffscreenCanvasRenderingContext2D`; the layout
-  dimensions are informational there. Loading the WASM module inside the Worker
-  is the host's responsibility.
+- In a Worker, pass an `OffscreenCanvasRenderingContext2D`. An
+  `OffscreenCanvas` has no layout box to measure, so the main thread posts the
+  scale. Loading the WASM module inside the Worker is the host's
+  responsibility.
 - `paint` / `pageSize` throw on a page the compile does not have, a zero-page
   compile included, naming the index and the `pageCount` that excludes it. That
   throw is the whole contract: open the session and handle it.
 
 ### Schema model
 
-A field carries two independent axes, and no `required` one.
+A field declares no `required` key: nothing is required.
 
-**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.
+**`default:`** — what an unanswered field renders. With one, `quill.blueprint`
+renders that value under a type-only `# <type>` annotation and the render path
+uses it when the document omits the field. Without one, the blueprint leaves the
+cell empty and an absent field blank-fills.
 
-**Obligation** — whether a human must author the field, read off `default:`'s
-absence: a defaulted field asks nobody, a defaultless one asks. 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.
+**`example:`** — the schema's illustration of the field's shape.
+`quill.blueprint` shows it on a `# e.g.` line above the field; it never takes a
+cell and never renders.
 
-Neither axis gates render. Partial documents are accepted, and
+An unanswered field draws no diagnostic. Partial documents are accepted, and
 `engine.render(quill, doc)` throws only for malformed input.
 
 ### Errors
@@ -514,7 +515,7 @@ in a browser that hasn't shipped it:
 const session = await engine.open(quill, doc);
 try {
   for (let p = 0; p < session.pageCount; p++) {
-    session.paint(ctx, p);
+    session.paint(canvases[p].getContext("2d")!, p, scale);
   }
 } finally {
   session.free();