@quillmark/wasm 0.81.0-rc.1 → 0.81.0

package/README.md

@@ -69,7 +69,7 @@ semantic equality.
 
 ### `doc.toJson()`
 Serialize the document to a versioned storage DTO — a JSON **string**
-carrying a `schema` version tag. Use this (not `toMarkdown`) to persist a
+carrying a `schema` version. Use this (not `toMarkdown`) to persist a
 document across a process restart or crate upgrade: the wire format is
 frozen per `schema` version, whereas Markdown syntax evolves. Parse-time
 `warnings` are not part of the DTO.
@@ -79,6 +79,13 @@ global is not involved. It is standard JSON text, so callers may
 `JSON.parse` it to inspect it — but it is intended as an opaque blob you
 persist and hand back.
 
+`toJson()` is **deterministic**: a `Document` that is `equals` to another
+serializes to a byte-identical string — across repeated calls, and across
+any crate upgrade that keeps the same `schema` version (every release does until
+the `Document` model changes; see [Storage compatibility](#storage-compatibility-across-versions)).
+Field order is fixed and object key order is preserved, so content hashes
+and string-equality dirty-checks over the output are stable.
+
 ### `Document.fromJson(json)`
 Reconstruct a `Document` from a storage DTO string produced by `toJson`.
 Round-trips losslessly:
@@ -89,9 +96,57 @@ const restored = Document.fromJson(stored);
 restored.equals(doc);               // true
 ```
 
-Throws a JS `Error` on malformed JSON, an unknown `schema` tag, or a
+Throws a JS `Error` on malformed JSON, an unknown `schema` version, or a
 malformed payload. The restored document has no parse-time `warnings`.
 
+### `Document.tryFromJson(json)`
+Like `fromJson`, but returns `undefined` instead of throwing when `json` is
+not a valid storage DTO. Use it to branch on format without a heuristic or
+`try`/`catch` as control flow:
+
+```ts
+// "JSON canonical, Markdown fallback" — no exceptions, no string sniffing
+const doc = Document.tryFromJson(content) ?? Document.fromMarkdown(content);
+```
+
+`undefined` means only "not a storage DTO"; `fromMarkdown` still throws on
+genuinely malformed Markdown.
+
+### Storage compatibility across versions
+
+The `schema` value (`quillmark/document@0.81.0`) is the **model version**,
+not the running crate version. It is a hand-set constant, bumped only when
+the `Document` model itself changes — so every `0.81.x` patch release reads
+and writes that same value.
+
+- **Upgrading is safe.** A newer build always reads documents written by an
+  older one. Each schema version's wire format is frozen and never changes;
+  when the model does change, the new build ships a migration that converts
+  old payloads on `fromJson`. A document you commit as your canonical
+  on-disk format keeps loading across crate upgrades — there is no need to
+  pin old wasm to read old data.
+- **Downgrading is not.** `fromJson` rejects an *unknown* (i.e. newer)
+  `schema` version rather than guessing at a format it predates. Don't feed
+  documents written by a newer build back into an older one.
+
+To detect a version mismatch before parsing, use the static accessors:
+
+```ts
+const v = Document.schemaVersionOf(blob); // undefined | string
+if (v && v !== Document.currentSchemaVersion()) {
+  // payload is from a build with a different model version
+}
+```
+
+`schemaVersionOf` does not validate the payload — it only reads the
+`schema` field, returning `undefined` for non-JSON, non-objects, or
+payloads that don't carry one. Use it to distinguish "wrong version" from
+"corrupt" when `fromJson` throws.
+
+In short: persist the `toJson` string, upgrade freely, never downgrade. The
+full design — including how migrations are added — is in
+`prose/canon/DOCUMENT_STORAGE.md`.
+
 ### `doc.equals(other)`
 Structural equality between two `Document` handles. Compares `main` and
 `cards` by value; parse-time `warnings` are intentionally excluded.
@@ -218,8 +273,11 @@ compilation failures. The same shape applies to every throw site:
 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).
+teardown hook for callers that want deterministic release.
+
+The package requires Node 24+ (`engines: { node: ">=24" }`) and current
+evergreen browsers; `--weak-refs` itself only needs Node 14.6+, but the
+published package floor is 24.
 
 For environments where `using` (the [explicit resource management][erm]
 proposal) hasn't landed, use an explicit `try` / `finally`:

package/bundler/wasm.d.ts

@@ -269,6 +269,20 @@ export class Document {
      * history of either handle.
      */
     clone(): Document;
+    /**
+     * Schema version this build writes via [`toJson`](Document::to_json).
+     *
+     * Compare a payload's [`schemaVersionOf`](Document::schema_version_of)
+     * against this to detect mismatches before calling
+     * [`fromJson`](Document::from_json).
+     *
+     * The tag tracks the **`Document` model version** — the crate version
+     * at which the wire format was last changed — not the running crate
+     * version. Every patch and minor release within the same model
+     * generation returns the same string; the tag advances only when a
+     * new schema variant ships.
+     */
+    static currentSchemaVersion(): string;
     /**
      * Structural equality against another `Document`.
      *
@@ -364,6 +378,27 @@ export class Document {
      * Mutators never modify `warnings`.
      */
     replaceBody(body: string): void;
+    /**
+     * Read the schema version from a raw storage DTO string without
+     * performing a full parse, or `undefined`.
+     *
+     * Returns the `schema` field as-is — including unknown future versions
+     * that `fromJson` would reject. Use this to distinguish "this build is
+     * too old for the payload" from "the payload is corrupt" when
+     * [`fromJson`](Document::from_json) throws:
+     *
+     * ```js
+     * const v = Document.schemaVersionOf(blob);
+     * if (v === undefined) {
+     *   // not a stored DTO at all — try fromMarkdown
+     * } else if (v !== Document.currentSchemaVersion()) {
+     *   // newer (or older unmigrated) schema — prompt the user to upgrade
+     * } else {
+     *   doc = Document.fromJson(blob);
+     * }
+     * ```
+     */
+    static schemaVersionOf(json: string): string | undefined;
     /**
      * Replace the tag of the composable card at `index`.
      *
@@ -413,7 +448,7 @@ export class Document {
      * Serialize this document to a versioned storage DTO string.
      *
      * Returns the document as a JSON string carrying a `schema` version
-     * tag. The string is produced inside the module via `serde_json` and
+     * field. The string is produced inside the module via `serde_json` and
      * round-trips losslessly back to an equal `Document` via
      * [`fromJson`](Document::from_json) — the JS `JSON` global is not
      * involved in either direction.
@@ -426,6 +461,22 @@ export class Document {
      * The result is standard JSON text, so callers that want to inspect it
      * may `JSON.parse` it — but treating it as an opaque blob is the
      * intended use.
+     *
+     * ## Byte-stability
+     *
+     * The output is a **byte-deterministic** function of the document's
+     * value within a given `schema` version: two documents that compare
+     * equal under [`equals`](Document::equals) serialize to byte-equal
+     * strings, and the same document re-serialized in a later patch or
+     * minor release of this crate (same `schema`) produces the same bytes.
+     * Content-hash use cases (template-divergence detection, cache keys)
+     * can rely on this without re-canonicalizing.
+     *
+     * Specifics: object fields are emitted in struct-declaration order;
+     * frontmatter field values preserve their YAML insertion order (no
+     * key sorting); whitespace is `serde_json`'s compact form (no spaces
+     * between tokens, no trailing newline); strings use `serde_json`'s
+     * standard escape set. A schema-version bump may change any of these.
      */
     toJson(): string;
     /**
@@ -436,6 +487,21 @@ export class Document {
      * produces a `Document` equal to `self` by value and by type.
      */
     toMarkdown(): string;
+    /**
+     * Reconstruct a `Document` from a storage DTO string, or `undefined`.
+     *
+     * Like [`fromJson`](Document::from_json), but returns `undefined`
+     * instead of throwing when `json` is not a valid storage DTO. Use this
+     * to detect format and fall back without exceptions as control flow:
+     *
+     * ```js
+     * const doc = Document.tryFromJson(content) ?? Document.fromMarkdown(content);
+     * ```
+     *
+     * `undefined` only ever means "not a storage DTO" — `fromMarkdown`
+     * still throws on genuinely malformed markdown.
+     */
+    static tryFromJson(json: string): Document | undefined;
     /**
      * Replace the body of the card at `index`.
      *

package/bundler/wasm_bg.js

@@ -61,6 +61,36 @@ export class Document {
         const ret = wasm.document_clone(this.__wbg_ptr);
         return Document.__wrap(ret);
     }
+    /**
+     * Schema version this build writes via [`toJson`](Document::to_json).
+     *
+     * Compare a payload's [`schemaVersionOf`](Document::schema_version_of)
+     * against this to detect mismatches before calling
+     * [`fromJson`](Document::from_json).
+     *
+     * The tag tracks the **`Document` model version** — the crate version
+     * at which the wire format was last changed — not the running crate
+     * version. Every patch and minor release within the same model
+     * generation returns the same string; the tag advances only when a
+     * new schema variant ships.
+     * @returns {string}
+     */
+    static currentSchemaVersion() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.document_currentSchemaVersion(retptr);
+            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);
+        }
+    }
     /**
      * Structural equality against another `Document`.
      *
@@ -320,6 +350,46 @@ export class Document {
         const len0 = WASM_VECTOR_LEN;
         wasm.document_replaceBody(this.__wbg_ptr, ptr0, len0);
     }
+    /**
+     * Read the schema version from a raw storage DTO string without
+     * performing a full parse, or `undefined`.
+     *
+     * Returns the `schema` field as-is — including unknown future versions
+     * that `fromJson` would reject. Use this to distinguish "this build is
+     * too old for the payload" from "the payload is corrupt" when
+     * [`fromJson`](Document::from_json) throws:
+     *
+     * ```js
+     * const v = Document.schemaVersionOf(blob);
+     * if (v === undefined) {
+     *   // not a stored DTO at all — try fromMarkdown
+     * } else if (v !== Document.currentSchemaVersion()) {
+     *   // newer (or older unmigrated) schema — prompt the user to upgrade
+     * } else {
+     *   doc = Document.fromJson(blob);
+     * }
+     * ```
+     * @param {string} json
+     * @returns {string | undefined}
+     */
+    static schemaVersionOf(json) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passStringToWasm0(json, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            wasm.document_schemaVersionOf(retptr, ptr0, len0);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            let v2;
+            if (r0 !== 0) {
+                v2 = getStringFromWasm0(r0, r1).slice();
+                wasm.__wbindgen_export4(r0, r1 * 1, 1);
+            }
+            return v2;
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
     /**
      * Replace the tag of the composable card at `index`.
      *
@@ -432,7 +502,7 @@ export class Document {
      * Serialize this document to a versioned storage DTO string.
      *
      * Returns the document as a JSON string carrying a `schema` version
-     * tag. The string is produced inside the module via `serde_json` and
+     * field. The string is produced inside the module via `serde_json` and
      * round-trips losslessly back to an equal `Document` via
      * [`fromJson`](Document::from_json) — the JS `JSON` global is not
      * involved in either direction.
@@ -445,30 +515,38 @@ export class Document {
      * The result is standard JSON text, so callers that want to inspect it
      * may `JSON.parse` it — but treating it as an opaque blob is the
      * intended use.
+     *
+     * ## Byte-stability
+     *
+     * The output is a **byte-deterministic** function of the document's
+     * value within a given `schema` version: two documents that compare
+     * equal under [`equals`](Document::equals) serialize to byte-equal
+     * strings, and the same document re-serialized in a later patch or
+     * minor release of this crate (same `schema`) produces the same bytes.
+     * Content-hash use cases (template-divergence detection, cache keys)
+     * can rely on this without re-canonicalizing.
+     *
+     * Specifics: object fields are emitted in struct-declaration order;
+     * frontmatter field values preserve their YAML insertion order (no
+     * key sorting); whitespace is `serde_json`'s compact form (no spaces
+     * between tokens, no trailing newline); strings use `serde_json`'s
+     * standard escape set. A schema-version bump may change any of these.
      * @returns {string}
      */
     toJson() {
-        let deferred2_0;
-        let deferred2_1;
+        let deferred1_0;
+        let deferred1_1;
         try {
             const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
             wasm.document_toJson(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);
-            var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
-            var ptr1 = r0;
-            var len1 = r1;
-            if (r3) {
-                ptr1 = 0; len1 = 0;
-                throw takeObject(r2);
-            }
-            deferred2_0 = ptr1;
-            deferred2_1 = len1;
-            return getStringFromWasm0(ptr1, len1);
+            deferred1_0 = r0;
+            deferred1_1 = r1;
+            return getStringFromWasm0(r0, r1);
         } finally {
             wasm.__wbindgen_add_to_stack_pointer(16);
-            wasm.__wbindgen_export4(deferred2_0, deferred2_1, 1);
+            wasm.__wbindgen_export4(deferred1_0, deferred1_1, 1);
         }
     }
     /**
@@ -495,6 +573,28 @@ export class Document {
             wasm.__wbindgen_export4(deferred1_0, deferred1_1, 1);
         }
     }
+    /**
+     * Reconstruct a `Document` from a storage DTO string, or `undefined`.
+     *
+     * Like [`fromJson`](Document::from_json), but returns `undefined`
+     * instead of throwing when `json` is not a valid storage DTO. Use this
+     * to detect format and fall back without exceptions as control flow:
+     *
+     * ```js
+     * const doc = Document.tryFromJson(content) ?? Document.fromMarkdown(content);
+     * ```
+     *
+     * `undefined` only ever means "not a storage DTO" — `fromMarkdown`
+     * still throws on genuinely malformed markdown.
+     * @param {string} json
+     * @returns {Document | undefined}
+     */
+    static tryFromJson(json) {
+        const ptr0 = passStringToWasm0(json, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.document_tryFromJson(ptr0, len0);
+        return ret === 0 ? undefined : Document.__wrap(ret);
+    }
     /**
      * Replace the body of the card at `index`.
      *

package/bundler/wasm_bg.wasm.d.ts

@@ -8,6 +8,7 @@ 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_currentSchemaVersion: (a: number) => void;
 export const document_equals: (a: number, b: number) => number;
 export const document_fromJson: (a: number, b: number, c: number) => void;
 export const document_fromMarkdown: (a: number, b: number, c: number) => void;
@@ -20,12 +21,14 @@ export const document_removeCard: (a: number, b: number) => number;
 export const document_removeCardField: (a: number, b: number, c: number, d: number, e: number) => void;
 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_setCardTag: (a: number, b: number, c: number, d: number, e: 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_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_updateCardField: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
 export const document_warnings: (a: number) => number;

package/package.json

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