@quillmark/wasm 0.115.0 → 0.116.0

package/CHANGELOG.md

@@ -1,5 +1,210 @@
 # 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).

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.115.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.115.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
@@ -220,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:
 
@@ -248,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
@@ -289,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;
@@ -354,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`.
@@ -402,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
@@ -516,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();