@quillmark/wasm 0.116.0 → 0.118.0

package/CHANGELOG.md

@@ -1,5 +1,115 @@
 # Changelog
 
+## v0.118.0 - 2026-09-30
+
+Upgrade path: [0.117 → 0.118](docs/migrations/0.117-to-0.118.md).
+
+### Kind seeds
+
+- feat(core,wasm,python)!: **a card kind declares `seed:`**, what
+  `seed_card` writes into a new card of that kind: the `$seed.<kind>` shape,
+  fields plus an optional `$body`. `seed_document()` carries each kind's seed,
+  and `schema()` emits it (WASM `QuillCardSchema.seed`). `CardSchema` gains a
+  public `seed` field. A document's `$seed.<kind>` replaces the kind's seed
+  whole, `$body` included, and `$seed.<kind>: {}` seeds nothing. A kind's
+  seed is checked as the card it makes and fails the load under
+  `quill::seed_*`, plus `quill::seed_redundant` for a seed that renders as the
+  unanswered field does; `main` declares none (`quill::invalid_card_schema`).
+  (#2016)
+
+### Document `$seed`
+
+- feat(core)!: **a document's `$seed` warns wherever the card it seeds
+  would**: an undeclared key below a seeded field
+  (`validation::unknown_field`), a cell outside its variant world
+  (`validation::out_of_variant`), a `$body` that is not a markdown string or
+  does not import (`validation::seed_overlay_shape`), and a seeded array past
+  its `max:` (`validation::cardinality`). `quillmark validate` fails a quill
+  whose `example.md` carries one. A `null` in `$seed.<kind>` commits nothing,
+  where the new card carried `field:`. (#2016)
+- refactor(cli): `quillmark validate` names `seed_document`'s output
+  `seeded` in its render report, where it said `seed`. (#2014)
+
+
+## v0.117.0 - 2026-09-29
+
+Upgrade path: [0.116 → 0.117](docs/migrations/0.116-to-0.117.md).
+
+### `example:` leaves the quill schema
+
+- feat(core,wasm,python)!: **a `Quill.yaml` declaring `example:` fails to
+  load.** A slot declares one value, its `default:`. `example:` on a field at
+  any depth fails `quill::field_parse_error`, hinted to `description:`, and
+  `body.example` fails `quill::invalid_body`. The `quill::example_*` checks
+  and `quill::body_example_*` codes are deleted, and
+  `quill::richtext_example_import` is `quill::richtext_default_import`. The
+  blueprint drops its `# e.g.` and `# body e.g.` lines but a matrix's member
+  hint, `schema()` carries no `example`, and `FieldSchema::example`,
+  `BodyCardSchema::example`, WASM `QuillFieldSchema.example` and
+  `QuillCardBody.example` are deleted. (#1999)
+
+### The example document
+
+- feat(core,cli,wasm,python)!: **`example.md` at the quill root is the
+  quill's example**, a filled-in page whose values are made up.
+  `Quill.yaml` declares nothing about it and the load never reads it.
+  `Quill::example_document()`, WASM `Quill.exampleDocument()` and Python
+  `Quill.example_document()` hand it out pinned to the quill's
+  `name@version`, or `None` without one; a `$quill` other than the quill's
+  bare name fails `quill::example_reference`. `quillmark` re-exports
+  `EXAMPLE_FILE`. `quillmark validate` reads, validates and renders it, and
+  fails the quill on any diagnostic it carries, a warning included
+  (`cli::example_not_clean`, `cli::example_render_failed`): a quill keeping a
+  root `example.md` for another purpose renames it. `status_report` and
+  `usaf_memo` ship one. (#2002, #2007, #2009)
+
+### Quill references
+
+- refactor(core)!: **`$quill: name@latest` fails as
+  `parse::invalid_quill_reference`.** It was a second spelling of the bare
+  `name`, which matches the same versions. A selector is `MAJOR`,
+  `MAJOR.MINOR` or `MAJOR.MINOR.PATCH`, digits only, the grammar
+  `@quillmark/quiver`'s `parseQuillRef` enforces. `VersionSelector::Latest`
+  is `VersionSelector::Any`, and `QuillReference::latest` is deleted.
+  (#2000)
+- refactor(core)!: `VersionSelector` has no `Display`: `Any` has no written
+  form outside a reference. `QuillReference`'s `Display` still writes `name`
+  or `name@selector`. (#2008)
+
+### Quill headers the load refuses
+
+- fix(core)!: **`version: ""`, a tagged version such as `!!float 1.10`, and
+  a card kind named `main` fail to load**, as `quill::invalid_version` and
+  `quill::invalid_card_name`. None could hold what it seemed to. (#1994)
+- fix(core)!: a `title` key on a matrix member in a document warns
+  `validation::unknown_field` at `<field>.<member>.title`: the member's title
+  is the quill's, and `quillmark check --strict` fails such a document.
+  (#1994)
+
+### Rendering
+
+- fix(typst)!: **a quill shipping no fonts renders in Roboto**, where it
+  rendered in Figtree, which has no prime: a `"` or `'` after a digit in
+  richtext rendered as an empty box. The faces are variable Roboto, upright
+  and italic, weights 100 to 900. A font-less quill's text reflows, a plate
+  naming an unshipped `"Figtree"` warns `unknown font family`, and
+  `quillmark workspace` exports `fonts/Roboto.ttf` and
+  `fonts/Roboto-Italic.ttf`. (#2010)
+
+### The CLI
+
+- fix(cli): `quillmark check` locates a diagnostic in the file it came from,
+  where every location read `input.md`; `quillmark` re-exports
+  `DOCUMENT_FILE`. (#1995)
+- fix(cli): a missing path given to `quillmark check` draws
+  `cli::unreadable_document`, as an unreadable one does, where it stopped
+  the run; the remaining paths are still checked. (#1994)
+
+### Fixes
+
+- fix(core): a field parse hint answers the key serde refused, at every
+  depth. (#1999)
+
 ## v0.116.0 - 2026-09-26
 
 Upgrade path: [0.115 → 0.116](docs/migrations/0.115-to-0.116.md).

package/README.md

@@ -219,8 +219,12 @@ 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: one card per kind, each body
-empty, every field absent (no `example:` is committed);
+`quill.exampleDocument()` returns the quill's example, a filled-in page whose
+values are made up, pinned to the quill's `name@version`; `undefined` when
+the quill has no `example.md` at its root.
+
+`quill.seedDocument()` returns a starter document: one card per kind, each
+carrying the kind's `seed` from `Quill.yaml` and no other field;
 `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:
@@ -423,10 +427,6 @@ 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.
 
-**`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.
-
 An unanswered field draws no diagnostic. Partial documents are accepted, and
 `engine.render(quill, doc)` throws only for malformed input.
 

package/core/wasm.d.ts

@@ -407,16 +407,14 @@ export interface QuillCardUi {
 export interface QuillCardBody {
     /** When false, consumers must not accept or store body content for this card kind. Defaults to true. */
     enabled?: boolean;
-    /** Example body content, shown on the blueprint's `# body e.g.` line above the body. */
-    example?: string;
 }
 
 export type QuillFieldType = "string" | "number" | "integer" | "boolean" | "array" | "object" | "date" | "datetime" | "richtext" | "plaintext" | "enum" | "matrix";
 
 /** Schema entry for a single field declared in a quill's `Quill.yaml`.
  *
- * `default` is the value an unanswered cell renders; `example` documents shape
- * and never renders. An absent field without a `default` blank-fills.
+ * `default` is the value an unanswered cell renders. An absent field without a
+ * `default` blank-fills.
  */
 export interface QuillFieldSchema {
     /** A trailing `?` marks the cell optional: unanswered, it renders `none`
@@ -428,7 +426,6 @@ export interface QuillFieldSchema {
     title?: string;
     description?: string;
     default?: unknown;
-    example?: unknown;
     /** The closed set of allowed values. Required on `type: "enum"`, and valid
      *  nowhere else. */
     values?: string[];
@@ -464,6 +461,10 @@ export interface QuillCardSchema {
     fields: Record<string, QuillFieldSchema>;
     ui?: QuillCardUi;
     body?: QuillCardBody;
+    /** What `seedCard` writes into a new card of this kind where the
+     *  document's `$seed` carries no entry for it: the `$seed[kind]` shape, fields plus
+     *  an optional `$body`. Never present on `main`. */
+    seed?: Record<string, unknown>;
 }
 
 /**
@@ -813,6 +814,15 @@ export class Quill {
      * reached by spelling the reference.
      */
     emptyDocument(): Document;
+    /**
+     * The quill's example document, `undefined` when the quill has no
+     * `example.md` at its root: a filled-in page whose values are made up to show the
+     * quill in use, never kept. It comes back pinned to this quill's
+     * `name@version` and conformed as `parse` conforms, its parse and
+     * `conform::*` warnings on `doc.warnings`. Throws when the file does not
+     * parse or its `$quill` is not this quill's bare name.
+     */
+    exampleDocument(): Document | undefined;
     /**
      * Build a quill from a file tree. Pure: the declared backend is resolved
      * later, at render time. Accepts a `Map<string, Uint8Array>` or a plain
@@ -834,20 +844,20 @@ export class Quill {
     parse(markdown: string): Document;
     /**
      * Seed a starter composable `Card` of the given kind (carries `$kind`),
-     * committing an optional per-kind seed `overlay`'s fields and `$body`
-     * (`overlay › absent`, body `overlay › empty`). `undefined` when
-     * `cardKind` is not declared in this quill's schema.
+     * committing an optional per-kind seed `overlay`'s fields and `$body` in
+     * place of the kind's own `seed`, else that seed's. `undefined` when `cardKind` is
+     * not declared in this quill's schema.
      *
      * Pass `document.seedOverlay(cardKind)` as `overlay` so a card added to a
      * template-derived document inherits its curated starting values; omit it
-     * for the bare schema seed.
+     * for a card carrying the kind's seed alone.
      */
     seedCard(card_kind: string, overlay: Record<string, unknown> | undefined): Card | undefined;
     /**
      * Seed a starter `Document` from the schema: the main card plus one instance
-     * of each composable card kind, each body empty and every field absent
-     * (interpolated at render as `default:`, else the field's blank). No
-     * `example:` is committed (a field's or `body.example`).
+     * of each composable card kind, each carrying its kind's `seed` and every
+     * other field absent (interpolated at render as `default:`, else the
+     * field's blank).
      */
     seedDocument(): Document;
     /**
@@ -1062,6 +1072,7 @@ export interface InitOutput {
     readonly quill_blueprint: (a: number, b: number) => void;
     readonly quill_conform: (a: number, b: number, c: number) => void;
     readonly quill_emptyDocument: (a: number) => number;
+    readonly quill_exampleDocument: (a: number, b: number) => void;
     readonly quill_fromTree: (a: number, b: number) => void;
     readonly quill_metadata: (a: number, b: number) => void;
     readonly quill_parse: (a: number, b: number, c: number, d: number) => void;

package/core/wasm.js

@@ -1246,6 +1246,30 @@ export class Quill {
         const ret = wasm.quill_emptyDocument(this.__wbg_ptr);
         return Document.__wrap(ret);
     }
+    /**
+     * The quill's example document, `undefined` when the quill has no
+     * `example.md` at its root: a filled-in page whose values are made up to show the
+     * quill in use, never kept. It comes back pinned to this quill's
+     * `name@version` and conformed as `parse` conforms, its parse and
+     * `conform::*` warnings on `doc.warnings`. Throws when the file does not
+     * parse or its `$quill` is not this quill's bare name.
+     * @returns {Document | undefined}
+     */
+    exampleDocument() {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.quill_exampleDocument(retptr, this.__wbg_ptr);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            if (r2) {
+                throw takeObject(r1);
+            }
+            return r0 === 0 ? undefined : Document.__wrap(r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
     /**
      * Build a quill from a file tree. Pure: the declared backend is resolved
      * later, at render time. Accepts a `Map<string, Uint8Array>` or a plain
@@ -1343,13 +1367,13 @@ export class Quill {
     }
     /**
      * Seed a starter composable `Card` of the given kind (carries `$kind`),
-     * committing an optional per-kind seed `overlay`'s fields and `$body`
-     * (`overlay › absent`, body `overlay › empty`). `undefined` when
-     * `cardKind` is not declared in this quill's schema.
+     * committing an optional per-kind seed `overlay`'s fields and `$body` in
+     * place of the kind's own `seed`, else that seed's. `undefined` when `cardKind` is
+     * not declared in this quill's schema.
      *
      * Pass `document.seedOverlay(cardKind)` as `overlay` so a card added to a
      * template-derived document inherits its curated starting values; omit it
-     * for the bare schema seed.
+     * for a card carrying the kind's seed alone.
      * @param {string} card_kind
      * @param {Record<string, unknown> | undefined} overlay
      * @returns {Card | undefined}
@@ -1373,9 +1397,9 @@ export class Quill {
     }
     /**
      * Seed a starter `Document` from the schema: the main card plus one instance
-     * of each composable card kind, each body empty and every field absent
-     * (interpolated at render as `default:`, else the field's blank). No
-     * `example:` is committed (a field's or `body.example`).
+     * of each composable card kind, each carrying its kind's `seed` and every
+     * other field absent (interpolated at render as `default:`, else the
+     * field's blank).
      * @returns {Document}
      */
     seedDocument() {

package/core/wasm_bg.wasm.d.ts

@@ -62,6 +62,7 @@ export const quill_backendId: (a: number, b: number) => void;
 export const quill_blueprint: (a: number, b: number) => void;
 export const quill_conform: (a: number, b: number, c: number) => void;
 export const quill_emptyDocument: (a: number) => number;
+export const quill_exampleDocument: (a: number, b: number) => void;
 export const quill_fromTree: (a: number, b: number) => void;
 export const quill_metadata: (a: number, b: number) => void;
 export const quill_parse: (a: number, b: number, c: number, d: number) => void;

package/package.json

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

package/render/wasm.d.ts

@@ -418,16 +418,14 @@ export interface QuillCardUi {
 export interface QuillCardBody {
     /** When false, consumers must not accept or store body content for this card kind. Defaults to true. */
     enabled?: boolean;
-    /** Example body content, shown on the blueprint's `# body e.g.` line above the body. */
-    example?: string;
 }
 
 export type QuillFieldType = "string" | "number" | "integer" | "boolean" | "array" | "object" | "date" | "datetime" | "richtext" | "plaintext" | "enum" | "matrix";
 
 /** Schema entry for a single field declared in a quill's `Quill.yaml`.
  *
- * `default` is the value an unanswered cell renders; `example` documents shape
- * and never renders. An absent field without a `default` blank-fills.
+ * `default` is the value an unanswered cell renders. An absent field without a
+ * `default` blank-fills.
  */
 export interface QuillFieldSchema {
     /** A trailing `?` marks the cell optional: unanswered, it renders `none`
@@ -439,7 +437,6 @@ export interface QuillFieldSchema {
     title?: string;
     description?: string;
     default?: unknown;
-    example?: unknown;
     /** The closed set of allowed values. Required on `type: "enum"`, and valid
      *  nowhere else. */
     values?: string[];
@@ -475,6 +472,10 @@ export interface QuillCardSchema {
     fields: Record<string, QuillFieldSchema>;
     ui?: QuillCardUi;
     body?: QuillCardBody;
+    /** What `seedCard` writes into a new card of this kind where the
+     *  document's `$seed` carries no entry for it: the `$seed[kind]` shape, fields plus
+     *  an optional `$body`. Never present on `main`. */
+    seed?: Record<string, unknown>;
 }
 
 /**
@@ -1046,6 +1047,15 @@ export class Quill {
      * reached by spelling the reference.
      */
     emptyDocument(): Document;
+    /**
+     * The quill's example document, `undefined` when the quill has no
+     * `example.md` at its root: a filled-in page whose values are made up to show the
+     * quill in use, never kept. It comes back pinned to this quill's
+     * `name@version` and conformed as `parse` conforms, its parse and
+     * `conform::*` warnings on `doc.warnings`. Throws when the file does not
+     * parse or its `$quill` is not this quill's bare name.
+     */
+    exampleDocument(): Document | undefined;
     /**
      * Build a quill from a file tree. Pure: the declared backend is resolved
      * later, at render time. Accepts a `Map<string, Uint8Array>` or a plain
@@ -1067,20 +1077,20 @@ export class Quill {
     parse(markdown: string): Document;
     /**
      * Seed a starter composable `Card` of the given kind (carries `$kind`),
-     * committing an optional per-kind seed `overlay`'s fields and `$body`
-     * (`overlay › absent`, body `overlay › empty`). `undefined` when
-     * `cardKind` is not declared in this quill's schema.
+     * committing an optional per-kind seed `overlay`'s fields and `$body` in
+     * place of the kind's own `seed`, else that seed's. `undefined` when `cardKind` is
+     * not declared in this quill's schema.
      *
      * Pass `document.seedOverlay(cardKind)` as `overlay` so a card added to a
      * template-derived document inherits its curated starting values; omit it
-     * for the bare schema seed.
+     * for a card carrying the kind's seed alone.
      */
     seedCard(card_kind: string, overlay: Record<string, unknown> | undefined): Card | undefined;
     /**
      * Seed a starter `Document` from the schema: the main card plus one instance
-     * of each composable card kind, each body empty and every field absent
-     * (interpolated at render as `default:`, else the field's blank). No
-     * `example:` is committed (a field's or `body.example`).
+     * of each composable card kind, each carrying its kind's `seed` and every
+     * other field absent (interpolated at render as `default:`, else the
+     * field's blank).
      */
     seedDocument(): Document;
     /**
@@ -1337,6 +1347,7 @@ export interface InitOutput {
     readonly quill_blueprint: (a: number, b: number) => void;
     readonly quill_conform: (a: number, b: number, c: number) => void;
     readonly quill_emptyDocument: (a: number) => number;
+    readonly quill_exampleDocument: (a: number, b: number) => void;
     readonly quill_fromTree: (a: number, b: number) => void;
     readonly quill_metadata: (a: number, b: number) => void;
     readonly quill_parse: (a: number, b: number, c: number, d: number) => void;

package/render/wasm.js

@@ -1567,6 +1567,30 @@ export class Quill {
         const ret = wasm.quill_emptyDocument(this.__wbg_ptr);
         return Document.__wrap(ret);
     }
+    /**
+     * The quill's example document, `undefined` when the quill has no
+     * `example.md` at its root: a filled-in page whose values are made up to show the
+     * quill in use, never kept. It comes back pinned to this quill's
+     * `name@version` and conformed as `parse` conforms, its parse and
+     * `conform::*` warnings on `doc.warnings`. Throws when the file does not
+     * parse or its `$quill` is not this quill's bare name.
+     * @returns {Document | undefined}
+     */
+    exampleDocument() {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.quill_exampleDocument(retptr, this.__wbg_ptr);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            if (r2) {
+                throw takeObject(r1);
+            }
+            return r0 === 0 ? undefined : Document.__wrap(r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
     /**
      * Build a quill from a file tree. Pure: the declared backend is resolved
      * later, at render time. Accepts a `Map<string, Uint8Array>` or a plain
@@ -1664,13 +1688,13 @@ export class Quill {
     }
     /**
      * Seed a starter composable `Card` of the given kind (carries `$kind`),
-     * committing an optional per-kind seed `overlay`'s fields and `$body`
-     * (`overlay › absent`, body `overlay › empty`). `undefined` when
-     * `cardKind` is not declared in this quill's schema.
+     * committing an optional per-kind seed `overlay`'s fields and `$body` in
+     * place of the kind's own `seed`, else that seed's. `undefined` when `cardKind` is
+     * not declared in this quill's schema.
      *
      * Pass `document.seedOverlay(cardKind)` as `overlay` so a card added to a
      * template-derived document inherits its curated starting values; omit it
-     * for the bare schema seed.
+     * for a card carrying the kind's seed alone.
      * @param {string} card_kind
      * @param {Record<string, unknown> | undefined} overlay
      * @returns {Card | undefined}
@@ -1694,9 +1718,9 @@ export class Quill {
     }
     /**
      * Seed a starter `Document` from the schema: the main card plus one instance
-     * of each composable card kind, each body empty and every field absent
-     * (interpolated at render as `default:`, else the field's blank). No
-     * `example:` is committed (a field's or `body.example`).
+     * of each composable card kind, each carrying its kind's `seed` and every
+     * other field absent (interpolated at render as `default:`, else the
+     * field's blank).
      * @returns {Document}
      */
     seedDocument() {

package/render/wasm_bg.wasm.d.ts

@@ -76,6 +76,7 @@ export const quill_backendId: (a: number, b: number) => void;
 export const quill_blueprint: (a: number, b: number) => void;
 export const quill_conform: (a: number, b: number, c: number) => void;
 export const quill_emptyDocument: (a: number) => number;
+export const quill_exampleDocument: (a: number, b: number) => void;
 export const quill_fromTree: (a: number, b: number) => void;
 export const quill_metadata: (a: number, b: number) => void;
 export const quill_parse: (a: number, b: number, c: number, d: number) => void;