@quillmark/wasm 0.116.0 → 0.117.0

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # Changelog
 
+## 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.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 body
-empty, every field absent (no `example:` is committed);
+empty, every field absent;
 `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[];
@@ -813,6 +810,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
@@ -846,8 +852,7 @@ 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`).
+     * (interpolated at render as `default:`, else the field's blank).
      */
     seedDocument(): Document;
     /**
@@ -1062,6 +1067,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
@@ -1374,8 +1398,7 @@ 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`).
+     * (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.117.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[];
@@ -1046,6 +1043,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
@@ -1079,8 +1085,7 @@ 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`).
+     * (interpolated at render as `default:`, else the field's blank).
      */
     seedDocument(): Document;
     /**
@@ -1337,6 +1342,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
@@ -1695,8 +1719,7 @@ 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`).
+     * (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;