@quillmark/wasm 0.87.3 → 0.88.0

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # Changelog
 
+## v0.88.0 - 2026-06-05
+
+- **Breaking (bindings + Rust API):** a single canonical **`Card` wire shape** now
+  flows in *both* directions. Core owns it as `quillmark_core::CardWire` (with
+  `From<&Card>` / `TryFrom<CardWire>`); the WASM/Python bindings serialize and
+  deserialize it instead of hand-rolling their own per-card translation. The
+  flat `CardInput { kind, fields?, body? }` input type is **removed**:
+  `Document.pushCard` / `insertCard` (`push_card` / `insert_card`) now accept the
+  same `Card` shape they return (`{ kind, payloadItems, … }`), so a card from
+  `cards` / `removeCard` / `quill.seedCard` feeds straight back in. Build a fresh
+  card from a flat field map with the new **`Document.makeCard`** /
+  `Document.make_card` helper. A stale `{ kind, fields }` object is now a loud
+  error (`deny_unknown_fields`), not a silently-empty card. The seeded per-card
+  getters `quill.seedMain` / `quill.seedCard` (`seed_main` / `seed_card`) are
+  exposed on both bindings, mirroring the Rust `Quill::seed_main` / `seed_card`.
+- **Breaking (Rust API):** `Document::push_card` now returns
+  `Result<(), EditError>` and, with `insert_card`, validates that the card's
+  `$kind` is a valid, non-reserved composable kind — the cards-list invariant is
+  enforced at the edit op rather than incidentally at `Card::new`.
+- **Breaking (bindings + Rust API):** the schema-aware **form view is removed**.
+  `Quill::form` / `Quill::blank_main` / `Quill::blank_card` (and the
+  `quill.form` / `blankMain` / `blankCard` bindings) are gone, along with the
+  `Form` / `FormCard` / `FormFieldValue` / `FormFieldSource` types. Validation
+  diagnostics now flow through `Quill::validate(&Document) -> Vec<Diagnostic>`
+  (`quill.validate(doc)` in WASM/Python), which forwards the canonical
+  `validation::*` diagnostics and keeps the non-fatal `validation::field_absent`
+  completeness signal that `render` demotes. Field values/defaults/order are a
+  `Document` × `quill.schema` join the consumer performs directly. See
+  `docs/migrations/0.87-to-0.88.md`.
+- **Breaking (diagnostics):** the validation code `validation::must_fill_absent`
+  is renamed `validation::field_absent`. "Must-fill" is now scoped to the
+  blueprint communication surface (the `<must-fill>` sentinel and the fatal
+  `validation::must_fill_sentinel`); an *absent* field is a non-fatal
+  completeness signal, not a fill requirement, since the render floor
+  zero-fills it. The schema cell axis is renamed accordingly: the no-`default:`
+  cell is **Unendorsed** (was "Must Fill"), the antonym of **Endorsed** —
+  consumers routing on the old code or label must update. Internally
+  `ValidationError::MustFillUnset { source }` splits into `FieldAbsent` and
+  `MustFillSentinel` and the `MustFillSource` enum is removed.
+- **Breaking (bindings + Rust API):** the `example` reference document is
+  removed. `QuillConfig::example()` and the `Quill.example` (WASM) /
+  `Quill.example` (Python) getters are gone. Its "show me a filled-out one"
+  role is served by seeding — `Quill::seed_document()` / `Quill.seedDocument()`
+  / `Quill.seed_document()` — which returns a committed `Document` rather than
+  an annotated string. The CLI `render` with no input file now renders the
+  seeded document. Nothing consumed the example document's annotations (the
+  authoring surface is `blueprint()`), so the projection collapses into the
+  seed: internally the `FillSource` fork in blueprint emission is gone and the
+  blueprint always renders `default:` else the `<must-fill>` sentinel.
+- **wasm:** lower the npm package `engines.node` floor from `>=24` to `>=22`.
+  The runtime never required 24 — `--weak-refs` needs only Node 14.6+, and the
+  `using` sugar that motivated the 24 floor is optional (a `try` / `finally`
+  fallback covers Node 22). The aggressive floor hard-blocked installs on Node
+  22 CI/dev images under `engine-strict`.
+- **wasm:** `Document.makeCard(kind, fields?, body?)` now types `fields` as
+  optional in the generated `.d.ts` (was required, contradicting its docs);
+  omitting it yields an empty field map, as before.
+- **docs:** fix the `Quill.schema` getter doc — the returned schema **includes**
+  `ui` hints (it never stripped them); the stale "ui hints stripped" wording is
+  corrected. The 0.87→0.88 migration guide now documents the `fill` flag's
+  `!fill`-placeholder semantics and clarifies that seeding is example-filled,
+  not a blank-form replacement.
+- **blueprint:** flatten `group_fields` and drop the unused group label (#697).
+- **docs:** document seeding (example → absent), fix a block-scalar prescan
+  bug, and add commitment-ladder docs (#691).
+- **docs(canon):** dedup field-resolution semantics into SCHEMAS (#692); note
+  that released migration guides are era-accurate and immutable (#695); prune
+  evolutionary information from comments and canon docs (#700).
+
 ## v0.87.3 - 2026-06-04
 
 - Complete and consolidate the $ext mutator surface (#689)

package/README.md

@@ -160,18 +160,52 @@ O(1) getter for the number of composable cards (excluding the main card).
 Use this to validate indices before calling card mutators (`removeCard`,
 `updateCardField`, etc.) without allocating the full `cards` array.
 
-### `quill.form(doc)`
+### `quill.validate(doc)`
 
-Returns `{ main, cards, diagnostics }` — a schema-aware snapshot of `doc`
-without invoking the backend. `diagnostics` contains validation errors and
-warnings; an empty array means the document is valid. Useful for validating
-content without rendering:
+Returns `Diagnostic[]` — the document validated against the quill schema,
+without invoking the backend. An empty array means the document is valid.
+Each diagnostic carries the canonical `validation::*` `code`, `path`, and
+`hint`. Includes the non-fatal `validation::field_absent` completeness
+signal that `render` demotes (an absent Unendorsed field zero-fills rather
+than failing), so filter by `severity`/`code` for blockers vs. hints:
 
 ```ts
-const form = quill.form(Document.fromMarkdown(markdown));
-const errors = form.diagnostics.filter(d => d.severity === "error");
+const diagnostics = quill.validate(Document.fromMarkdown(markdown));
+const errors = diagnostics.filter(d => d.severity === "error");
 ```
 
+To render a form editor, read field definitions from `quill.schema` (sort
+fields by each field's `ui.order`) and the authored values from the
+`Document` payload — there is no separate form-view projection.
+
+### `quill.seedDocument()`
+
+Returns a starter `Document` seeded from the schema: each field's `example:`
+is committed and every other field is left absent (the render layer fills
+`default:` → type-empty zero). Illustration-first — a field with both an
+`example` and a `default` renders its example. Use as the initial state for a
+"new document" editor.
+
+```ts
+const doc = quill.seedDocument();
+const markdown = doc.toMarkdown();
+```
+
+For per-card seeding, `quill.seedMain()` returns just the `$kind: main` card
+and `quill.seedCard(kind)` returns a starter composable card (or `undefined`
+if the kind is not declared). Both return the same `Card` shape as
+`doc.main` / `doc.cards`, which `doc.pushCard` / `doc.insertCard` accept
+directly:
+
+```ts
+doc.pushCard(quill.seedCard("note"));                 // seed → push
+doc.pushCard(Document.makeCard("note", { x: 1 }));    // build from a flat map
+```
+
+There is one `Card` shape in both directions — `pushCard` / `insertCard` take
+exactly what `cards` / `removeCard` / `seedCard` return. Build a fresh card
+from a flat field map with `Document.makeCard(kind, fields?, body?)`.
+
 ### `quill.render(parsed, opts?)` vs. `quill.open(parsed)`
 
 Use **`Quill.render`** for one-shot exports (PDF/SVG/PNG) — compiles, emits
@@ -248,9 +282,9 @@ canvas.style.height = `${result.layoutHeight}px`;
 
 A field's *cell* is inferred from whether its schema declares a `default:`:
 
-- **Must Fill** (no `default:`) — `quill.blueprint` renders `<must-fill>`
-  in the value cell. An absent Must Fill field is a non-fatal signal
-  (`validation::must_fill_absent`) — the render path zero-fills it
+- **Unendorsed** (no `default:`) — `quill.blueprint` renders `<must-fill>`
+  in the value cell. An absent Unendorsed field is a non-fatal signal
+  (`validation::field_absent`) — the render path zero-fills it
   silently. A surviving `<must-fill>` sentinel is fatal
   (`validation::must_fill_sentinel`). Partial documents are
   first-class; `quill.render(doc)` only throws for malformed input.
@@ -260,7 +294,7 @@ A field's *cell* is inferred from whether its schema declares a `default:`:
 
 `QuillFieldSchema` no longer carries a `required` axis. The legacy
 `validation::missing_required` code has been replaced by
-`validation::must_fill_absent`; the `validation::must_fill_sentinel`
+`validation::field_absent`; the `validation::must_fill_sentinel`
 code covers unreplaced sentinels.
 
 ### Errors
@@ -295,9 +329,10 @@ The wasm bindings are built with `--weak-refs`, so dropped `Document`,
 without manual `.free()` discipline. `.free()` is still emitted as an eager
 teardown hook for callers that want deterministic release.
 
-The package requires Node 24+ (`engines: { node: ">=24" }`) and current
-evergreen browsers; `--weak-refs` itself only needs Node 14.6+, but the
-published package floor is 24.
+The package floor is Node 22+ (`engines: { node: ">=22" }`) and current
+evergreen browsers; `--weak-refs` itself only needs Node 14.6+. The `using`
+sugar shown below ([explicit resource management][erm]) needs Node 24, but is
+optional — the `try` / `finally` fallback runs on the Node 22 floor.
 
 For environments where `using` (the [explicit resource management][erm]
 proposal) hasn't landed, use an explicit `try` / `finally`:

package/bundler/wasm.d.ts

@@ -1,19 +1,6 @@
 /* tslint:disable */
 /* eslint-disable */
 
-/**
- * Input shape for `Document.pushCard` and `Document.insertCard`.
- *
- * Only `kind` is required. `fields` defaults to `{}`, `body` to `""`.
- */
-export interface CardInput {
-    kind: string;
-    fields?: Record<string, unknown>;
-    body?: string;
-}
-
-
-
 /**
  * Page dimensions in Typst points (1 pt = 1/72 inch).
  *
@@ -85,6 +72,33 @@ export interface PaintResult {
 
 
 
+/** A field or comment entry in a `Card.payloadItems` list. */
+export type PayloadItem =
+| { type: "field"; key: string; value: unknown; fill?: boolean }
+| { type: "comment"; text: string; inline?: boolean };
+
+/**
+ * A single card block. The one shape exchanged in both directions: returned by
+ * `Document.main` / `Document.cards` / `Document.removeCard` / `Quill.seedCard`,
+ * and accepted by `Document.pushCard` / `Document.insertCard`. Build a fresh
+ * one with `Document.makeCard`.
+ *
+ * `$` system entries are hoisted to named fields: `kind` (the `$kind`, empty
+ * string when none), optional `quill` (the `$quill` `name@version`, main card
+ * only), optional `id` (`$id`), and optional `ext` (`$ext`). `payloadItems`
+ * carries user fields and comments in order.
+ */
+export interface Card {
+    kind: string;
+    quill?: string;
+    id?: string;
+    ext?: Record<string, unknown>;
+    payloadItems: PayloadItem[];
+    body: string;
+}
+
+
+
 /** UI layout hints for a single field. */
 export interface QuillFieldUi {
     group?: string;
@@ -110,9 +124,9 @@ export interface QuillCardBody {
  *
  * A field's *cell* is determined by `default`: a field with a `default`
  * is **Endorsed** (the rendered value is shippable as-is), while a field
- * without a `default` is **Must Fill** (the blueprint carries a
+ * without a `default` is **Unendorsed** (the blueprint carries a
  * `<must-fill>` sentinel and validation reports
- * `validation::must_fill_absent` if the field is absent at validate
+ * `validation::field_absent` if the field is absent at validate
  * time — a non-fatal signal, since the render path zero-fills an absent
  * field). There is no separate `required` axis.
  */
@@ -163,44 +177,6 @@ export interface QuillMetadata {
     [key: string]: unknown;
 }
 
-/** Source of a field's effective value in a form view. */
-export type FormFieldSource = "document" | "default" | "missing";
-
-/**
- * A single field's view within a `FormCard`.
- *
- * - `value` — the document-supplied value (`null` when absent).
- * - `default` — the schema default (`null` when no default is declared).
- * - `source` — where the effective value comes from.
- */
-export interface FormFieldValue {
-    value: unknown;
-    default: unknown;
-    source: FormFieldSource;
-}
-
-/**
- * A card viewed through its schema, as returned by `Quill.form`,
- * `Quill.blankMain`, and `Quill.blankCard`.
- */
-export interface FormCard {
-    schema: QuillCardSchema;
-    values: Record<string, FormFieldValue>;
-}
-
-/**
- * Schema-aware form view of a document, returned by `Quill.form`.
- *
- * - `main` — the main card viewed through the quill's main schema.
- * - `cards` — composable card blocks, in document order (unknown kinds excluded).
- * - `diagnostics` — diagnostics from unknown card kinds and validation.
- */
-export interface Form {
-    main: FormCard;
-    cards: FormCard[];
-    diagnostics: Diagnostic[];
-}
-
 
 export interface Artifact {
     format: OutputFormat;
@@ -208,13 +184,6 @@ export interface Artifact {
     mimeType: string;
 }
 
-export interface Card {
-    kind: string;
-    payloadItems: PayloadItem[];
-    ext?: Record<string, unknown> | undefined;
-    body: string;
-}
-
 export interface Diagnostic {
     severity: Severity;
     code?: string;
@@ -247,8 +216,6 @@ export interface RenderResult {
 
 export type OutputFormat = "pdf" | "svg" | "txt" | "png";
 
-export type PayloadItem = { type: "field"; key: string; value: unknown; fill?: boolean } | { type: "comment"; text: string; inline?: boolean };
-
 export type Severity = "error" | "warning" | "note";
 
 
@@ -304,18 +271,29 @@ export class Document {
      */
     static fromMarkdown(markdown: string): Document;
     /**
-     * Insert a card at `index` (must be in `0..=cards.length`).
+     * Insert a card at `index` (must be in `0..=cards.length`). Accepts a
+     * `Card` (see [`pushCard`](Self::push_card)).
+     */
+    insertCard(index: number, card: Card): void;
+    /**
+     * Build a fresh `Card` from a kind and a flat field map — the ergonomic
+     * constructor for `pushCard` / `insertCard`. `fields` is an optional
+     * `Record<string, unknown>` (each entry becomes a card field, in
+     * insertion order); `body` defaults to `""`. Kind validity is checked by
+     * `pushCard` / `insertCard`, not here.
      */
-    insertCard(index: number, card: CardInput): void;
+    static makeCard(kind: string, fields: Record<string, unknown>, body?: string | null): Card;
     /**
      * Move the card at `from` to position `to`. `from == to` is a no-op.
      */
     moveCard(from: number, to: number): void;
     /**
-     * Append a card to the end of the card list.
-     * Throws if `card.kind` is not a valid kind name.
+     * Append a card to the end of the card list. Accepts a `Card` (the shape
+     * returned by `cards` / `removeCard` / `quill.seedCard`); build a fresh
+     * one with [`Document.makeCard`](Document::make_card). Throws if
+     * `card.kind` is not a valid kind name.
      */
-    pushCard(card: CardInput): void;
+    pushCard(card: Card): void;
     /**
      * The canonical `$quill` reference grammar as author-facing text. Single
      * source of truth (CLI, Python, MCP): drive schema `describe` and
@@ -467,42 +445,59 @@ export class Quill {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    open(doc: Document): RenderSession;
+    render(doc: Document, opts?: RenderOptions | null): RenderResult;
     /**
-     * Blank `FormCard` for the given card kind. Returns `null` if `cardKind`
-     * is not declared in this quill's schema.
+     * Seed a starter composable `Card` of the given kind (carries `$kind`),
+     * committing its fields' `example:` values and leaving every other field
+     * absent. Returns `undefined` if `cardKind` is not declared in this
+     * quill's schema, else a `Card` that feeds straight into
+     * `Document.pushCard` / `insertCard`.
      */
-    blankCard(card_kind: string): FormCard | null;
+    seedCard(card_kind: string): Card | undefined;
     /**
-     * Blank `FormCard` for the main card with no document values.
-     * Every field's `source` is `"default"` or `"missing"`.
+     * Seed a starter `Document` from the schema — the main card plus one
+     * instance of each composable card kind, each committing its fields'
+     * `example:` values and leaving every other field absent (interpolated at
+     * render: `default:`, else type-empty zero). Illustration-first: a field
+     * with both an `example` and a `default` renders its example. See
+     * `prose/canon/SCHEMAS.md` § "Document seeding".
      */
-    blankMain(): FormCard;
+    seedDocument(): Document;
     /**
-     * The schema-aware form view of `doc`. Read-only snapshot at call time;
-     * subsequent edits to `doc` require calling `form` again.
+     * Seed a starter main `Card` (carries `$quill`) from the schema — the
+     * `$kind: main` card of [`seedDocument`](Self::seed_document) in
+     * isolation, committing each field's `example:` value. Returns the same
+     * `Card` shape as the `Document.main` getter.
      */
-    form(doc: Document): Form;
-    open(doc: Document): RenderSession;
-    render(doc: Document, opts?: RenderOptions | null): RenderResult;
+    seedMain(): Card;
+    /**
+     * Validate `doc` against this quill's schema, returning every diagnostic
+     * (an empty array when the document is valid).
+     *
+     * Forwards the canonical `validation::*` diagnostics — same `code`,
+     * `path`, and `hint` the engine emits — including the non-fatal
+     * `validation::field_absent` completeness signal that `render` demotes.
+     * Field values, defaults, and order are not part of this surface: read
+     * them from the `Document` payload and `Quill.schema` (fields carry
+     * `ui.order`).
+     */
+    validate(doc: Document): Diagnostic[];
     /**
      * The resolved backend identifier (e.g. `"typst"`).
      */
     readonly backendId: string;
     readonly blueprint: string;
-    /**
-     * The `example` reference document — the illustrative "show me a
-     * filled-out one." Each field renders its `example:`, else its
-     * `default:`, else the type-empty zero value, with no `<must-fill>`
-     * sentinels. See `prose/canon/BLUEPRINT.md`.
-     */
-    readonly example: string;
     /**
      * Identity snapshot of the `quill:` section of `Quill.yaml`, plus
      * `supportedFormats` and any extra `quill:` keys.
      */
     readonly metadata: QuillMetadata;
     /**
-     * Document schema with `ui` hints stripped — for LLM/MCP consumers.
+     * Document schema for the quill: the user-fillable fields plus their
+     * `ui` hints (group / order / showWhen). The single field-metadata
+     * surface — drives form editors and LLM/MCP consumers alike. Returns the
+     * `QuillSchema` shape.
      */
     readonly schema: QuillSchema;
     /**

package/bundler/wasm_bg.js

@@ -195,9 +195,10 @@ export class Document {
         }
     }
     /**
-     * Insert a card at `index` (must be in `0..=cards.length`).
+     * Insert a card at `index` (must be in `0..=cards.length`). Accepts a
+     * `Card` (see [`pushCard`](Self::push_card)).
      * @param {number} index
-     * @param {CardInput} card
+     * @param {Card} card
      */
     insertCard(index, card) {
         try {
@@ -221,6 +222,36 @@ export class Document {
         const ret = wasm.document_main(this.__wbg_ptr);
         return takeObject(ret);
     }
+    /**
+     * Build a fresh `Card` from a kind and a flat field map — the ergonomic
+     * constructor for `pushCard` / `insertCard`. `fields` is an optional
+     * `Record<string, unknown>` (each entry becomes a card field, in
+     * insertion order); `body` defaults to `""`. Kind validity is checked by
+     * `pushCard` / `insertCard`, not here.
+     * @param {string} kind
+     * @param {Record<string, unknown>} fields
+     * @param {string | null} [body]
+     * @returns {Card}
+     */
+    static makeCard(kind, fields, body) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passStringToWasm0(kind, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            var ptr1 = isLikeNone(body) ? 0 : passStringToWasm0(body, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            var len1 = WASM_VECTOR_LEN;
+            wasm.document_makeCard(retptr, ptr0, len0, isLikeNone(fields) ? 0 : addHeapObject(fields), ptr1, len1);
+            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 takeObject(r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
     /**
      * Move the card at `from` to position `to`. `from == to` is a no-op.
      * @param {number} from
@@ -240,9 +271,11 @@ export class Document {
         }
     }
     /**
-     * Append a card to the end of the card list.
-     * Throws if `card.kind` is not a valid kind name.
-     * @param {CardInput} card
+     * Append a card to the end of the card list. Accepts a `Card` (the shape
+     * returned by `cards` / `removeCard` / `quill.seedCard`); build a fresh
+     * one with [`Document.makeCard`](Document::make_card). Throws if
+     * `card.kind` is not a valid kind name.
+     * @param {Card} card
      */
     pushCard(card) {
         try {
@@ -784,49 +817,6 @@ export class Quill {
             wasm.__wbindgen_export4(deferred1_0, deferred1_1, 1);
         }
     }
-    /**
-     * Blank `FormCard` for the given card kind. Returns `null` if `cardKind`
-     * is not declared in this quill's schema.
-     * @param {string} card_kind
-     * @returns {FormCard | null}
-     */
-    blankCard(card_kind) {
-        try {
-            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-            const ptr0 = passStringToWasm0(card_kind, wasm.__wbindgen_export, wasm.__wbindgen_export2);
-            const len0 = WASM_VECTOR_LEN;
-            wasm.quill_blankCard(retptr, this.__wbg_ptr, ptr0, len0);
-            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 takeObject(r0);
-        } finally {
-            wasm.__wbindgen_add_to_stack_pointer(16);
-        }
-    }
-    /**
-     * Blank `FormCard` for the main card with no document values.
-     * Every field's `source` is `"default"` or `"missing"`.
-     * @returns {FormCard}
-     */
-    blankMain() {
-        try {
-            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-            wasm.quill_blankMain(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 takeObject(r0);
-        } finally {
-            wasm.__wbindgen_add_to_stack_pointer(16);
-        }
-    }
     /**
      * @returns {string}
      */
@@ -846,51 +836,6 @@ export class Quill {
             wasm.__wbindgen_export4(deferred1_0, deferred1_1, 1);
         }
     }
-    /**
-     * The `example` reference document — the illustrative "show me a
-     * filled-out one." Each field renders its `example:`, else its
-     * `default:`, else the type-empty zero value, with no `<must-fill>`
-     * sentinels. See `prose/canon/BLUEPRINT.md`.
-     * @returns {string}
-     */
-    get example() {
-        let deferred1_0;
-        let deferred1_1;
-        try {
-            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-            wasm.quill_example(retptr, this.__wbg_ptr);
-            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
-            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
-            deferred1_0 = r0;
-            deferred1_1 = r1;
-            return getStringFromWasm0(r0, r1);
-        } finally {
-            wasm.__wbindgen_add_to_stack_pointer(16);
-            wasm.__wbindgen_export4(deferred1_0, deferred1_1, 1);
-        }
-    }
-    /**
-     * The schema-aware form view of `doc`. Read-only snapshot at call time;
-     * subsequent edits to `doc` require calling `form` again.
-     * @param {Document} doc
-     * @returns {Form}
-     */
-    form(doc) {
-        try {
-            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-            _assertClass(doc, Document);
-            wasm.quill_form(retptr, this.__wbg_ptr, doc.__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 takeObject(r0);
-        } finally {
-            wasm.__wbindgen_add_to_stack_pointer(16);
-        }
-    }
     /**
      * Identity snapshot of the `quill:` section of `Quill.yaml`, plus
      * `supportedFormats` and any extra `quill:` keys.
@@ -942,13 +887,55 @@ export class Quill {
         }
     }
     /**
-     * Document schema with `ui` hints stripped — for LLM/MCP consumers.
+     * Document schema for the quill: the user-fillable fields plus their
+     * `ui` hints (group / order / showWhen). The single field-metadata
+     * surface — drives form editors and LLM/MCP consumers alike. Returns the
+     * `QuillSchema` shape.
      * @returns {QuillSchema}
      */
     get schema() {
         const ret = wasm.quill_schema(this.__wbg_ptr);
         return takeObject(ret);
     }
+    /**
+     * Seed a starter composable `Card` of the given kind (carries `$kind`),
+     * committing its fields' `example:` values and leaving every other field
+     * absent. Returns `undefined` if `cardKind` is not declared in this
+     * quill's schema, else a `Card` that feeds straight into
+     * `Document.pushCard` / `insertCard`.
+     * @param {string} card_kind
+     * @returns {Card | undefined}
+     */
+    seedCard(card_kind) {
+        const ptr0 = passStringToWasm0(card_kind, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.quill_seedCard(this.__wbg_ptr, ptr0, len0);
+        return takeObject(ret);
+    }
+    /**
+     * Seed a starter `Document` from the schema — the main card plus one
+     * instance of each composable card kind, each committing its fields'
+     * `example:` values and leaving every other field absent (interpolated at
+     * render: `default:`, else type-empty zero). Illustration-first: a field
+     * with both an `example` and a `default` renders its example. See
+     * `prose/canon/SCHEMAS.md` § "Document seeding".
+     * @returns {Document}
+     */
+    seedDocument() {
+        const ret = wasm.quill_seedDocument(this.__wbg_ptr);
+        return Document.__wrap(ret);
+    }
+    /**
+     * Seed a starter main `Card` (carries `$quill`) from the schema — the
+     * `$kind: main` card of [`seedDocument`](Self::seed_document) in
+     * isolation, committing each field's `example:` value. Returns the same
+     * `Card` shape as the `Document.main` getter.
+     * @returns {Card}
+     */
+    seedMain() {
+        const ret = wasm.quill_seedMain(this.__wbg_ptr);
+        return takeObject(ret);
+    }
     /**
      * `true` iff `RenderSession.paint` and `RenderSession.pageSize` will
      * succeed for sessions opened by this quill. Use as a precondition
@@ -959,6 +946,35 @@ export class Quill {
         const ret = wasm.quill_supportsCanvas(this.__wbg_ptr);
         return ret !== 0;
     }
+    /**
+     * Validate `doc` against this quill's schema, returning every diagnostic
+     * (an empty array when the document is valid).
+     *
+     * Forwards the canonical `validation::*` diagnostics — same `code`,
+     * `path`, and `hint` the engine emits — including the non-fatal
+     * `validation::field_absent` completeness signal that `render` demotes.
+     * Field values, defaults, and order are not part of this surface: read
+     * them from the `Document` payload and `Quill.schema` (fields carry
+     * `ui.order`).
+     * @param {Document} doc
+     * @returns {Diagnostic[]}
+     */
+    validate(doc) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            _assertClass(doc, Document);
+            wasm.quill_validate(retptr, this.__wbg_ptr, doc.__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 takeObject(r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
 }
 if (Symbol.dispose) Quill.prototype[Symbol.dispose] = Quill.prototype.free;
 
@@ -1159,10 +1175,6 @@ export function __wbg_Error_960c155d3d49e4c2(arg0, arg1) {
     const ret = Error(getStringFromWasm0(arg0, arg1));
     return addHeapObject(ret);
 }
-export function __wbg_Number_32bf70a599af1d4b(arg0) {
-    const ret = Number(getObject(arg0));
-    return ret;
-}
 export function __wbg_String_8564e559799eccda(arg0, arg1) {
     const ret = String(getObject(arg1));
     const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_export, wasm.__wbindgen_export2);
@@ -1357,6 +1369,16 @@ export function __wbg_instanceof_Map_1b76fd4635be43eb(arg0) {
     const ret = result;
     return ret;
 }
+export function __wbg_instanceof_Object_7c99480a1cdfb911(arg0) {
+    let result;
+    try {
+        result = getObject(arg0) instanceof Object;
+    } catch (_) {
+        result = false;
+    }
+    const ret = result;
+    return ret;
+}
 export function __wbg_instanceof_OffscreenCanvasRenderingContext2d_285a274020b4f230(arg0) {
     let result;
     try {
@@ -1389,6 +1411,10 @@ export function __wbg_iterator_013bc09ec998c2a7() {
     const ret = Symbol.iterator;
     return addHeapObject(ret);
 }
+export function __wbg_keys_2fd1bfdda7e278ca(arg0) {
+    const ret = Object.keys(getObject(arg0));
+    return addHeapObject(ret);
+}
 export function __wbg_length_3d4ecd04bd8d22f1(arg0) {
     const ret = getObject(arg0).length;
     return ret;

package/bundler/wasm_bg.wasm.d.ts

@@ -17,6 +17,7 @@ export const document_fromJson: (a: number, b: number, c: number) => void;
 export const document_fromMarkdown: (a: number, b: number, c: number) => void;
 export const document_insertCard: (a: number, b: number, c: number, d: number) => void;
 export const document_main: (a: number) => number;
+export const document_makeCard: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
 export const document_moveCard: (a: number, b: number, c: number, d: number) => void;
 export const document_pushCard: (a: number, b: number, c: number) => void;
 export const document_quillRef: (a: number, b: number) => void;
@@ -46,16 +47,16 @@ export const document_updateCardField: (a: number, b: number, c: number, d: numb
 export const document_warnings: (a: number) => number;
 export const init: () => void;
 export const quill_backendId: (a: number, b: number) => void;
-export const quill_blankCard: (a: number, b: number, c: number, d: number) => void;
-export const quill_blankMain: (a: number, b: number) => void;
 export const quill_blueprint: (a: number, b: number) => void;
-export const quill_example: (a: number, b: number) => void;
-export const quill_form: (a: number, b: number, c: number) => void;
 export const quill_metadata: (a: number) => number;
 export const quill_open: (a: number, b: number, c: number) => void;
 export const quill_render: (a: number, b: number, c: number, d: number) => void;
 export const quill_schema: (a: number) => number;
+export const quill_seedCard: (a: number, b: number, c: number) => number;
+export const quill_seedDocument: (a: number) => number;
+export const quill_seedMain: (a: number) => number;
 export const quill_supportsCanvas: (a: number) => number;
+export const quill_validate: (a: number, b: number, c: number) => void;
 export const quillmark_new: () => number;
 export const quillmark_quill: (a: number, b: number, c: number) => void;
 export const rendersession_backendId: (a: number, b: number) => void;

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@quillmark/wasm",
-  "version": "0.87.3",
+  "version": "0.88.0",
   "description": "WebAssembly bindings for quillmark",
   "type": "module",
   "license": "MIT OR Apache-2.0",
   "engines": {
-    "node": ">=24"
+    "node": ">=22"
   },
   "repository": {
     "type": "git",