@quillmark/wasm 0.65.1 → 0.66.1

package/README.md

@@ -11,9 +11,12 @@ Use Quillmark in browsers/Node.js with explicit in-memory trees (`Map<string, Ui
 ## Build
 
 ```bash
-wasm-pack build --target bundler --scope quillmark
+bash scripts/build-wasm.sh
 ```
 
+The script builds for `bundler` and `experimental-nodejs-module` targets with
+`--weak-refs` enabled (see [Lifecycle](#lifecycle)).
+
 ## Test
 
 ```bash
@@ -51,11 +54,30 @@ Create engine.
 Build + validate + attach backend. Returns a render-ready `Quill`.
 
 ### `Document.fromMarkdown(markdown)`
-Parse markdown to parsed document.
+Parse markdown to a parsed document. Throws a JS `Error` (with `.diagnostics`
+attached, see [Errors](#errors)) on any parse failure, including missing
+`QUILL`, malformed YAML, and inputs over the 10 MB `parse::input_too_large`
+limit.
 
 ### `doc.toMarkdown()`
 Emit canonical Quillmark Markdown. Type-fidelity round-trip safe:
-`Document.fromMarkdown(doc.toMarkdown())` returns a document equal to `doc`.
+`Document.fromMarkdown(doc.toMarkdown())` returns a document equal to `doc`
+under [`doc.equals`](#docequalsother). The output is **not** guaranteed
+byte-equal to the original source — YAML quoting, key ordering, and
+whitespace are normalised. Use `equals` (not string comparison) to test
+semantic equality.
+
+### `doc.equals(other)`
+Structural equality between two `Document` handles. Compares `main` and
+`cards` by value; parse-time `warnings` are intentionally excluded.
+
+Use this to debounce upstream prop updates: keep the last parsed `Document`
+and compare instead of re-parsing on every keystroke.
+
+### `doc.cardCount`
+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.render(parsed, opts?)`
 Render with a pre-parsed `Document`.
@@ -65,15 +87,36 @@ Open once, render all or selected pages (`opts.pages`).
 
 ### Errors
 
-Every method that can fail throws a JS `Error` with a flat shape:
+Every method that can fail throws a JS `Error` with `.diagnostics` attached:
 
 ```ts
 { message: string, diagnostics: Diagnostic[] }
 ```
 
 `diagnostics` is always non-empty — length 1 for most failures, length N for
-backend compilation errors. Read `err.diagnostics[0]` for the primary
-diagnostic; iterate the array for compilation failures.
+backend compilation errors. `message` is derived from `diagnostics`
+(`diagnostics[0].message` for single-diagnostic errors; an aggregate
+`"<N> error(s): <first.message>"` summary for compilation failures).
+
+Read `err.diagnostics[0]` for the primary diagnostic; iterate the array for
+compilation failures. The same shape applies to every throw site:
+
+- `Document.fromMarkdown` — parse errors (missing `QUILL`, YAML errors,
+  `parse::input_too_large` for inputs > 10 MB).
+- `Document` mutators (`setField`, `updateCardField`, etc.) — `EditError`
+  variants (`ReservedName`, `InvalidFieldName`, `InvalidTagName`,
+  `IndexOutOfRange`) appear in `diagnostics[0].message` with the
+  `[EditError::<Variant>]` prefix.
+- `quill.render` / `session.render` — backend compilation failures and
+  validation errors.
+
+### Lifecycle
+
+The wasm bindings are built with `--weak-refs`, so dropped `Document`,
+`Quill`, and `RenderSession` handles are reclaimed by `FinalizationRegistry`
+without manual `.free()` discipline. `.free()` is still emitted as an eager
+teardown hook for callers that want deterministic release. Requires
+Node 14.6+ / current evergreen browsers (all supported targets).
 
 ## Notes
 

package/bundler/wasm.d.ts

@@ -88,6 +88,17 @@ export class Document {
      * history of either handle.
      */
     clone(): Document;
+    /**
+     * Structural equality against another `Document`.
+     *
+     * Compares `main` and `cards` by value (matching core's [`PartialEq`]).
+     * Parse-time `warnings` are intentionally excluded — they describe the
+     * source text, not the document's content.
+     *
+     * Use this to debounce upstream prop updates: keep the last parsed
+     * `Document` and compare instead of re-parsing on every keystroke.
+     */
+    equals(other: Document): boolean;
     /**
      * Parse markdown into a typed Document.
      *
@@ -228,6 +239,13 @@ export class Document {
      * Mutators never modify `warnings`.
      */
     updateCardField(index: number, name: string, value: any): void;
+    /**
+     * Number of composable cards (excludes the main card).
+     *
+     * O(1). Use this to validate indices before calling card mutators
+     * instead of allocating the full `cards` array.
+     */
+    readonly cardCount: number;
     /**
      * Ordered list of composable card blocks as typed `Card` objects.
      */
@@ -321,8 +339,11 @@ export class Quill {
      *   optional `example`. `main` and each card under `card_types` share
      *   the same shape: `fields` (map keyed by field name), optional
      *   `title`, `description`, `ui`.
-     * - `backend`, `version`, `author` — quill identity declared in
-     *   `Quill.yaml`'s `quill:` section.
+     * - `backend`, `version`, `author`, `description` — quill identity
+     *   declared in `Quill.yaml`'s `quill:` section. `description` describes
+     *   the quill itself; if the author also declared `main.description` (the
+     *   schema description of the entry-point card), it lives at
+     *   `schema.main.description` and is independent.
      * - `supportedFormats` — output formats the backend produces, as
      *   lowercase strings.
      * - Any additional unstructured keys declared under `quill:`.

package/bundler/wasm_bg.js

@@ -29,6 +29,17 @@ export class Document {
         const ptr = this.__destroy_into_raw();
         wasm.__wbg_document_free(ptr, 0);
     }
+    /**
+     * Number of composable cards (excludes the main card).
+     *
+     * O(1). Use this to validate indices before calling card mutators
+     * instead of allocating the full `cards` array.
+     * @returns {number}
+     */
+    get cardCount() {
+        const ret = wasm.document_cardCount(this.__wbg_ptr);
+        return ret >>> 0;
+    }
     /**
      * Ordered list of composable card blocks as typed `Card` objects.
      * @returns {Card[]}
@@ -50,6 +61,23 @@ export class Document {
         const ret = wasm.document_clone(this.__wbg_ptr);
         return Document.__wrap(ret);
     }
+    /**
+     * Structural equality against another `Document`.
+     *
+     * Compares `main` and `cards` by value (matching core's [`PartialEq`]).
+     * Parse-time `warnings` are intentionally excluded — they describe the
+     * source text, not the document's content.
+     *
+     * Use this to debounce upstream prop updates: keep the last parsed
+     * `Document` and compare instead of re-parsing on every keystroke.
+     * @param {Document} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        _assertClass(other, Document);
+        const ret = wasm.document_equals(this.__wbg_ptr, other.__wbg_ptr);
+        return ret !== 0;
+    }
     /**
      * Parse markdown into a typed Document.
      *
@@ -594,8 +622,11 @@ export class Quill {
      *   optional `example`. `main` and each card under `card_types` share
      *   the same shape: `fields` (map keyed by field name), optional
      *   `title`, `description`, `ui`.
-     * - `backend`, `version`, `author` — quill identity declared in
-     *   `Quill.yaml`'s `quill:` section.
+     * - `backend`, `version`, `author`, `description` — quill identity
+     *   declared in `Quill.yaml`'s `quill:` section. `description` describes
+     *   the quill itself; if the author also declared `main.description` (the
+     *   schema description of the entry-point card), it lives at
+     *   `schema.main.description` and is independent.
      * - `supportedFormats` — output formats the backend produces, as
      *   lowercase strings.
      * - Any additional unstructured keys declared under `quill:`.

package/bundler/wasm_bg.wasm.d.ts

@@ -5,8 +5,10 @@ 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_cardCount: (a: number) => number;
 export const document_cards: (a: number) => number;
 export const document_clone: (a: number) => number;
+export const document_equals: (a: number, b: number) => number;
 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;

package/node-esm/wasm.d.ts

@@ -88,6 +88,17 @@ export class Document {
      * history of either handle.
      */
     clone(): Document;
+    /**
+     * Structural equality against another `Document`.
+     *
+     * Compares `main` and `cards` by value (matching core's [`PartialEq`]).
+     * Parse-time `warnings` are intentionally excluded — they describe the
+     * source text, not the document's content.
+     *
+     * Use this to debounce upstream prop updates: keep the last parsed
+     * `Document` and compare instead of re-parsing on every keystroke.
+     */
+    equals(other: Document): boolean;
     /**
      * Parse markdown into a typed Document.
      *
@@ -228,6 +239,13 @@ export class Document {
      * Mutators never modify `warnings`.
      */
     updateCardField(index: number, name: string, value: any): void;
+    /**
+     * Number of composable cards (excludes the main card).
+     *
+     * O(1). Use this to validate indices before calling card mutators
+     * instead of allocating the full `cards` array.
+     */
+    readonly cardCount: number;
     /**
      * Ordered list of composable card blocks as typed `Card` objects.
      */
@@ -321,8 +339,11 @@ export class Quill {
      *   optional `example`. `main` and each card under `card_types` share
      *   the same shape: `fields` (map keyed by field name), optional
      *   `title`, `description`, `ui`.
-     * - `backend`, `version`, `author` — quill identity declared in
-     *   `Quill.yaml`'s `quill:` section.
+     * - `backend`, `version`, `author`, `description` — quill identity
+     *   declared in `Quill.yaml`'s `quill:` section. `description` describes
+     *   the quill itself; if the author also declared `main.description` (the
+     *   schema description of the entry-point card), it lives at
+     *   `schema.main.description` and is independent.
      * - `supportedFormats` — output formats the backend produces, as
      *   lowercase strings.
      * - Any additional unstructured keys declared under `quill:`.

package/node-esm/wasm.js

@@ -33,6 +33,17 @@ export class Document {
         const ptr = this.__destroy_into_raw();
         wasm.__wbg_document_free(ptr, 0);
     }
+    /**
+     * Number of composable cards (excludes the main card).
+     *
+     * O(1). Use this to validate indices before calling card mutators
+     * instead of allocating the full `cards` array.
+     * @returns {number}
+     */
+    get cardCount() {
+        const ret = wasm.document_cardCount(this.__wbg_ptr);
+        return ret >>> 0;
+    }
     /**
      * Ordered list of composable card blocks as typed `Card` objects.
      * @returns {Card[]}
@@ -54,6 +65,23 @@ export class Document {
         const ret = wasm.document_clone(this.__wbg_ptr);
         return Document.__wrap(ret);
     }
+    /**
+     * Structural equality against another `Document`.
+     *
+     * Compares `main` and `cards` by value (matching core's [`PartialEq`]).
+     * Parse-time `warnings` are intentionally excluded — they describe the
+     * source text, not the document's content.
+     *
+     * Use this to debounce upstream prop updates: keep the last parsed
+     * `Document` and compare instead of re-parsing on every keystroke.
+     * @param {Document} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        _assertClass(other, Document);
+        const ret = wasm.document_equals(this.__wbg_ptr, other.__wbg_ptr);
+        return ret !== 0;
+    }
     /**
      * Parse markdown into a typed Document.
      *
@@ -598,8 +626,11 @@ export class Quill {
      *   optional `example`. `main` and each card under `card_types` share
      *   the same shape: `fields` (map keyed by field name), optional
      *   `title`, `description`, `ui`.
-     * - `backend`, `version`, `author` — quill identity declared in
-     *   `Quill.yaml`'s `quill:` section.
+     * - `backend`, `version`, `author`, `description` — quill identity
+     *   declared in `Quill.yaml`'s `quill:` section. `description` describes
+     *   the quill itself; if the author also declared `main.description` (the
+     *   schema description of the entry-point card), it lives at
+     *   `schema.main.description` and is independent.
      * - `supportedFormats` — output formats the backend produces, as
      *   lowercase strings.
      * - Any additional unstructured keys declared under `quill:`.

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

@@ -5,8 +5,10 @@ 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_cardCount: (a: number) => number;
 export const document_cards: (a: number) => number;
 export const document_clone: (a: number) => number;
+export const document_equals: (a: number, b: number) => number;
 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;

package/package.json

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