@quillmark/wasm 0.87.2 → 0.88.0-rc.1

package/CHANGELOG.md

@@ -1,5 +1,82 @@
 # Changelog
 
+## v0.88.0-rc.1 - 2026-06-05
+
+- blueprint: flatten group_fields, drop unused group label (#697)
+- Update CLAUDE.md
+- Expose seedMain/seedCard to WASM + Python bindings (#696)
+- docs: note that released migration guides are era-accurate and immutable (#695)
+- Remove form-view projection; add Quill::validate (#694)
+- Remove example() reference document, fold into seeding (#693)
+- Document seeding (example → absent) + block-scalar prescan fix + commitment-ladder docs (#691)
+- docs(canon): dedup field-resolution semantics into SCHEMAS (#692)
+
+
+## Unreleased
+
+- **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.
+
+## v0.87.3 - 2026-06-04
+
+- Complete and consolidate the $ext mutator surface (#689)
+- Complete the `$ext` mutator matrix with namespace-scoped removal and
+  card-indexed namespace ops: `remove_ext_namespace` (Rust `Card`,
+  `removeExtNamespace` WASM, `remove_ext_namespace` Python) plus
+  `setCardExtNamespace` / `removeCardExtNamespace`. Deleting a sub-namespace
+  is now the preferred way to clear `$ext` state — it preserves sibling
+  consumers' slots and drops `$ext` entirely once empty, where `removeExt`
+  remains a blunt clear-everything escape hatch.
+- **Breaking (bindings):** the whole-map card mutator `updateCardExt` /
+  `update_card_ext` is renamed `setCardExt` / `set_card_ext` for naming
+  consistency with `setExt` on the main card.
+
 ## v0.87.2 - 2026-06-03
 
 - Expose $ext write path through the editor surface and bindings (#687)

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

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
@@ -326,20 +304,36 @@ export class Document {
     static quillRefHint(): string;
     removeCard(index: number): Card | undefined;
     /**
-     * Remove the `$ext` map from the card at `index`, returning the previous
-     * map or `undefined`. Throws if out of range.
+     * Remove the `$ext` map from the composable card at `index` *entirely*,
+     * returning the previous map or `undefined`. Throws if out of range.
+     * Prefer `removeCardExtNamespace` to clear only one consumer's slot.
      */
     removeCardExt(index: number): Record<string, unknown> | undefined;
+    /**
+     * Remove `namespace` from the composable card's `$ext` map, returning the
+     * value stored there or `undefined`; clears `$ext` entirely once empty.
+     * The card-indexed twin of `removeExtNamespace`. Throws if out of range.
+     */
+    removeCardExtNamespace(index: number, namespace: string): any;
     /**
      * Remove a field on the card at `index`. Returns the removed value or
      * `undefined`. Throws if `index` is out of range or `name` is invalid.
      */
     removeCardField(index: number, name: string): any;
     /**
-     * Remove the `$ext` map from the main card, returning the previous map or
-     * `undefined`.
+     * Remove the `$ext` map from the main card *entirely*, returning the
+     * previous map or `undefined`. This is a blunt escape hatch that discards
+     * every namespace at once — prefer `removeExtNamespace` to clear only your
+     * own slot while leaving sibling consumers' state intact.
      */
     removeExt(): Record<string, unknown> | undefined;
+    /**
+     * Remove `namespace` from the main card's `$ext` map, returning the value
+     * stored there or `undefined`. This is the recommended way to clear `$ext`
+     * state: sibling namespaces survive, and when the last namespace is removed
+     * the `$ext` entry is dropped entirely (not left as `$ext: {}`).
+     */
+    removeExtNamespace(namespace: string): any;
     /**
      * Remove a payload field on the main card, returning the removed value or
      * `undefined`. Throws if `name` does not match `[a-z_][a-z0-9_]*`.
@@ -353,6 +347,18 @@ export class Document {
      * `fromJson` throws.
      */
     static schemaVersionOf(json: string): string | undefined;
+    /**
+     * Replace the `$ext` map on the composable card at `index`. Throws if out
+     * of range or `value` is not a plain object. Named to mirror `setExt` on
+     * the main card; `setCardExtNamespace` is the sibling-safe alternative.
+     */
+    setCardExt(index: number, value: any): void;
+    /**
+     * Merge `value` into the composable card's `$ext` map under `namespace`,
+     * preserving sibling namespaces. The card-indexed twin of `setExtNamespace`.
+     * Throws if out of range or `value` cannot be serialized.
+     */
+    setCardExtNamespace(index: number, namespace: string, value: any): void;
     /**
      * Replace the kind of the card at `index`. Payload and body are untouched;
      * schema-aware migration is the caller's responsibility.
@@ -416,11 +422,6 @@ export class Document {
      * Replace the body of the card at `index`. Throws if out of range.
      */
     updateCardBody(index: number, body: string): void;
-    /**
-     * Replace the `$ext` map on the card at `index`. Throws if out of range or
-     * `value` is not a plain object.
-     */
-    updateCardExt(index: number, value: any): void;
     /**
      * Update a field on the card at `index`.
      * Throws if `index` is out of range, `name` is reserved or invalid.
@@ -444,35 +445,49 @@ 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.

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, 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 {
@@ -309,8 +342,9 @@ export class Document {
         return takeObject(ret);
     }
     /**
-     * Remove the `$ext` map from the card at `index`, returning the previous
-     * map or `undefined`. Throws if out of range.
+     * Remove the `$ext` map from the composable card at `index` *entirely*,
+     * returning the previous map or `undefined`. Throws if out of range.
+     * Prefer `removeCardExtNamespace` to clear only one consumer's slot.
      * @param {number} index
      * @returns {Record<string, unknown> | undefined}
      */
@@ -329,6 +363,31 @@ export class Document {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
+    /**
+     * Remove `namespace` from the composable card's `$ext` map, returning the
+     * value stored there or `undefined`; clears `$ext` entirely once empty.
+     * The card-indexed twin of `removeExtNamespace`. Throws if out of range.
+     * @param {number} index
+     * @param {string} namespace
+     * @returns {any}
+     */
+    removeCardExtNamespace(index, namespace) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passStringToWasm0(namespace, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            wasm.document_removeCardExtNamespace(retptr, this.__wbg_ptr, index, 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);
+        }
+    }
     /**
      * Remove a field on the card at `index`. Returns the removed value or
      * `undefined`. Throws if `index` is out of range or `name` is invalid.
@@ -354,14 +413,30 @@ export class Document {
         }
     }
     /**
-     * Remove the `$ext` map from the main card, returning the previous map or
-     * `undefined`.
+     * Remove the `$ext` map from the main card *entirely*, returning the
+     * previous map or `undefined`. This is a blunt escape hatch that discards
+     * every namespace at once — prefer `removeExtNamespace` to clear only your
+     * own slot while leaving sibling consumers' state intact.
      * @returns {Record<string, unknown> | undefined}
      */
     removeExt() {
         const ret = wasm.document_removeExt(this.__wbg_ptr);
         return takeObject(ret);
     }
+    /**
+     * Remove `namespace` from the main card's `$ext` map, returning the value
+     * stored there or `undefined`. This is the recommended way to clear `$ext`
+     * state: sibling namespaces survive, and when the last namespace is removed
+     * the `$ext` entry is dropped entirely (not left as `$ext: {}`).
+     * @param {string} namespace
+     * @returns {any}
+     */
+    removeExtNamespace(namespace) {
+        const ptr0 = passStringToWasm0(namespace, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.document_removeExtNamespace(this.__wbg_ptr, ptr0, len0);
+        return takeObject(ret);
+    }
     /**
      * Remove a payload field on the main card, returning the removed value or
      * `undefined`. Throws if `name` does not match `[a-z_][a-z0-9_]*`.
@@ -419,6 +494,49 @@ export class Document {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
+    /**
+     * Replace the `$ext` map on the composable card at `index`. Throws if out
+     * of range or `value` is not a plain object. Named to mirror `setExt` on
+     * the main card; `setCardExtNamespace` is the sibling-safe alternative.
+     * @param {number} index
+     * @param {any} value
+     */
+    setCardExt(index, value) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.document_setCardExt(retptr, this.__wbg_ptr, index, addHeapObject(value));
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            if (r1) {
+                throw takeObject(r0);
+            }
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
+    /**
+     * Merge `value` into the composable card's `$ext` map under `namespace`,
+     * preserving sibling namespaces. The card-indexed twin of `setExtNamespace`.
+     * Throws if out of range or `value` cannot be serialized.
+     * @param {number} index
+     * @param {string} namespace
+     * @param {any} value
+     */
+    setCardExtNamespace(index, namespace, value) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passStringToWasm0(namespace, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            wasm.document_setCardExtNamespace(retptr, this.__wbg_ptr, index, ptr0, len0, addHeapObject(value));
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            if (r1) {
+                throw takeObject(r0);
+            }
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
     /**
      * Replace the kind of the card at `index`. Payload and body are untouched;
      * schema-aware migration is the caller's responsibility.
@@ -629,25 +747,6 @@ export class Document {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
-    /**
-     * Replace the `$ext` map on the card at `index`. Throws if out of range or
-     * `value` is not a plain object.
-     * @param {number} index
-     * @param {any} value
-     */
-    updateCardExt(index, value) {
-        try {
-            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-            wasm.document_updateCardExt(retptr, this.__wbg_ptr, index, addHeapObject(value));
-            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
-            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
-            if (r1) {
-                throw takeObject(r0);
-            }
-        } finally {
-            wasm.__wbindgen_add_to_stack_pointer(16);
-        }
-    }
     /**
      * Update a field on the card at `index`.
      * Throws if `index` is out of range, `name` is reserved or invalid.
@@ -718,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}
      */
@@ -780,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.
@@ -883,6 +894,45 @@ export class Quill {
         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
@@ -893,6 +943,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;
 
@@ -1093,10 +1172,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);
@@ -1291,6 +1366,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 {
@@ -1323,6 +1408,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,17 +17,22 @@ 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;
 export const document_quillRefHint: (a: number) => void;
 export const document_removeCard: (a: number, b: number) => number;
 export const document_removeCardExt: (a: number, b: number, c: number) => void;
+export const document_removeCardExtNamespace: (a: number, b: number, c: number, d: number, e: number) => void;
 export const document_removeCardField: (a: number, b: number, c: number, d: number, e: number) => void;
 export const document_removeExt: (a: number) => number;
+export const document_removeExtNamespace: (a: number, b: number, c: number) => number;
 export const document_removeField: (a: number, b: number, c: number, d: number) => void;
 export const document_replaceBody: (a: number, b: number, c: number) => void;
 export const document_schemaVersionOf: (a: number, b: number, c: number) => void;
+export const document_setCardExt: (a: number, b: number, c: number, d: number) => void;
+export const document_setCardExtNamespace: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
 export const document_setCardKind: (a: number, b: number, c: number, d: number, e: number) => void;
 export const document_setExt: (a: number, b: number, c: number) => void;
 export const document_setExtNamespace: (a: number, b: number, c: number, d: number, e: number) => void;
@@ -38,21 +43,20 @@ export const document_toJson: (a: number, b: number) => void;
 export const document_toMarkdown: (a: number, b: number) => void;
 export const document_tryFromJson: (a: number, b: number) => number;
 export const document_updateCardBody: (a: number, b: number, c: number, d: number, e: number) => void;
-export const document_updateCardExt: (a: number, b: number, c: number, d: number) => void;
 export const document_updateCardField: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
 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,6 +1,6 @@
 {
   "name": "@quillmark/wasm",
-  "version": "0.87.2",
+  "version": "0.88.0-rc.1",
   "description": "WebAssembly bindings for quillmark",
   "type": "module",
   "license": "MIT OR Apache-2.0",