@quillmark/wasm 0.58.2-rc.5 → 0.59.0-rc.1

package/bundler/wasm.d.ts

@@ -1,5 +1,18 @@
 /* tslint:disable */
 /* eslint-disable */
+
+/**
+ * Input shape for `Document.pushCard` and `Document.insertCard`.
+ *
+ * Only `tag` is required. `fields` defaults to `{}`, `body` to `""`.
+ */
+export interface CardInput {
+    tag: string;
+    fields?: Record<string, unknown>;
+    body?: string;
+}
+
+
 export interface Artifact {
     format: OutputFormat;
     bytes: Uint8Array;
@@ -7,8 +20,10 @@ export interface Artifact {
 }
 
 export interface Card {
+    sentinel: string;
     tag: string;
-    fields: Record<string, unknown>;
+    frontmatter: Record<string, unknown>;
+    frontmatterItems: FrontmatterItem[];
     body: string;
 }
 
@@ -40,6 +55,8 @@ export interface RenderResult {
     renderTimeMs: number;
 }
 
+export type FrontmatterItem = { kind: "field"; key: string; value: unknown; fill?: boolean } | { kind: "comment"; text: string };
+
 export type OutputFormat = "pdf" | "svg" | "txt" | "png";
 
 export type Severity = "error" | "warning" | "note";
@@ -62,6 +79,15 @@ export class Document {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Return a fresh `Document` handle with the same parse state.
+     *
+     * Mutations on the returned handle do not affect the original and
+     * vice versa. Parse-time warnings are snapshotted alongside the
+     * document — they describe the original parse, not the edit
+     * history of either handle.
+     */
+    clone(): Document;
     /**
      * Parse markdown into a typed Document.
      *
@@ -76,7 +102,7 @@ export class Document {
      *
      * Mutators never modify `warnings`.
      */
-    insertCard(index: number, card: any): void;
+    insertCard(index: number, card: CardInput): void;
     /**
      * Move the card at `from` to position `to`.
      *
@@ -96,27 +122,30 @@ export class Document {
      *
      * Mutators never modify `warnings`.
      */
-    pushCard(card: any): void;
+    pushCard(card: CardInput): void;
     /**
      * Remove the card at `index` and return it, or `undefined` if out of range.
      *
      * Mutators never modify `warnings`.
      */
-    removeCard(index: number): any;
+    removeCard(index: number): Card | undefined;
     /**
-     * Remove a frontmatter field, returning the removed value or `undefined`.
+     * Remove a frontmatter field on the main card, returning the removed value or `undefined`.
      *
      * Mutators never modify `warnings`.
      */
     removeField(name: string): any;
     /**
-     * Replace the global Markdown body.
+     * Replace the main card's body (the global Markdown body).
      *
      * Mutators never modify `warnings`.
      */
     replaceBody(body: string): void;
     /**
-     * Set a frontmatter field.
+     * Update a frontmatter field on the main card.
+     *
+     * Convenience method: equivalent to `doc.mainMut().setField(name, value)`.
+     * Clears any existing `!fill` marker on the field.
      *
      * Throws an `Error` whose message includes the `EditError` variant name and
      * details if `name` is reserved (`BODY`, `CARDS`, `QUILL`, `CARD`) or does
@@ -125,6 +154,16 @@ export class Document {
      * Mutators never modify `warnings`.
      */
     setField(name: string, value: any): void;
+    /**
+     * Update a frontmatter field on the main card AND mark it as `!fill`.
+     *
+     * Convenience method: equivalent to `doc.mainMut().setFill(name, value)`.
+     *
+     * Throws on invalid name (see [`setField`](Document::set_field)).
+     *
+     * Mutators never modify `warnings`.
+     */
+    setFill(name: string, value: any): void;
     /**
      * Replace the QUILL reference string.
      *
@@ -161,30 +200,27 @@ export class Document {
      */
     updateCardField(index: number, name: string, value: any): void;
     /**
-     * Global Markdown body between frontmatter and the first card.
-     *
-     * Trailing newlines are stripped — those are structural separators in
-     * the Markdown wire format, not content the consumer wrote.
-     *
-     * Empty string when no body is present.
-     */
-    readonly body: string;
-    /**
-     * Ordered list of card blocks as JS objects with `tag`, `fields`, and `body`.
+     * Ordered list of composable card blocks as typed `Card` objects.
      */
-    readonly cards: any;
+    readonly cards: Card[];
     /**
-     * Typed YAML frontmatter fields as a JS object (no QUILL, BODY, or CARDS keys).
+     * The document's main (entry) card.
+     *
+     * Carries the QUILL sentinel, the document-level frontmatter, and the
+     * global body. Frontmatter/body reads and mutations go through this
+     * handle — there are no document-level shortcuts after the rework.
+     *
+     * Allocates and serializes on each call — cache locally if read in a hot loop.
      */
-    readonly frontmatter: any;
+    readonly main: Card;
     /**
      * The QUILL reference string (e.g. `"usaf_memo@0.1"`).
      */
     readonly quillRef: string;
     /**
-     * Non-fatal parse-time warnings as a JS array of Diagnostic objects.
+     * Non-fatal parse-time warnings as an array of typed `Diagnostic` objects.
      */
-    readonly warnings: any;
+    readonly warnings: Diagnostic[];
 }
 
 /**
@@ -227,6 +263,21 @@ export class Quill {
      * The resolved backend identifier (e.g. `"typst"`).
      */
     readonly backendId: string;
+    /**
+     * Read-only snapshot of the loaded `Quill.yaml`.
+     *
+     * Returns a plain JS object with `name`, `backend`, `description`,
+     * `version`, `author`, optional `example` (content of the example
+     * markdown, when the quill ships one), `supportedFormats` (backend's
+     * output formats as lowercase strings), `schema` (the raw main-card
+     * field schema as parsed from YAML — consumers that need validation
+     * run their own validator against this), and any additional
+     * unstructured keys declared inside the `quill:` section.
+     *
+     * Equivalent by value for the lifetime of the handle; the quill is
+     * immutable once constructed.
+     */
+    readonly metadata: any;
 }
 
 /**
@@ -242,9 +293,12 @@ export class Quillmark {
     /**
      * Load a quill from a file tree and attach the appropriate backend.
      *
-     * The tree must be a `Map<string, Uint8Array>`.
+     * Accepts either a `Map<string, Uint8Array>` or a plain object
+     * (`Record<string, Uint8Array>`). Plain objects are walked via
+     * `Object.entries` at the boundary; the Rust side sees a single
+     * canonical shape.
      */
-    quill(tree: any): Quill;
+    quill(tree: Map<string, Uint8Array>): Quill;
 }
 
 export class RenderSession {

package/bundler/wasm_bg.js

@@ -30,38 +30,26 @@ export class Document {
         wasm.__wbg_document_free(ptr, 0);
     }
     /**
-     * Global Markdown body between frontmatter and the first card.
-     *
-     * Trailing newlines are stripped — those are structural separators in
-     * the Markdown wire format, not content the consumer wrote.
-     *
-     * Empty string when no body is present.
-     * @returns {string}
-     */
-    get body() {
-        let deferred1_0;
-        let deferred1_1;
-        try {
-            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-            wasm.document_body(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);
-        }
-    }
-    /**
-     * Ordered list of card blocks as JS objects with `tag`, `fields`, and `body`.
-     * @returns {any}
+     * Ordered list of composable card blocks as typed `Card` objects.
+     * @returns {Card[]}
      */
     get cards() {
         const ret = wasm.document_cards(this.__wbg_ptr);
         return takeObject(ret);
     }
+    /**
+     * Return a fresh `Document` handle with the same parse state.
+     *
+     * Mutations on the returned handle do not affect the original and
+     * vice versa. Parse-time warnings are snapshotted alongside the
+     * document — they describe the original parse, not the edit
+     * history of either handle.
+     * @returns {Document}
+     */
+    clone() {
+        const ret = wasm.document_clone(this.__wbg_ptr);
+        return Document.__wrap(ret);
+    }
     /**
      * Parse markdown into a typed Document.
      *
@@ -87,14 +75,6 @@ export class Document {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
-    /**
-     * Typed YAML frontmatter fields as a JS object (no QUILL, BODY, or CARDS keys).
-     * @returns {any}
-     */
-    get frontmatter() {
-        const ret = wasm.document_frontmatter(this.__wbg_ptr);
-        return takeObject(ret);
-    }
     /**
      * Insert a card at the given index.
      *
@@ -102,7 +82,7 @@ export class Document {
      *
      * Mutators never modify `warnings`.
      * @param {number} index
-     * @param {any} card
+     * @param {CardInput} card
      */
     insertCard(index, card) {
         try {
@@ -117,6 +97,20 @@ export class Document {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
+    /**
+     * The document's main (entry) card.
+     *
+     * Carries the QUILL sentinel, the document-level frontmatter, and the
+     * global body. Frontmatter/body reads and mutations go through this
+     * handle — there are no document-level shortcuts after the rework.
+     *
+     * Allocates and serializes on each call — cache locally if read in a hot loop.
+     * @returns {Card}
+     */
+    get main() {
+        const ret = wasm.document_main(this.__wbg_ptr);
+        return takeObject(ret);
+    }
     /**
      * Move the card at `from` to position `to`.
      *
@@ -149,7 +143,7 @@ export class Document {
      * Throws an `Error` if `card.tag` is not a valid tag name.
      *
      * Mutators never modify `warnings`.
-     * @param {any} card
+     * @param {CardInput} card
      */
     pushCard(card) {
         try {
@@ -189,14 +183,14 @@ export class Document {
      *
      * Mutators never modify `warnings`.
      * @param {number} index
-     * @returns {any}
+     * @returns {Card | undefined}
      */
     removeCard(index) {
         const ret = wasm.document_removeCard(this.__wbg_ptr, index);
         return takeObject(ret);
     }
     /**
-     * Remove a frontmatter field, returning the removed value or `undefined`.
+     * Remove a frontmatter field on the main card, returning the removed value or `undefined`.
      *
      * Mutators never modify `warnings`.
      * @param {string} name
@@ -209,7 +203,7 @@ export class Document {
         return takeObject(ret);
     }
     /**
-     * Replace the global Markdown body.
+     * Replace the main card's body (the global Markdown body).
      *
      * Mutators never modify `warnings`.
      * @param {string} body
@@ -220,7 +214,10 @@ export class Document {
         wasm.document_replaceBody(this.__wbg_ptr, ptr0, len0);
     }
     /**
-     * Set a frontmatter field.
+     * Update a frontmatter field on the main card.
+     *
+     * Convenience method: equivalent to `doc.mainMut().setField(name, value)`.
+     * Clears any existing `!fill` marker on the field.
      *
      * Throws an `Error` whose message includes the `EditError` variant name and
      * details if `name` is reserved (`BODY`, `CARDS`, `QUILL`, `CARD`) or does
@@ -245,6 +242,32 @@ export class Document {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
+    /**
+     * Update a frontmatter field on the main card AND mark it as `!fill`.
+     *
+     * Convenience method: equivalent to `doc.mainMut().setFill(name, value)`.
+     *
+     * Throws on invalid name (see [`setField`](Document::set_field)).
+     *
+     * Mutators never modify `warnings`.
+     * @param {string} name
+     * @param {any} value
+     */
+    setFill(name, value) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passStringToWasm0(name, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            wasm.document_setFill(retptr, this.__wbg_ptr, 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 QUILL reference string.
      *
@@ -345,8 +368,8 @@ export class Document {
         }
     }
     /**
-     * Non-fatal parse-time warnings as a JS array of Diagnostic objects.
-     * @returns {any}
+     * Non-fatal parse-time warnings as an array of typed `Diagnostic` objects.
+     * @returns {Diagnostic[]}
      */
     get warnings() {
         const ret = wasm.document_warnings(this.__wbg_ptr);
@@ -396,6 +419,25 @@ export class Quill {
             wasm.__wbindgen_export4(deferred1_0, deferred1_1, 1);
         }
     }
+    /**
+     * Read-only snapshot of the loaded `Quill.yaml`.
+     *
+     * Returns a plain JS object with `name`, `backend`, `description`,
+     * `version`, `author`, optional `example` (content of the example
+     * markdown, when the quill ships one), `supportedFormats` (backend's
+     * output formats as lowercase strings), `schema` (the raw main-card
+     * field schema as parsed from YAML — consumers that need validation
+     * run their own validator against this), and any additional
+     * unstructured keys declared inside the `quill:` section.
+     *
+     * Equivalent by value for the lifetime of the handle; the quill is
+     * immutable once constructed.
+     * @returns {any}
+     */
+    get metadata() {
+        const ret = wasm.quill_metadata(this.__wbg_ptr);
+        return takeObject(ret);
+    }
     /**
      * Open an iterative render session for page-selective rendering.
      * @param {Document} doc
@@ -506,8 +548,11 @@ export class Quillmark {
     /**
      * Load a quill from a file tree and attach the appropriate backend.
      *
-     * The tree must be a `Map<string, Uint8Array>`.
-     * @param {any} tree
+     * Accepts either a `Map<string, Uint8Array>` or a plain object
+     * (`Record<string, Uint8Array>`). Plain objects are walked via
+     * `Object.entries` at the boundary; the Rust side sees a single
+     * canonical shape.
+     * @param {Map<string, Uint8Array>} tree
      * @returns {Quill}
      */
     quill(tree) {
@@ -635,6 +680,10 @@ export function __wbg___wbindgen_is_function_3baa9db1a987f47d(arg0) {
     const ret = typeof(getObject(arg0)) === 'function';
     return ret;
 }
+export function __wbg___wbindgen_is_null_52ff4ec04186736f(arg0) {
+    const ret = getObject(arg0) === null;
+    return ret;
+}
 export function __wbg___wbindgen_is_object_63322ec0cd6ea4ef(arg0) {
     const val = getObject(arg0);
     const ret = typeof(val) === 'object' && val !== null;

package/bundler/wasm_bg.wasm.d.ts

@@ -5,11 +5,11 @@ export const __wbg_document_free: (a: number, b: number) => void;
 export const __wbg_quill_free: (a: number, b: number) => void;
 export const __wbg_quillmark_free: (a: number, b: number) => void;
 export const __wbg_rendersession_free: (a: number, b: number) => void;
-export const document_body: (a: number, b: number) => void;
 export const document_cards: (a: number) => number;
+export const document_clone: (a: number) => number;
 export const document_fromMarkdown: (a: number, b: number, c: number) => void;
-export const document_frontmatter: (a: number) => number;
 export const document_insertCard: (a: number, b: number, c: number, d: number) => void;
+export const document_main: (a: number) => number;
 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;
@@ -17,6 +17,7 @@ export const document_removeCard: (a: number, b: number) => number;
 export const document_removeField: (a: number, b: number, c: number) => number;
 export const document_replaceBody: (a: number, b: number, c: number) => void;
 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_toMarkdown: (a: number, b: number) => void;
 export const document_updateCardBody: (a: number, b: number, c: number, d: number, e: number) => void;
@@ -24,6 +25,7 @@ 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_metadata: (a: number) => number;
 export const quill_open: (a: number, b: number, c: number) => void;
 export const quill_projectForm: (a: number, b: number, c: number) => void;
 export const quill_render: (a: number, b: number, c: number, d: number) => void;

package/node-esm/wasm.d.ts

@@ -1,5 +1,18 @@
 /* tslint:disable */
 /* eslint-disable */
+
+/**
+ * Input shape for `Document.pushCard` and `Document.insertCard`.
+ *
+ * Only `tag` is required. `fields` defaults to `{}`, `body` to `""`.
+ */
+export interface CardInput {
+    tag: string;
+    fields?: Record<string, unknown>;
+    body?: string;
+}
+
+
 export interface Artifact {
     format: OutputFormat;
     bytes: Uint8Array;
@@ -7,8 +20,10 @@ export interface Artifact {
 }
 
 export interface Card {
+    sentinel: string;
     tag: string;
-    fields: Record<string, unknown>;
+    frontmatter: Record<string, unknown>;
+    frontmatterItems: FrontmatterItem[];
     body: string;
 }
 
@@ -40,6 +55,8 @@ export interface RenderResult {
     renderTimeMs: number;
 }
 
+export type FrontmatterItem = { kind: "field"; key: string; value: unknown; fill?: boolean } | { kind: "comment"; text: string };
+
 export type OutputFormat = "pdf" | "svg" | "txt" | "png";
 
 export type Severity = "error" | "warning" | "note";
@@ -62,6 +79,15 @@ export class Document {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Return a fresh `Document` handle with the same parse state.
+     *
+     * Mutations on the returned handle do not affect the original and
+     * vice versa. Parse-time warnings are snapshotted alongside the
+     * document — they describe the original parse, not the edit
+     * history of either handle.
+     */
+    clone(): Document;
     /**
      * Parse markdown into a typed Document.
      *
@@ -76,7 +102,7 @@ export class Document {
      *
      * Mutators never modify `warnings`.
      */
-    insertCard(index: number, card: any): void;
+    insertCard(index: number, card: CardInput): void;
     /**
      * Move the card at `from` to position `to`.
      *
@@ -96,27 +122,30 @@ export class Document {
      *
      * Mutators never modify `warnings`.
      */
-    pushCard(card: any): void;
+    pushCard(card: CardInput): void;
     /**
      * Remove the card at `index` and return it, or `undefined` if out of range.
      *
      * Mutators never modify `warnings`.
      */
-    removeCard(index: number): any;
+    removeCard(index: number): Card | undefined;
     /**
-     * Remove a frontmatter field, returning the removed value or `undefined`.
+     * Remove a frontmatter field on the main card, returning the removed value or `undefined`.
      *
      * Mutators never modify `warnings`.
      */
     removeField(name: string): any;
     /**
-     * Replace the global Markdown body.
+     * Replace the main card's body (the global Markdown body).
      *
      * Mutators never modify `warnings`.
      */
     replaceBody(body: string): void;
     /**
-     * Set a frontmatter field.
+     * Update a frontmatter field on the main card.
+     *
+     * Convenience method: equivalent to `doc.mainMut().setField(name, value)`.
+     * Clears any existing `!fill` marker on the field.
      *
      * Throws an `Error` whose message includes the `EditError` variant name and
      * details if `name` is reserved (`BODY`, `CARDS`, `QUILL`, `CARD`) or does
@@ -125,6 +154,16 @@ export class Document {
      * Mutators never modify `warnings`.
      */
     setField(name: string, value: any): void;
+    /**
+     * Update a frontmatter field on the main card AND mark it as `!fill`.
+     *
+     * Convenience method: equivalent to `doc.mainMut().setFill(name, value)`.
+     *
+     * Throws on invalid name (see [`setField`](Document::set_field)).
+     *
+     * Mutators never modify `warnings`.
+     */
+    setFill(name: string, value: any): void;
     /**
      * Replace the QUILL reference string.
      *
@@ -161,30 +200,27 @@ export class Document {
      */
     updateCardField(index: number, name: string, value: any): void;
     /**
-     * Global Markdown body between frontmatter and the first card.
-     *
-     * Trailing newlines are stripped — those are structural separators in
-     * the Markdown wire format, not content the consumer wrote.
-     *
-     * Empty string when no body is present.
-     */
-    readonly body: string;
-    /**
-     * Ordered list of card blocks as JS objects with `tag`, `fields`, and `body`.
+     * Ordered list of composable card blocks as typed `Card` objects.
      */
-    readonly cards: any;
+    readonly cards: Card[];
     /**
-     * Typed YAML frontmatter fields as a JS object (no QUILL, BODY, or CARDS keys).
+     * The document's main (entry) card.
+     *
+     * Carries the QUILL sentinel, the document-level frontmatter, and the
+     * global body. Frontmatter/body reads and mutations go through this
+     * handle — there are no document-level shortcuts after the rework.
+     *
+     * Allocates and serializes on each call — cache locally if read in a hot loop.
      */
-    readonly frontmatter: any;
+    readonly main: Card;
     /**
      * The QUILL reference string (e.g. `"usaf_memo@0.1"`).
      */
     readonly quillRef: string;
     /**
-     * Non-fatal parse-time warnings as a JS array of Diagnostic objects.
+     * Non-fatal parse-time warnings as an array of typed `Diagnostic` objects.
      */
-    readonly warnings: any;
+    readonly warnings: Diagnostic[];
 }
 
 /**
@@ -227,6 +263,21 @@ export class Quill {
      * The resolved backend identifier (e.g. `"typst"`).
      */
     readonly backendId: string;
+    /**
+     * Read-only snapshot of the loaded `Quill.yaml`.
+     *
+     * Returns a plain JS object with `name`, `backend`, `description`,
+     * `version`, `author`, optional `example` (content of the example
+     * markdown, when the quill ships one), `supportedFormats` (backend's
+     * output formats as lowercase strings), `schema` (the raw main-card
+     * field schema as parsed from YAML — consumers that need validation
+     * run their own validator against this), and any additional
+     * unstructured keys declared inside the `quill:` section.
+     *
+     * Equivalent by value for the lifetime of the handle; the quill is
+     * immutable once constructed.
+     */
+    readonly metadata: any;
 }
 
 /**
@@ -242,9 +293,12 @@ export class Quillmark {
     /**
      * Load a quill from a file tree and attach the appropriate backend.
      *
-     * The tree must be a `Map<string, Uint8Array>`.
+     * Accepts either a `Map<string, Uint8Array>` or a plain object
+     * (`Record<string, Uint8Array>`). Plain objects are walked via
+     * `Object.entries` at the boundary; the Rust side sees a single
+     * canonical shape.
      */
-    quill(tree: any): Quill;
+    quill(tree: Map<string, Uint8Array>): Quill;
 }
 
 export class RenderSession {

package/node-esm/wasm.js

@@ -34,38 +34,26 @@ export class Document {
         wasm.__wbg_document_free(ptr, 0);
     }
     /**
-     * Global Markdown body between frontmatter and the first card.
-     *
-     * Trailing newlines are stripped — those are structural separators in
-     * the Markdown wire format, not content the consumer wrote.
-     *
-     * Empty string when no body is present.
-     * @returns {string}
-     */
-    get body() {
-        let deferred1_0;
-        let deferred1_1;
-        try {
-            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-            wasm.document_body(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);
-        }
-    }
-    /**
-     * Ordered list of card blocks as JS objects with `tag`, `fields`, and `body`.
-     * @returns {any}
+     * Ordered list of composable card blocks as typed `Card` objects.
+     * @returns {Card[]}
      */
     get cards() {
         const ret = wasm.document_cards(this.__wbg_ptr);
         return takeObject(ret);
     }
+    /**
+     * Return a fresh `Document` handle with the same parse state.
+     *
+     * Mutations on the returned handle do not affect the original and
+     * vice versa. Parse-time warnings are snapshotted alongside the
+     * document — they describe the original parse, not the edit
+     * history of either handle.
+     * @returns {Document}
+     */
+    clone() {
+        const ret = wasm.document_clone(this.__wbg_ptr);
+        return Document.__wrap(ret);
+    }
     /**
      * Parse markdown into a typed Document.
      *
@@ -91,14 +79,6 @@ export class Document {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
-    /**
-     * Typed YAML frontmatter fields as a JS object (no QUILL, BODY, or CARDS keys).
-     * @returns {any}
-     */
-    get frontmatter() {
-        const ret = wasm.document_frontmatter(this.__wbg_ptr);
-        return takeObject(ret);
-    }
     /**
      * Insert a card at the given index.
      *
@@ -106,7 +86,7 @@ export class Document {
      *
      * Mutators never modify `warnings`.
      * @param {number} index
-     * @param {any} card
+     * @param {CardInput} card
      */
     insertCard(index, card) {
         try {
@@ -121,6 +101,20 @@ export class Document {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
+    /**
+     * The document's main (entry) card.
+     *
+     * Carries the QUILL sentinel, the document-level frontmatter, and the
+     * global body. Frontmatter/body reads and mutations go through this
+     * handle — there are no document-level shortcuts after the rework.
+     *
+     * Allocates and serializes on each call — cache locally if read in a hot loop.
+     * @returns {Card}
+     */
+    get main() {
+        const ret = wasm.document_main(this.__wbg_ptr);
+        return takeObject(ret);
+    }
     /**
      * Move the card at `from` to position `to`.
      *
@@ -153,7 +147,7 @@ export class Document {
      * Throws an `Error` if `card.tag` is not a valid tag name.
      *
      * Mutators never modify `warnings`.
-     * @param {any} card
+     * @param {CardInput} card
      */
     pushCard(card) {
         try {
@@ -193,14 +187,14 @@ export class Document {
      *
      * Mutators never modify `warnings`.
      * @param {number} index
-     * @returns {any}
+     * @returns {Card | undefined}
      */
     removeCard(index) {
         const ret = wasm.document_removeCard(this.__wbg_ptr, index);
         return takeObject(ret);
     }
     /**
-     * Remove a frontmatter field, returning the removed value or `undefined`.
+     * Remove a frontmatter field on the main card, returning the removed value or `undefined`.
      *
      * Mutators never modify `warnings`.
      * @param {string} name
@@ -213,7 +207,7 @@ export class Document {
         return takeObject(ret);
     }
     /**
-     * Replace the global Markdown body.
+     * Replace the main card's body (the global Markdown body).
      *
      * Mutators never modify `warnings`.
      * @param {string} body
@@ -224,7 +218,10 @@ export class Document {
         wasm.document_replaceBody(this.__wbg_ptr, ptr0, len0);
     }
     /**
-     * Set a frontmatter field.
+     * Update a frontmatter field on the main card.
+     *
+     * Convenience method: equivalent to `doc.mainMut().setField(name, value)`.
+     * Clears any existing `!fill` marker on the field.
      *
      * Throws an `Error` whose message includes the `EditError` variant name and
      * details if `name` is reserved (`BODY`, `CARDS`, `QUILL`, `CARD`) or does
@@ -249,6 +246,32 @@ export class Document {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
+    /**
+     * Update a frontmatter field on the main card AND mark it as `!fill`.
+     *
+     * Convenience method: equivalent to `doc.mainMut().setFill(name, value)`.
+     *
+     * Throws on invalid name (see [`setField`](Document::set_field)).
+     *
+     * Mutators never modify `warnings`.
+     * @param {string} name
+     * @param {any} value
+     */
+    setFill(name, value) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passStringToWasm0(name, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            wasm.document_setFill(retptr, this.__wbg_ptr, 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 QUILL reference string.
      *
@@ -349,8 +372,8 @@ export class Document {
         }
     }
     /**
-     * Non-fatal parse-time warnings as a JS array of Diagnostic objects.
-     * @returns {any}
+     * Non-fatal parse-time warnings as an array of typed `Diagnostic` objects.
+     * @returns {Diagnostic[]}
      */
     get warnings() {
         const ret = wasm.document_warnings(this.__wbg_ptr);
@@ -400,6 +423,25 @@ export class Quill {
             wasm.__wbindgen_export4(deferred1_0, deferred1_1, 1);
         }
     }
+    /**
+     * Read-only snapshot of the loaded `Quill.yaml`.
+     *
+     * Returns a plain JS object with `name`, `backend`, `description`,
+     * `version`, `author`, optional `example` (content of the example
+     * markdown, when the quill ships one), `supportedFormats` (backend's
+     * output formats as lowercase strings), `schema` (the raw main-card
+     * field schema as parsed from YAML — consumers that need validation
+     * run their own validator against this), and any additional
+     * unstructured keys declared inside the `quill:` section.
+     *
+     * Equivalent by value for the lifetime of the handle; the quill is
+     * immutable once constructed.
+     * @returns {any}
+     */
+    get metadata() {
+        const ret = wasm.quill_metadata(this.__wbg_ptr);
+        return takeObject(ret);
+    }
     /**
      * Open an iterative render session for page-selective rendering.
      * @param {Document} doc
@@ -510,8 +552,11 @@ export class Quillmark {
     /**
      * Load a quill from a file tree and attach the appropriate backend.
      *
-     * The tree must be a `Map<string, Uint8Array>`.
-     * @param {any} tree
+     * Accepts either a `Map<string, Uint8Array>` or a plain object
+     * (`Record<string, Uint8Array>`). Plain objects are walked via
+     * `Object.entries` at the boundary; the Rust side sees a single
+     * canonical shape.
+     * @param {Map<string, Uint8Array>} tree
      * @returns {Quill}
      */
     quill(tree) {
@@ -642,6 +687,10 @@ function __wbg_get_imports() {
             const ret = typeof(getObject(arg0)) === 'function';
             return ret;
         },
+        __wbg___wbindgen_is_null_52ff4ec04186736f: function(arg0) {
+            const ret = getObject(arg0) === null;
+            return ret;
+        },
         __wbg___wbindgen_is_object_63322ec0cd6ea4ef: function(arg0) {
             const val = getObject(arg0);
             const ret = typeof(val) === 'object' && val !== null;

package/node-esm/wasm_bg.wasm.d.ts

@@ -5,11 +5,11 @@ export const __wbg_document_free: (a: number, b: number) => void;
 export const __wbg_quill_free: (a: number, b: number) => void;
 export const __wbg_quillmark_free: (a: number, b: number) => void;
 export const __wbg_rendersession_free: (a: number, b: number) => void;
-export const document_body: (a: number, b: number) => void;
 export const document_cards: (a: number) => number;
+export const document_clone: (a: number) => number;
 export const document_fromMarkdown: (a: number, b: number, c: number) => void;
-export const document_frontmatter: (a: number) => number;
 export const document_insertCard: (a: number, b: number, c: number, d: number) => void;
+export const document_main: (a: number) => number;
 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;
@@ -17,6 +17,7 @@ export const document_removeCard: (a: number, b: number) => number;
 export const document_removeField: (a: number, b: number, c: number) => number;
 export const document_replaceBody: (a: number, b: number, c: number) => void;
 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_toMarkdown: (a: number, b: number) => void;
 export const document_updateCardBody: (a: number, b: number, c: number, d: number, e: number) => void;
@@ -24,6 +25,7 @@ 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_metadata: (a: number) => number;
 export const quill_open: (a: number, b: number, c: number) => void;
 export const quill_projectForm: (a: number, b: number, c: number) => void;
 export const quill_render: (a: number, b: number, c: number, d: number) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quillmark/wasm",
-  "version": "0.58.2-rc.5",
+  "version": "0.59.0-rc.1",
   "description": "WebAssembly bindings for quillmark",
   "type": "module",
   "license": "MIT OR Apache-2.0",