@quillmark/wasm 0.91.0 → 0.92.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## v0.92.0 - 2026-06-22
+
+- 0.92 technical-debt sweep: correctness, $seed hardening, de-duplication (#727)
+- dotnet: add $seed namespace writers (parity with Python/WASM)
+- refactor(core): unify $ext/$seed into one out-of-band Meta concept
+- Cleanup: simplify QuillWorld::font to a single expression
+- Cleanup: de-narrate comments, sync canon binding tables with .NET
+- dotnet: fix stale schema version (CI) + review-flagged polish
+- docs(migration): cover the !fill → !must_fill rename in the 0.92 guide
+- dotnet: fix native-lib copy to test project + two correctness bugs
+- Remove Document.seed(kind) for strict ext/seed symmetry
+- dotnet: expose $seed on the Card DTO
+- refactor(dotnet): rename engine class Quillmark -> QuillmarkEngine
+- Reject !fill: treat as a noncanonical tag, not a fill alias
+- Fix binding build break + warn on unsupported fill positions
+- fix(dotnet): resolve engine type in test namespace (CS0426)
+- docs(dotnet): trim README to a dense, consumer-focused surface
+- Address review nits: loud divergence, docs, coverage
+- Add storage schema 0.92.0: persist nested !must_fill
+- docs(canon): consolidate binding overviews into BINDINGS.md
+- feat($seed): reject $seed on composable cards (root-only, like $quill)
+- docs: move dotnet binding into canon, delete DESIGN.md
+- docs: reframe QmBytes by-value return as a tested assumption, not a defect
+- Carry nested !must_fill across the live wire (CardWire)
+- Address review: trap FFI panics, fix depth-limit asymmetry, Equals contract
+- Detect nested !must_fill on sequence-item inline first key
+- docs($seed): correct two claims flagged in review
+- Fix invalid '--' inside XML comment in Quillmark.csproj
+- fix(docs): drop canon links that break mkdocs --strict
+- Promote .NET binding: CI test job, NuGet release, first-class docs
+- Spike: .NET binding symmetrical to the Python binding
+- Capture and round-trip nested !must_fill markers
+- Make QuillValue an annotated value tree (fill on nodes)
+- fix(bindings): bump currentSchemaVersion to 0.92.0; add $seed JS test
+- Rename !fill tag to !must_fill (accept !fill as deprecated alias)
+- docs($seed): document the per-kind seed-overlay key across canon and spec
+- test($seed): cover parse/emit/storage, overlay layering, advisory validation
+- feat(core): first-class $seed key for per-card-kind seed overlays
+- Remove RenderSession and canvas-preview APIs from Python binding (#722)
+
+
 ## v0.91.0 - 2026-06-17
 
 - Upgrade Typst backend to 0.15 (#720)
@@ -9,35 +50,6 @@
 
 ## v0.90.0 - 2026-06-10
 
-
-
-## v0.89.1 - 2026-06-10
-
-- chore(release): v0.89.1-rc.1 (#714)
-- feat(wasm)!: 0.90 canonical API — engine-free Quill, single root export, typed errors; Python parity (#713)
-- Proposal: WASM bindings split (core + render) via backend-decoupled Quill (#710)
-- Add version selector matching and mismatch warnings (#708)
-- docs: density-optimization pass on user-facing docs (#703)
-- Remove role annotation from root block metadata header (#707)
-- canon: audit and correct all prose/canon/ docs (#704)
-- Fix makeCard fields/body typed as required in WASM .d.ts (#702)
-- Update CLAUDE.md
-
-
-## v0.89.1-rc.1 - 2026-06-10
-
-- feat(wasm)!: 0.90 canonical API — engine-free Quill, single root export, typed errors; Python parity (#713)
-- Proposal: WASM bindings split (core + render) via backend-decoupled Quill (#710)
-- Add version selector matching and mismatch warnings (#708)
-- docs: density-optimization pass on user-facing docs (#703)
-- Remove role annotation from root block metadata header (#707)
-- canon: audit and correct all prose/canon/ docs (#704)
-- Fix makeCard fields/body typed as required in WASM .d.ts (#702)
-- Update CLAUDE.md
-
-
-## Unreleased
-
 - **Breaking (Rust API + bindings):** `Quill` is now engine-free, validated
   data. It no longer holds a backend; the `Quillmark` engine becomes a backend
   registry + render dispatcher. Rendering and capability move onto the engine:
@@ -134,6 +146,30 @@
   bindings now use `unchecked_optional_param_type`. Callers can build a bare
   card with `Document.makeCard('kind')`.
 
+## v0.89.1 - 2026-06-10
+
+- chore(release): v0.89.1-rc.1 (#714)
+- feat(wasm)!: 0.90 canonical API — engine-free Quill, single root export, typed errors; Python parity (#713)
+- Proposal: WASM bindings split (core + render) via backend-decoupled Quill (#710)
+- Add version selector matching and mismatch warnings (#708)
+- docs: density-optimization pass on user-facing docs (#703)
+- Remove role annotation from root block metadata header (#707)
+- canon: audit and correct all prose/canon/ docs (#704)
+- Fix makeCard fields/body typed as required in WASM .d.ts (#702)
+- Update CLAUDE.md
+
+
+## v0.89.1-rc.1 - 2026-06-10
+
+- feat(wasm)!: 0.90 canonical API — engine-free Quill, single root export, typed errors; Python parity (#713)
+- Proposal: WASM bindings split (core + render) via backend-decoupled Quill (#710)
+- Add version selector matching and mismatch warnings (#708)
+- docs: density-optimization pass on user-facing docs (#703)
+- Remove role annotation from root block metadata header (#707)
+- canon: audit and correct all prose/canon/ docs (#704)
+- Fix makeCard fields/body typed as required in WASM .d.ts (#702)
+- Update CLAUDE.md
+
 ## v0.88.0 - 2026-06-05
 
 - **Breaking (bindings + Rust API):** a single canonical **`Card` wire shape** now

package/README.md

@@ -329,10 +329,9 @@ A field's *cell* is inferred from whether its schema declares a `default:`:
   default value followed by a `; delete-ok` annotation, and the default
   is used when the document omits the field.
 
-`QuillFieldSchema` no longer carries a `required` axis. The legacy
-`validation::missing_required` code has been replaced by
-`validation::field_absent`; the `validation::must_fill_sentinel`
-code covers unreplaced sentinels.
+`QuillFieldSchema` has no `required` axis. Absent Unendorsed fields emit
+`validation::field_absent`; a surviving `<must-fill>` sentinel emits
+`validation::must_fill_sentinel`.
 
 ### Errors
 

package/backends/typst/wasm.d.ts

@@ -1,6 +1,52 @@
 /* tslint:disable */
 /* eslint-disable */
 
+/**
+ * A path to a value nested inside a field `value`: `string` keys and
+ * `number` array indices, e.g. `["addr", "street"]` or `["recipients", 0, "name"]`.
+ */
+export type PathStep = string | number;
+
+/** A field or comment entry in a `Card.payloadItems` list. */
+export type PayloadItem =
+| {
+    type: "field";
+    key: string;
+    value: unknown;
+    fill?: boolean;
+    /**
+     * Paths to `!must_fill` markers nested *inside* `value` (the `value`
+     * projection itself is fill-free). Absent when the field has no nested
+     * placeholders. Preserved across `pushCard` / `makeCard`.
+     */
+    nestedFills?: PathStep[][];
+}
+| { 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`), optional `ext` (`$ext`), and optional `seed`
+ * (the `$seed` per-kind overlay map, main card only). `payloadItems` carries
+ * user fields and comments in order.
+ */
+export interface Card {
+    kind: string;
+    quill?: string;
+    id?: string;
+    ext?: Record<string, unknown>;
+    seed?: Record<string, unknown>;
+    payloadItems: PayloadItem[];
+    body: string;
+}
+
+
+
 /**
  * Page dimensions in Typst points (1 pt = 1/72 inch).
  *
@@ -72,33 +118,6 @@ 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;
@@ -227,8 +246,9 @@ export class Document {
     [Symbol.dispose](): void;
     /**
      * Authoring-ergonomics header introducing a blueprint to an LLM/MCP
-     * consumer for the given `quillName`. Surfaced verbatim by every binding
-     * so the wording stays uniform across CLI / Python / MCP.
+     * consumer for the given `quillName`. Re-exposes core's canonical text for
+     * JS consumers; any surface that draws from the same core source stays
+     * uniform.
      */
     static blueprintInstruction(quill_name: string): string;
     clone(): Document;
@@ -244,16 +264,17 @@ export class Document {
      */
     equals(other: Document): boolean;
     /**
-     * Render a Diagnostic as the canonical pretty-printed text every binding
-     * shows (CLI, Python, MCP). Single source of truth so a Diagnostic looks
+     * Render a Diagnostic as the canonical pretty-printed text (core's
+     * `Diagnostic::fmt_pretty`). Single source of truth so a Diagnostic looks
      * identical no matter which consumer surfaces it.
      */
     static formatDiagnostic(diag: Diagnostic): string;
     /**
-     * Authoring-format rules for the card-yaml markdown surface — the same
-     * text every binding (CLI, Python, MCP) shows so callers reading errors
-     * from one binding can use the rules from any other. Read once at
-     * startup and cache; the value never changes between calls.
+     * Authoring-format rules for the card-yaml markdown surface. The canonical
+     * text is core's (`quillmark_core::document::FORMAT_RULES`), re-exposed
+     * here for JS consumers so it matches any other surface that draws from the
+     * same source. Read once at startup and cache; the value never changes
+     * between calls.
      */
     static formatRules(): string;
     /**
@@ -294,11 +315,11 @@ export class Document {
      */
     pushCard(card: Card): void;
     /**
-     * The canonical `$quill` reference grammar as author-facing text. Single
-     * source of truth (CLI, Python, MCP): drive schema `describe` and
-     * validation messages from this instead of re-stating the rule — it
-     * matches the `hint` on `parse::invalid_quill_reference`. Cache it; the
-     * value never changes.
+     * The canonical `$quill` reference grammar as author-facing text. Core is
+     * the single source of truth: drive schema `describe` and validation
+     * messages from this instead of re-stating the rule — it matches the
+     * `hint` on `parse::invalid_quill_reference`. Cache it; the value never
+     * changes.
      */
     static quillRefHint(): string;
     removeCard(index: number): Card | undefined;
@@ -338,6 +359,12 @@ export class Document {
      * `undefined`. Throws if `name` does not match `[a-z_][a-z0-9_]*`.
      */
     removeField(name: string): any;
+    /**
+     * Remove `cardKind` from the main card's `$seed` map, returning its
+     * overlay or `undefined`; drops `$seed` entirely once empty. Sibling
+     * kinds survive.
+     */
+    removeSeedNamespace(card_kind: string): any;
     replaceBody(body: string): void;
     /**
      * Read the `schema` version tag from a raw storage DTO string without a
@@ -379,13 +406,13 @@ export class Document {
      */
     setExtNamespace(namespace: string, value: any): void;
     /**
-     * Update a payload field on the main card. Clears any existing `!fill` marker.
+     * Update a payload field on the main card. Clears any existing `!must_fill` marker.
      *
      * Throws if `name` does not match `[a-z_][a-z0-9_]*`.
      */
     setField(name: string, value: any): void;
     /**
-     * Update a payload field on the main card and mark it as `!fill`.
+     * Update a payload field on the main card and mark it as `!must_fill`.
      * Throws on invalid name (see [`setField`](Document::set_field)).
      */
     setFill(name: string, value: any): void;
@@ -393,6 +420,13 @@ export class Document {
      * Replace the QUILL reference string. Throws if `ref_str` is invalid.
      */
     setQuillRef(ref_str: string): void;
+    /**
+     * Merge a card-kind's seed `overlay` into the main card's `$seed` map
+     * under `cardKind`, preserving sibling kinds. Sets the starting values
+     * new cards of that kind spawn with. Throws if `overlay` cannot be
+     * serialized or nests too deep.
+     */
+    setSeedNamespace(card_kind: string, overlay: any): void;
     /**
      * Serialize this document to a versioned storage DTO string.
      *
@@ -456,12 +490,17 @@ export class Quill {
     static fromTree(tree: Map<string, Uint8Array>): Quill;
     /**
      * 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`.
+     * layering an optional per-kind seed `overlay` over the schema-example
+     * base (`overlay › example › absent`). Returns `undefined` if `cardKind`
+     * is not declared in this quill's schema, else a `Card` that feeds
+     * straight into `Document.pushCard` / `insertCard`.
+     *
+     * Pass `document.main.seed?.[cardKind]` as `overlay` so a card added to a
+     * template-derived document inherits its curated starting values; omit it
+     * (or pass `undefined` / `null`) for the bare schema seed. `overlay` is a
+     * plain object — this reads the document, it does not mutate it.
      */
-    seedCard(card_kind: string): Card | undefined;
+    seedCard(card_kind: string, overlay: Record<string, unknown> | undefined): Card | undefined;
     /**
      * Seed a starter `Document` from the schema — the main card plus one
      * instance of each composable card kind, each committing its fields'

package/backends/typst/wasm_bg.js

@@ -21,8 +21,9 @@ export class Document {
     }
     /**
      * Authoring-ergonomics header introducing a blueprint to an LLM/MCP
-     * consumer for the given `quillName`. Surfaced verbatim by every binding
-     * so the wording stays uniform across CLI / Python / MCP.
+     * consumer for the given `quillName`. Re-exposes core's canonical text for
+     * JS consumers; any surface that draws from the same core source stays
+     * uniform.
      * @param {string} quill_name
      * @returns {string}
      */
@@ -111,8 +112,8 @@ export class Document {
         return ret !== 0;
     }
     /**
-     * Render a Diagnostic as the canonical pretty-printed text every binding
-     * shows (CLI, Python, MCP). Single source of truth so a Diagnostic looks
+     * Render a Diagnostic as the canonical pretty-printed text (core's
+     * `Diagnostic::fmt_pretty`). Single source of truth so a Diagnostic looks
      * identical no matter which consumer surfaces it.
      * @param {Diagnostic} diag
      * @returns {string}
@@ -134,10 +135,11 @@ export class Document {
         }
     }
     /**
-     * Authoring-format rules for the card-yaml markdown surface — the same
-     * text every binding (CLI, Python, MCP) shows so callers reading errors
-     * from one binding can use the rules from any other. Read once at
-     * startup and cache; the value never changes between calls.
+     * Authoring-format rules for the card-yaml markdown surface. The canonical
+     * text is core's (`quillmark_core::document::FORMAT_RULES`), re-exposed
+     * here for JS consumers so it matches any other surface that draws from the
+     * same source. Read once at startup and cache; the value never changes
+     * between calls.
      * @returns {string}
      */
     static formatRules() {
@@ -332,11 +334,11 @@ export class Document {
         }
     }
     /**
-     * The canonical `$quill` reference grammar as author-facing text. Single
-     * source of truth (CLI, Python, MCP): drive schema `describe` and
-     * validation messages from this instead of re-stating the rule — it
-     * matches the `hint` on `parse::invalid_quill_reference`. Cache it; the
-     * value never changes.
+     * The canonical `$quill` reference grammar as author-facing text. Core is
+     * the single source of truth: drive schema `describe` and validation
+     * messages from this instead of re-stating the rule — it matches the
+     * `hint` on `parse::invalid_quill_reference`. Cache it; the value never
+     * changes.
      * @returns {string}
      */
     static quillRefHint() {
@@ -515,6 +517,30 @@ export class Document {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
+    /**
+     * Remove `cardKind` from the main card's `$seed` map, returning its
+     * overlay or `undefined`; drops `$seed` entirely once empty. Sibling
+     * kinds survive.
+     * @param {string} card_kind
+     * @returns {any}
+     */
+    removeSeedNamespace(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.document_removeSeedNamespace(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);
+        }
+    }
     /**
      * @param {string} body
      */
@@ -658,7 +684,7 @@ export class Document {
         }
     }
     /**
-     * Update a payload field on the main card. Clears any existing `!fill` marker.
+     * Update a payload field on the main card. Clears any existing `!must_fill` marker.
      *
      * Throws if `name` does not match `[a-z_][a-z0-9_]*`.
      * @param {string} name
@@ -680,7 +706,7 @@ export class Document {
         }
     }
     /**
-     * Update a payload field on the main card and mark it as `!fill`.
+     * Update a payload field on the main card and mark it as `!must_fill`.
      * Throws on invalid name (see [`setField`](Document::set_field)).
      * @param {string} name
      * @param {any} value
@@ -719,6 +745,29 @@ export class Document {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
+    /**
+     * Merge a card-kind's seed `overlay` into the main card's `$seed` map
+     * under `cardKind`, preserving sibling kinds. Sets the starting values
+     * new cards of that kind spawn with. Throws if `overlay` cannot be
+     * serialized or nests too deep.
+     * @param {string} card_kind
+     * @param {any} overlay
+     */
+    setSeedNamespace(card_kind, overlay) {
+        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.document_setSeedNamespace(retptr, this.__wbg_ptr, ptr0, len0, addHeapObject(overlay));
+            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);
+        }
+    }
     /**
      * Serialize this document to a versioned storage DTO string.
      *
@@ -976,19 +1025,25 @@ export class Quill {
     }
     /**
      * 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`.
+     * layering an optional per-kind seed `overlay` over the schema-example
+     * base (`overlay › example › absent`). Returns `undefined` if `cardKind`
+     * is not declared in this quill's schema, else a `Card` that feeds
+     * straight into `Document.pushCard` / `insertCard`.
+     *
+     * Pass `document.main.seed?.[cardKind]` as `overlay` so a card added to a
+     * template-derived document inherits its curated starting values; omit it
+     * (or pass `undefined` / `null`) for the bare schema seed. `overlay` is a
+     * plain object — this reads the document, it does not mutate it.
      * @param {string} card_kind
+     * @param {Record<string, unknown> | undefined} overlay
      * @returns {Card | undefined}
      */
-    seedCard(card_kind) {
+    seedCard(card_kind, overlay) {
         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_seedCard(retptr, this.__wbg_ptr, ptr0, len0);
+            wasm.quill_seedCard(retptr, this.__wbg_ptr, ptr0, len0, addHeapObject(overlay));
             var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
             var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
             var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);

package/backends/typst/wasm_bg.wasm.d.ts

@@ -29,6 +29,7 @@ export const document_removeCardField: (a: number, b: number, c: number, d: numb
 export const document_removeExt: (a: number, b: number) => void;
 export const document_removeExtNamespace: (a: number, b: number, c: number, d: number) => void;
 export const document_removeField: (a: number, b: number, c: number, d: number) => void;
+export const document_removeSeedNamespace: (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;
@@ -39,6 +40,7 @@ export const document_setExtNamespace: (a: number, b: number, c: number, d: numb
 export const document_setField: (a: number, b: number, c: number, d: number, e: number) => void;
 export const document_setFill: (a: number, b: number, c: number, d: number, e: number) => void;
 export const document_setQuillRef: (a: number, b: number, c: number, d: number) => void;
+export const document_setSeedNamespace: (a: number, b: number, c: number, d: number, e: number) => void;
 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;
@@ -51,7 +53,7 @@ export const quill_blueprint: (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_schema: (a: number, b: number) => void;
-export const quill_seedCard: (a: number, b: number, c: number, d: number) => void;
+export const quill_seedCard: (a: number, b: number, c: number, d: number, e: number) => void;
 export const quill_seedDocument: (a: number) => number;
 export const quill_seedMain: (a: number, b: number) => void;
 export const quill_toTree: (a: number) => number;

package/core/wasm.d.ts

@@ -1,9 +1,26 @@
 /* tslint:disable */
 /* eslint-disable */
 
+/**
+ * A path to a value nested inside a field `value`: `string` keys and
+ * `number` array indices, e.g. `["addr", "street"]` or `["recipients", 0, "name"]`.
+ */
+export type PathStep = string | number;
+
 /** A field or comment entry in a `Card.payloadItems` list. */
 export type PayloadItem =
-| { type: "field"; key: string; value: unknown; fill?: boolean }
+| {
+    type: "field";
+    key: string;
+    value: unknown;
+    fill?: boolean;
+    /**
+     * Paths to `!must_fill` markers nested *inside* `value` (the `value`
+     * projection itself is fill-free). Absent when the field has no nested
+     * placeholders. Preserved across `pushCard` / `makeCard`.
+     */
+    nestedFills?: PathStep[][];
+}
 | { type: "comment"; text: string; inline?: boolean };
 
 /**
@@ -14,14 +31,16 @@ export type PayloadItem =
  *
  * `$` 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.
+ * only), optional `id` (`$id`), optional `ext` (`$ext`), and optional `seed`
+ * (the `$seed` per-kind overlay map, main card only). `payloadItems` carries
+ * user fields and comments in order.
  */
 export interface Card {
     kind: string;
     quill?: string;
     id?: string;
     ext?: Record<string, unknown>;
+    seed?: Record<string, unknown>;
     payloadItems: PayloadItem[];
     body: string;
 }
@@ -134,8 +153,9 @@ export class Document {
     [Symbol.dispose](): void;
     /**
      * Authoring-ergonomics header introducing a blueprint to an LLM/MCP
-     * consumer for the given `quillName`. Surfaced verbatim by every binding
-     * so the wording stays uniform across CLI / Python / MCP.
+     * consumer for the given `quillName`. Re-exposes core's canonical text for
+     * JS consumers; any surface that draws from the same core source stays
+     * uniform.
      */
     static blueprintInstruction(quill_name: string): string;
     clone(): Document;
@@ -151,16 +171,17 @@ export class Document {
      */
     equals(other: Document): boolean;
     /**
-     * Render a Diagnostic as the canonical pretty-printed text every binding
-     * shows (CLI, Python, MCP). Single source of truth so a Diagnostic looks
+     * Render a Diagnostic as the canonical pretty-printed text (core's
+     * `Diagnostic::fmt_pretty`). Single source of truth so a Diagnostic looks
      * identical no matter which consumer surfaces it.
      */
     static formatDiagnostic(diag: Diagnostic): string;
     /**
-     * Authoring-format rules for the card-yaml markdown surface — the same
-     * text every binding (CLI, Python, MCP) shows so callers reading errors
-     * from one binding can use the rules from any other. Read once at
-     * startup and cache; the value never changes between calls.
+     * Authoring-format rules for the card-yaml markdown surface. The canonical
+     * text is core's (`quillmark_core::document::FORMAT_RULES`), re-exposed
+     * here for JS consumers so it matches any other surface that draws from the
+     * same source. Read once at startup and cache; the value never changes
+     * between calls.
      */
     static formatRules(): string;
     /**
@@ -201,11 +222,11 @@ export class Document {
      */
     pushCard(card: Card): void;
     /**
-     * The canonical `$quill` reference grammar as author-facing text. Single
-     * source of truth (CLI, Python, MCP): drive schema `describe` and
-     * validation messages from this instead of re-stating the rule — it
-     * matches the `hint` on `parse::invalid_quill_reference`. Cache it; the
-     * value never changes.
+     * The canonical `$quill` reference grammar as author-facing text. Core is
+     * the single source of truth: drive schema `describe` and validation
+     * messages from this instead of re-stating the rule — it matches the
+     * `hint` on `parse::invalid_quill_reference`. Cache it; the value never
+     * changes.
      */
     static quillRefHint(): string;
     removeCard(index: number): Card | undefined;
@@ -245,6 +266,12 @@ export class Document {
      * `undefined`. Throws if `name` does not match `[a-z_][a-z0-9_]*`.
      */
     removeField(name: string): any;
+    /**
+     * Remove `cardKind` from the main card's `$seed` map, returning its
+     * overlay or `undefined`; drops `$seed` entirely once empty. Sibling
+     * kinds survive.
+     */
+    removeSeedNamespace(card_kind: string): any;
     replaceBody(body: string): void;
     /**
      * Read the `schema` version tag from a raw storage DTO string without a
@@ -286,13 +313,13 @@ export class Document {
      */
     setExtNamespace(namespace: string, value: any): void;
     /**
-     * Update a payload field on the main card. Clears any existing `!fill` marker.
+     * Update a payload field on the main card. Clears any existing `!must_fill` marker.
      *
      * Throws if `name` does not match `[a-z_][a-z0-9_]*`.
      */
     setField(name: string, value: any): void;
     /**
-     * Update a payload field on the main card and mark it as `!fill`.
+     * Update a payload field on the main card and mark it as `!must_fill`.
      * Throws on invalid name (see [`setField`](Document::set_field)).
      */
     setFill(name: string, value: any): void;
@@ -300,6 +327,13 @@ export class Document {
      * Replace the QUILL reference string. Throws if `ref_str` is invalid.
      */
     setQuillRef(ref_str: string): void;
+    /**
+     * Merge a card-kind's seed `overlay` into the main card's `$seed` map
+     * under `cardKind`, preserving sibling kinds. Sets the starting values
+     * new cards of that kind spawn with. Throws if `overlay` cannot be
+     * serialized or nests too deep.
+     */
+    setSeedNamespace(card_kind: string, overlay: any): void;
     /**
      * Serialize this document to a versioned storage DTO string.
      *
@@ -363,12 +397,17 @@ export class Quill {
     static fromTree(tree: Map<string, Uint8Array>): Quill;
     /**
      * 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`.
+     * layering an optional per-kind seed `overlay` over the schema-example
+     * base (`overlay › example › absent`). Returns `undefined` if `cardKind`
+     * is not declared in this quill's schema, else a `Card` that feeds
+     * straight into `Document.pushCard` / `insertCard`.
+     *
+     * Pass `document.main.seed?.[cardKind]` as `overlay` so a card added to a
+     * template-derived document inherits its curated starting values; omit it
+     * (or pass `undefined` / `null`) for the bare schema seed. `overlay` is a
+     * plain object — this reads the document, it does not mutate it.
      */
-    seedCard(card_kind: string): Card | undefined;
+    seedCard(card_kind: string, overlay: Record<string, unknown> | undefined): Card | undefined;
     /**
      * Seed a starter `Document` from the schema — the main card plus one
      * instance of each composable card kind, each committing its fields'

package/core/wasm_bg.js

@@ -21,8 +21,9 @@ export class Document {
     }
     /**
      * Authoring-ergonomics header introducing a blueprint to an LLM/MCP
-     * consumer for the given `quillName`. Surfaced verbatim by every binding
-     * so the wording stays uniform across CLI / Python / MCP.
+     * consumer for the given `quillName`. Re-exposes core's canonical text for
+     * JS consumers; any surface that draws from the same core source stays
+     * uniform.
      * @param {string} quill_name
      * @returns {string}
      */
@@ -111,8 +112,8 @@ export class Document {
         return ret !== 0;
     }
     /**
-     * Render a Diagnostic as the canonical pretty-printed text every binding
-     * shows (CLI, Python, MCP). Single source of truth so a Diagnostic looks
+     * Render a Diagnostic as the canonical pretty-printed text (core's
+     * `Diagnostic::fmt_pretty`). Single source of truth so a Diagnostic looks
      * identical no matter which consumer surfaces it.
      * @param {Diagnostic} diag
      * @returns {string}
@@ -134,10 +135,11 @@ export class Document {
         }
     }
     /**
-     * Authoring-format rules for the card-yaml markdown surface — the same
-     * text every binding (CLI, Python, MCP) shows so callers reading errors
-     * from one binding can use the rules from any other. Read once at
-     * startup and cache; the value never changes between calls.
+     * Authoring-format rules for the card-yaml markdown surface. The canonical
+     * text is core's (`quillmark_core::document::FORMAT_RULES`), re-exposed
+     * here for JS consumers so it matches any other surface that draws from the
+     * same source. Read once at startup and cache; the value never changes
+     * between calls.
      * @returns {string}
      */
     static formatRules() {
@@ -332,11 +334,11 @@ export class Document {
         }
     }
     /**
-     * The canonical `$quill` reference grammar as author-facing text. Single
-     * source of truth (CLI, Python, MCP): drive schema `describe` and
-     * validation messages from this instead of re-stating the rule — it
-     * matches the `hint` on `parse::invalid_quill_reference`. Cache it; the
-     * value never changes.
+     * The canonical `$quill` reference grammar as author-facing text. Core is
+     * the single source of truth: drive schema `describe` and validation
+     * messages from this instead of re-stating the rule — it matches the
+     * `hint` on `parse::invalid_quill_reference`. Cache it; the value never
+     * changes.
      * @returns {string}
      */
     static quillRefHint() {
@@ -515,6 +517,30 @@ export class Document {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
+    /**
+     * Remove `cardKind` from the main card's `$seed` map, returning its
+     * overlay or `undefined`; drops `$seed` entirely once empty. Sibling
+     * kinds survive.
+     * @param {string} card_kind
+     * @returns {any}
+     */
+    removeSeedNamespace(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.document_removeSeedNamespace(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);
+        }
+    }
     /**
      * @param {string} body
      */
@@ -658,7 +684,7 @@ export class Document {
         }
     }
     /**
-     * Update a payload field on the main card. Clears any existing `!fill` marker.
+     * Update a payload field on the main card. Clears any existing `!must_fill` marker.
      *
      * Throws if `name` does not match `[a-z_][a-z0-9_]*`.
      * @param {string} name
@@ -680,7 +706,7 @@ export class Document {
         }
     }
     /**
-     * Update a payload field on the main card and mark it as `!fill`.
+     * Update a payload field on the main card and mark it as `!must_fill`.
      * Throws on invalid name (see [`setField`](Document::set_field)).
      * @param {string} name
      * @param {any} value
@@ -719,6 +745,29 @@ export class Document {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
+    /**
+     * Merge a card-kind's seed `overlay` into the main card's `$seed` map
+     * under `cardKind`, preserving sibling kinds. Sets the starting values
+     * new cards of that kind spawn with. Throws if `overlay` cannot be
+     * serialized or nests too deep.
+     * @param {string} card_kind
+     * @param {any} overlay
+     */
+    setSeedNamespace(card_kind, overlay) {
+        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.document_setSeedNamespace(retptr, this.__wbg_ptr, ptr0, len0, addHeapObject(overlay));
+            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);
+        }
+    }
     /**
      * Serialize this document to a versioned storage DTO string.
      *
@@ -976,19 +1025,25 @@ export class Quill {
     }
     /**
      * 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`.
+     * layering an optional per-kind seed `overlay` over the schema-example
+     * base (`overlay › example › absent`). Returns `undefined` if `cardKind`
+     * is not declared in this quill's schema, else a `Card` that feeds
+     * straight into `Document.pushCard` / `insertCard`.
+     *
+     * Pass `document.main.seed?.[cardKind]` as `overlay` so a card added to a
+     * template-derived document inherits its curated starting values; omit it
+     * (or pass `undefined` / `null`) for the bare schema seed. `overlay` is a
+     * plain object — this reads the document, it does not mutate it.
      * @param {string} card_kind
+     * @param {Record<string, unknown> | undefined} overlay
      * @returns {Card | undefined}
      */
-    seedCard(card_kind) {
+    seedCard(card_kind, overlay) {
         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_seedCard(retptr, this.__wbg_ptr, ptr0, len0);
+            wasm.quill_seedCard(retptr, this.__wbg_ptr, ptr0, len0, addHeapObject(overlay));
             var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
             var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
             var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);

package/core/wasm_bg.wasm.d.ts

@@ -27,6 +27,7 @@ export const document_removeCardField: (a: number, b: number, c: number, d: numb
 export const document_removeExt: (a: number, b: number) => void;
 export const document_removeExtNamespace: (a: number, b: number, c: number, d: number) => void;
 export const document_removeField: (a: number, b: number, c: number, d: number) => void;
+export const document_removeSeedNamespace: (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;
@@ -37,6 +38,7 @@ export const document_setExtNamespace: (a: number, b: number, c: number, d: numb
 export const document_setField: (a: number, b: number, c: number, d: number, e: number) => void;
 export const document_setFill: (a: number, b: number, c: number, d: number, e: number) => void;
 export const document_setQuillRef: (a: number, b: number, c: number, d: number) => void;
+export const document_setSeedNamespace: (a: number, b: number, c: number, d: number, e: number) => void;
 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;
@@ -49,7 +51,7 @@ export const quill_blueprint: (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_schema: (a: number, b: number) => void;
-export const quill_seedCard: (a: number, b: number, c: number, d: number) => void;
+export const quill_seedCard: (a: number, b: number, c: number, d: number, e: number) => void;
 export const quill_seedDocument: (a: number) => number;
 export const quill_seedMain: (a: number, b: number) => void;
 export const quill_toTree: (a: number) => number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quillmark/wasm",
-  "version": "0.91.0",
+  "version": "0.92.0",
   "description": "WebAssembly bindings for quillmark",
   "type": "module",
   "license": "MIT OR Apache-2.0",