@quillmark/wasm 0.107.0 → 0.108.1

package/CHANGELOG.md

@@ -1,5 +1,109 @@
 # Changelog
 
+## v0.108.1 - 2026-08-19
+
+- fix: **a content cell under `variants:` is readable at its codec.**
+  `schema_at`, the walk behind `reader.get_content_at`, stepped `items` and
+  `properties` where conform steps `variants` as well, so a key into a variant
+  container fell to the catch-all and answered `edit::field_not_content` naming
+  `enum` — for a cell the same config declares `plaintext`. Such a cell stored,
+  conformed, seeded, validated and rendered, and nothing could read it back, so
+  no consumer could mount a content editor over it. The walk unions the worlds,
+  so a cell of a world that is not live reads absent rather than raising, as a
+  stale row index does; a name no world declares is `edit::unknown_field`, and a
+  variantless enum stays a scalar. The write is unchanged — a variant container
+  has no per-cell op address and needs none, committing whole.
+
+<!-- seed: commits since v0.108.0, confirm the entries above cover them, then delete this comment
+- fix: a content cell under `variants:` reads at its codec
+-->
+
+
+## v0.108.0 - 2026-08-18
+
+- fix: **the value ladder is cut per cell, so the plate is total at every
+  depth.** An absent container returned a value instead of descending, and
+  everything below it was decided by that one branch: an absent `contact` never
+  reached `contact.email`'s own `default:`, and a container `default: {name: A}`
+  crossed whole, so a declared property it omitted was **missing from the
+  plate** — a direct Typst read of it a compile error, on an address
+  `form-field` still binds. Two spellings of the same state disagreed:
+  authoring `contact: {}` rendered the leaf defaults that leaving `contact` out
+  did not, and `default: {}` — documented as expanding to the blank-filled
+  shape — emitted `{}` with no declared key at all. Resolution is now a descent:
+  a rung supplies a *seed*, and the same composition runs over it whichever rung
+  it came from, so absence is inherited rather than terminal and each cell cuts
+  its own ladder. A partial element inside an `array` `default:` is completed
+  against `items` as an authored element is. The variant container already
+  worked this way and stops being the special case.
+- **breaking** a `default:`/`example:` on an `object` with `properties` is a
+  load error (`quill::default_on_namespace`, `quill::example_on_namespace`),
+  naming the properties that hold it. A quill declaring one loaded before, so
+  the upgrade reads as a quill that stopped loading rather than as a fix; no
+  in-tree quill declares one. A typed dictionary is a namespace, not a cell:
+  the container literal was a second declaration of a value the property
+  already holds, and the two axes read different ones — `default: {name: A}`
+  rendered `A` while `must_fill` derives per property and still reported `name`
+  unauthored. It was also unchecked, so `default: {nope: 1}` loaded and crossed
+  an undeclared key to the plate. This is the variant container's rule
+  (`quill::default_type_mismatch`) generalized; an `array` keeps its literal,
+  since `items:` fixes the element type but never the arity.
+- **breaking** `must_fill:` is retired: obligation is a reading of `default:`,
+  never a declaration of its own. Declaring the key is a load error
+  (`quill::field_parse_error`) naming the migration that field's shape takes,
+  `FieldSchema::must_fill()` is `default.is_none()`, and the raw
+  `FieldSchema.must_fill` field is gone. Four of the five legacy declarations
+  restate the derivation and migrate by **deletion**: `must_fill:` on a typed
+  dictionary (a namespace carries no obligation — its leaves do), `must_fill:
+  true` with no `default:`, and `must_fill: false` beside one. `must_fill:
+  false` with no `default:` becomes `default: <the type's blank>` (`""`, `[]`,
+  `0`, `false`) — already the corpus's most common `default:`. The fifth,
+  `must_fill: true` beside a `default:`, is the one behavior deleted and the
+  one judgment call: keep the `default:` to render the value unasked, or move
+  it to `example:` to keep the ask. An example fills the blueprint cell the
+  default vacated, seeds *carrying* the `!must_fill` marker where a
+  `default:`-only field seeds nothing, and never renders — so an untouched
+  document renders the blank rather than asserting a value nobody chose. For a
+  `string` or `enum` the blueprint bytes are identical either way; three shapes
+  are not. A `richtext` example never inlines, so its cell becomes a bare
+  marker and the value survives only as the `# e.g.` hint. An
+  `integer`/`number`/`boolean` blank is indistinguishable at the plate from an
+  authored zero. On a variant container the two targets select different
+  worlds: `default: CUI` renders the CUI world and obliges its cells, while
+  `example: CUI` leaves the discriminant blank. Also removed:
+  `quillmark:must_fill` from the transform schema, which is the wire *validity*
+  contract, and an unauthored must-fill cell is wire-valid by design; the
+  declaration view carries `default:` for a consumer that wants to derive.
+  No in-tree quill declared the key and the declaration view emits only what an
+  author wrote, so no emitted JSON changes for any real quill — the WASM
+  `QuillFieldSchema` TS interface loses `must_fill?: boolean`, a compile-time
+  break for editors typed against it.
+- fix: **seeding descends into a container's `example:`.** A dictionary with no
+  `example:` of its own seeded nothing, so a property's `example:` was
+  unreachable at every projection — the render floor never emits an example, and
+  the blueprint is a different document. A seed is now composed from whatever
+  its cells commit, sparse at every depth, and stays absent when none of them
+  commit anything. Markers ride the cell they belong to.
+- fix: `resolve()`'s rung is honest for a container. It has no rung of its own,
+  so it reports the strongest that contributed: `authored` when the document
+  wrote any of it, else `default` when a cell below resolved to one, else the
+  floor. An absent container over defaulted cells read `blank` while rendering
+  those defaults, which is the fact an editor ghosts from. Nothing inside a
+  container the document did not author reads `authored`. A variant container
+  counts its live world's cells the same way, so writing one of them lifts a
+  container whose discriminant fell to the schema's `default:`.
+
+- chore(deps): the Typst floor moves to 0.15.1. The workspace already resolved
+  there under the 0.15.0 caret; the pin now names the version the tree is built
+  and tested against. `pdf-writer` stays at 0.15.0, still the version
+  `typst-pdf` → `krilla` forces and the newest published.
+- docs: `0.107-to-0.108.md`, the guide for this step. It leads with the two load
+  errors, since both reject the quill rather than the document, and gives
+  `must_fill: true` beside a `default:` — the one behavior deleted — the space
+  its judgment call needs. `BLUEPRINT.md` § "Typed dictionaries" loses the `{}`
+  expansion and the container-literal renderings with the cascade that produced
+  them, and states the nesting the 0.107 collapse admits.
+
 ## v0.107.0 - 2026-08-17
 
 - fix(typst): `display(field, ..)` validates its address against the schema, the
@@ -235,37 +339,6 @@
   address-keyed template-author contract, `plaintext(..)` having been removed
   here.
 
-<!-- seed: commits since v0.106.0, confirm the entries above cover them, then delete this comment
-- fix: a container's own `default:` crosses as content, or is refused
-- fix(typst): anchor a `let` alias only where the name is read
-- fix(typst): display validates its schema address
-- fix(docs): point the variants cross-reference at this page's own anchor
-- fix(docs): link canon by URL, not by a path outside the docs tree
-- docs: dense-prose pass over the nesting collapse
-- feat: every type nests at every depth
-- docs: dense-prose pass over the two address walks
-- feat(typst)!: the span scan takes the index step, so a row cell read anchors on the cell
-- fix: a nested content leaf's `default:` reaches the plate
-- docs: dense-prose pass over the address-grammar pin
-- test: pin the schema address grammar across both backends
-- Carry the prose style in CLAUDE.md at minimum size
-- Drop two CLAUDE.md lines that steer toward defaults
-- Cut the rules that steer toward defaults
-- docs: dense-prose pass over the lowering walk
-- Cut two lines that restated defaults
-- Rewrite dense-prose as a project-agnostic skill
-- feat!: a variant carries any leaf type, prose and dates included
-- refactor(typst)!: delete the `plaintext(field)` projection
-- feat(typst)!: depth-invariant lowering, and `date` as a native `datetime`
-- docs: dense-prose pass over the alias pass
-- docs: a bound read keeps its address, and what still needs a claim
-- fix(typst): disqualify aliases on a wildcard import in either order
-- feat(typst): follow a single-assignment `let` alias to its schema address
-- feat(wasm): export VARIANT_DISCRIMINANT_KEY to the runtime surface
-- docs: the 0.105 → 0.106 migration guide, and the rules that missed it
--->
-
-
 ## v0.106.0 - 2026-08-16
 
 - feat(typst,pdfform): a schema address may step one property into a declared

package/README.md

@@ -396,8 +396,8 @@ 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.
 
-**Obligation** — whether a human must author the field, declared by
-`must_fill:` and deriving from `default:`'s absence when left unset. An obliged
+**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

package/backends/pdfform/wasm.d.ts

@@ -347,7 +347,14 @@ export interface PaintResult {
 
 
 
-/** The commitment-ladder rung that produced a `ResolvedField.value`. */
+/**
+ * The commitment-ladder rung that produced a `ResolvedField.value`.
+ *
+ * A container has no rung of its own — it is a namespace, and its value is the
+ * composition of its cells' — so it reports the strongest rung that contributed:
+ * `authored` if the document wrote any of it, else `default` if any cell below
+ * resolved to one, else `blank`.
+ */
 export type FieldSource = "authored" | "default" | "blank";
 
 /**
@@ -447,12 +454,11 @@ export interface QuillCardBody {
 
 /** Schema entry for a single field declared in a quill's `Quill.yaml`.
  *
- * Two independent axes, and no separate `required` one. `default` and
- * `example` say what the cell holds; `must_fill` says whether a human must
- * author it, deriving from `default`'s absence when left unset. An obliged
- * field carries a `!must_fill` marker in the blueprint and warns
+ * One declaration, and no `required` key. `default` and `example` say what the
+ * cell holds, and `default`'s absence is the obligation: a field nobody
+ * declared a value for carries a `!must_fill` marker in the blueprint and warns
  * `validation::must_fill` while the document leaves it unauthored. Neither
- * axis gates render: an absent field blank-fills.
+ * gates render: an absent field blank-fills.
  */
 export interface QuillFieldSchema {
     type: "string" | "number" | "integer" | "boolean" | "array" | "object" | "date" | "datetime" | "richtext" | "plaintext" | "enum";
@@ -467,9 +473,6 @@ export interface QuillFieldSchema {
      *  member. Declaring it makes the field rest as a container,
      *  `{value: <member>, …that member's fields}`, rather than a bare string. */
     variants?: Record<string, Record<string, QuillFieldSchema>>;
-    /** Whether a human must author the field. Absent, it derives from
-     *  `default`: a defaulted field is unobliged, a defaultless one obliged. */
-    must_fill?: boolean;
     ui?: QuillFieldUi;
     properties?: Record<string, QuillFieldSchema>;
     items?: QuillFieldSchema;

package/backends/pdfform/wasm.js

@@ -196,7 +196,8 @@ export class Document {
      * and [`reader.getContent`](Self::reader_get_content) with the path spelled
      * out. `path` is a `PathStep[]` from the field to the leaf — `[0]` an
      * element of an `array<richtext>`, `["motto"]` an `object`'s content
-     * property, `[1, "notes"]` a leaf under both.
+     * property, `[1, "notes"]` a leaf under both, `["controlled_by"]` a
+     * variant's cell.
      *
      * The codec is the leaf's declared type's, so the caller stops deciding
      * what an element's stored bytes mean. Total over the storage form, as the

package/backends/typst/wasm.d.ts

@@ -347,7 +347,14 @@ export interface PaintResult {
 
 
 
-/** The commitment-ladder rung that produced a `ResolvedField.value`. */
+/**
+ * The commitment-ladder rung that produced a `ResolvedField.value`.
+ *
+ * A container has no rung of its own — it is a namespace, and its value is the
+ * composition of its cells' — so it reports the strongest rung that contributed:
+ * `authored` if the document wrote any of it, else `default` if any cell below
+ * resolved to one, else `blank`.
+ */
 export type FieldSource = "authored" | "default" | "blank";
 
 /**
@@ -447,12 +454,11 @@ export interface QuillCardBody {
 
 /** Schema entry for a single field declared in a quill's `Quill.yaml`.
  *
- * Two independent axes, and no separate `required` one. `default` and
- * `example` say what the cell holds; `must_fill` says whether a human must
- * author it, deriving from `default`'s absence when left unset. An obliged
- * field carries a `!must_fill` marker in the blueprint and warns
+ * One declaration, and no `required` key. `default` and `example` say what the
+ * cell holds, and `default`'s absence is the obligation: a field nobody
+ * declared a value for carries a `!must_fill` marker in the blueprint and warns
  * `validation::must_fill` while the document leaves it unauthored. Neither
- * axis gates render: an absent field blank-fills.
+ * gates render: an absent field blank-fills.
  */
 export interface QuillFieldSchema {
     type: "string" | "number" | "integer" | "boolean" | "array" | "object" | "date" | "datetime" | "richtext" | "plaintext" | "enum";
@@ -467,9 +473,6 @@ export interface QuillFieldSchema {
      *  member. Declaring it makes the field rest as a container,
      *  `{value: <member>, …that member's fields}`, rather than a bare string. */
     variants?: Record<string, Record<string, QuillFieldSchema>>;
-    /** Whether a human must author the field. Absent, it derives from
-     *  `default`: a defaulted field is unobliged, a defaultless one obliged. */
-    must_fill?: boolean;
     ui?: QuillFieldUi;
     properties?: Record<string, QuillFieldSchema>;
     items?: QuillFieldSchema;

package/backends/typst/wasm.js

@@ -196,7 +196,8 @@ export class Document {
      * and [`reader.getContent`](Self::reader_get_content) with the path spelled
      * out. `path` is a `PathStep[]` from the field to the leaf — `[0]` an
      * element of an `array<richtext>`, `["motto"]` an `object`'s content
-     * property, `[1, "notes"]` a leaf under both.
+     * property, `[1, "notes"]` a leaf under both, `["controlled_by"]` a
+     * variant's cell.
      *
      * The codec is the leaf's declared type's, so the caller stops deciding
      * what an element's stored bytes mean. Total over the storage form, as the

package/core/wasm.d.ts

@@ -292,7 +292,14 @@ export type DocPathSeg =
 
 
 
-/** The commitment-ladder rung that produced a `ResolvedField.value`. */
+/**
+ * The commitment-ladder rung that produced a `ResolvedField.value`.
+ *
+ * A container has no rung of its own — it is a namespace, and its value is the
+ * composition of its cells' — so it reports the strongest rung that contributed:
+ * `authored` if the document wrote any of it, else `default` if any cell below
+ * resolved to one, else `blank`.
+ */
 export type FieldSource = "authored" | "default" | "blank";
 
 /**
@@ -392,12 +399,11 @@ export interface QuillCardBody {
 
 /** Schema entry for a single field declared in a quill's `Quill.yaml`.
  *
- * Two independent axes, and no separate `required` one. `default` and
- * `example` say what the cell holds; `must_fill` says whether a human must
- * author it, deriving from `default`'s absence when left unset. An obliged
- * field carries a `!must_fill` marker in the blueprint and warns
+ * One declaration, and no `required` key. `default` and `example` say what the
+ * cell holds, and `default`'s absence is the obligation: a field nobody
+ * declared a value for carries a `!must_fill` marker in the blueprint and warns
  * `validation::must_fill` while the document leaves it unauthored. Neither
- * axis gates render: an absent field blank-fills.
+ * gates render: an absent field blank-fills.
  */
 export interface QuillFieldSchema {
     type: "string" | "number" | "integer" | "boolean" | "array" | "object" | "date" | "datetime" | "richtext" | "plaintext" | "enum";
@@ -412,9 +418,6 @@ export interface QuillFieldSchema {
      *  member. Declaring it makes the field rest as a container,
      *  `{value: <member>, …that member's fields}`, rather than a bare string. */
     variants?: Record<string, Record<string, QuillFieldSchema>>;
-    /** Whether a human must author the field. Absent, it derives from
-     *  `default`: a defaulted field is unobliged, a defaultless one obliged. */
-    must_fill?: boolean;
     ui?: QuillFieldUi;
     properties?: Record<string, QuillFieldSchema>;
     items?: QuillFieldSchema;

package/core/wasm.js

@@ -196,7 +196,8 @@ export class Document {
      * and [`reader.getContent`](Self::reader_get_content) with the path spelled
      * out. `path` is a `PathStep[]` from the field to the leaf — `[0]` an
      * element of an `array<richtext>`, `["motto"]` an `object`'s content
-     * property, `[1, "notes"]` a leaf under both.
+     * property, `[1, "notes"]` a leaf under both, `["controlled_by"]` a
+     * variant's cell.
      *
      * The codec is the leaf's declared type's, so the caller stops deciding
      * what an element's stored bytes mean. Total over the storage form, as the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quillmark/wasm",
-  "version": "0.107.0",
+  "version": "0.108.1",
   "description": "WebAssembly bindings for Quillmark, a schema-driven document engine",
   "type": "module",
   "license": "Apache-2.0",

package/runtime/runtime.d.ts

@@ -771,10 +771,10 @@ export declare class DocumentReader {
 	/**
 	 * Read the `Content` nested inside the composite field at `addr`, at `path`:
 	 * `[0]` an element of an `array<richtext>`, `["motto"]` an object's content
-	 * property, `[1, "notes"]` a leaf under both. The codec is the leaf's declared
-	 * type's, resolved through the field schema's `items` / `properties`, so the
-	 * element's storage form is not the caller's business. The empty path is
-	 * {@link getContent}.
+	 * property, `[1, "notes"]` a leaf under both, `["controlled_by"]` a variant's
+	 * cell. The codec is the leaf's declared type's, resolved through the field
+	 * schema's `items` / `properties` / `variants`, so the element's storage
+	 * form is not the caller's business. The empty path is {@link getContent}.
 	 *
 	 * `undefined` for an absent field and for a path that names nothing in the
 	 * stored value: a repeater's row index goes stale between derive and read,

package/runtime/runtime.js

@@ -1205,7 +1205,8 @@ export class DocumentReader {
 	/**
 	 * Read the `Content` nested inside the composite field at `addr`, at `path`:
 	 * `[0]` an `array<richtext>` element, `["motto"]` an object's content property,
-	 * `[1, "notes"]` a leaf under both. The codec is the leaf's declared type's.
+	 * `[1, "notes"]` a leaf under both, `["controlled_by"]` a variant's cell. The
+	 * codec is the leaf's declared type's.
 	 * `undefined` for an absent field and for a path that names nothing stored;
 	 * throws `UnknownField`, `FieldNotContent` when `path` resolves to no content
 	 * leaf, `FieldDecode` anchored at the addressed path, and `IndexOutOfRange`.