@quillmark/wasm 0.99.0 → 0.100.0

package/core/wasm_bg.js

@@ -169,7 +169,48 @@ export class Document {
         }
     }
     /**
-     * Revise the richtext field at `addr` from markdown, typed *and*
+     * Interpreted **corpus** read at `addr`: the stable ABI under the runtime
+     * `reader.getContent` / `reader.card(i).getContent`. The corpus twin of
+     * [`reader.get`](Self::reader_get), which projects; this decodes the stored
+     * value through the codec the field's declared type names (`richtext` as
+     * markdown, `plaintext` as literal text) and returns the canonical `Content`.
+     *
+     * Total over the storage form: a committed field holds a content object and
+     * a parsed one holds the authored string, and both read back as a corpus
+     * here, so a consumer mounting a corpus editor stops branching on how the
+     * document was built.
+     *
+     * A bare string is `Addr` shorthand for `{ field }`; `{ card, field }`
+     * targets a composable card. Returns `undefined` for an **absent** field. An
+     * absent `addr.field` reads the **body** corpus, quill-free, mirroring
+     * [`getStored`](Self::get_stored). Throws `edit::unknown_field` for a name
+     * the schema does not declare, `edit::field_not_content` for a declared type
+     * that is not a content leaf (`array<richtext>` carries content and still has
+     * no one corpus), `edit::field_richtext_decode` for a stored value
+     * that decodes under neither encoding, and `edit::index_out_of_range` for a
+     * bad `addr.card`.
+     * @param {Quill} quill
+     * @param {Addr | string} addr
+     * @returns {Content | undefined}
+     */
+    _readerGetContent(quill, addr) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            _assertClass(quill, Quill);
+            wasm.document__readerGetContent(retptr, this.__wbg_ptr, quill.__wbg_ptr, addHeapObject(addr));
+            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);
+        }
+    }
+    /**
+     * Revise the content field at `addr` from authored text, typed *and*
      * anchor-preserving: the ABI under `writer.reviseField`. Resolves the
      * field's schema from `quill` (main card, or the addressed card's `$kind`)
      * and defers to [`TypedWriter::revise_field`](quillmark_core::TypedWriter::revise_field):
@@ -178,6 +219,9 @@ export class Document {
      * multi-block result with `edit::field_richtext_not_inline`. Returns the
      * text `Delta`.
      *
+     * The codec is the declared type's: `richtext` diffs markdown, `plaintext`
+     * the literal text.
+     *
      * `addr` must name a field (a bare string is `{ field }`); a body address
      * throws (a body carries no field schema: use [`revise`](Self::revise)). A
      * name the schema does not declare throws `edit::unknown_field`. Throws
@@ -185,14 +229,14 @@ export class Document {
      * `writer.reviseField` in the runtime layer.
      * @param {Quill} quill
      * @param {Addr | string} addr
-     * @param {string} markdown
+     * @param {string} text
      * @returns {Delta}
      */
-    _reviseField(quill, addr, markdown) {
+    _reviseField(quill, addr, text) {
         try {
             const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
             _assertClass(quill, Quill);
-            const ptr0 = passStringToWasm0(markdown, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const ptr0 = passStringToWasm0(text, wasm.__wbindgen_export, wasm.__wbindgen_export2);
             const len0 = WASM_VECTOR_LEN;
             wasm.document__reviseField(retptr, this.__wbg_ptr, quill.__wbg_ptr, addHeapObject(addr), ptr0, len0);
             var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
@@ -289,20 +333,6 @@ export class Document {
         const ret = wasm.document_cardCount(this.__wbg_ptr);
         return ret >>> 0;
     }
-    /**
-     * The index of the composable card whose `$id` equals `id`, or
-     * `undefined` when none carries it. Resolves the durable card handle
-     * without a hand-rolled scan over [`cards`](Self::cards); `$id` is
-     * unique per document, so at most one card matches.
-     * @param {string} id
-     * @returns {number | undefined}
-     */
-    cardIndexById(id) {
-        const ptr0 = passStringToWasm0(id, wasm.__wbindgen_export, wasm.__wbindgen_export2);
-        const len0 = WASM_VECTOR_LEN;
-        const ret = wasm.document_cardIndexById(this.__wbg_ptr, ptr0, len0);
-        return takeObject(ret);
-    }
     /**
      * @returns {Card[]}
      */
@@ -536,8 +566,7 @@ export class Document {
     }
     /**
      * Read the **verbatim stored value** at `addr`: the raw payload value of a
-     * field (a content object for a richtext field, a scalar/array/object
-     * otherwise), or the **body content** when `addr.field` is absent. A bare
+     * field, or the **body content** when `addr.field` is absent. A bare
      * string is `Addr` shorthand for `{ field }`. Reads are total over the field
      * axis: an absent field is `undefined`; only an out-of-range `addr.card`
      * throws `edit::index_out_of_range`. Needs no schema, so it lives on
@@ -545,6 +574,16 @@ export class Document {
      * the interpreted schema-plane [`reader.get`](Self::reader_get). For the
      * markdown projection use [`getMarkdown`](Self::get_markdown) (body) or
      * `reader.get` (a field's declared type).
+     *
+     * **A content field at rest has one stored form per codec**: a `richtext`
+     * field holds the canonical content object, a `plaintext` field its literal
+     * string. A document that came through the bound door (`quill.parse` /
+     * `quill.conform`) is at rest, so this read no longer depends on which lane
+     * built it. A document that came through the transport door
+     * (`Document.fromMarkdown`, a legacy stored row) may rest as authored until
+     * it is conformed, and this read reports what is there. For the corpus
+     * either way, use the schema-plane `reader.getContent`, which decodes
+     * through the codec the field's declared type names.
      * @param {Addr | string} addr
      * @returns {unknown}
      */
@@ -1254,6 +1293,10 @@ export class Document {
         return ret === 0 ? undefined : Document.__wrap(ret);
     }
     /**
+     * The non-fatal diagnostics of the load that produced this document: parse
+     * warnings, plus the `conform::*` warnings when it came through
+     * `quill.parse`. Session state, not document value: `equals` and the
+     * storage DTO exclude it, and `fromJson` / `loadJson` clear it.
      * @returns {Diagnostic[]}
      */
     get warnings() {
@@ -1333,6 +1376,40 @@ export class Quill {
             wasm.__wbindgen_export4(deferred1_0, deferred1_1, 1);
         }
     }
+    /**
+     * Land `doc`'s declared content fields at their canonical rest **in
+     * place**, returning the `conform::*` diagnostics for the values that would
+     * not commit (an empty array when everything rested).
+     *
+     * The read-repair verb: a document that arrived through the transport door
+     * (`fromMarkdown`, `fromJson`, a stored row) converges here, and is then
+     * eligible for rewrite under its current schema tag. Idempotent, and a
+     * no-op on an already-canonical document: an equal value is not rewritten,
+     * so YAML comments and stored bytes survive.
+     *
+     * A `!must_fill` marker anywhere in a field's value skips that field (the
+     * marker is the state), and a value the strict write refuses stays as
+     * authored with a diagnostic. Throws when `doc` declares a different
+     * `$quill`, before any mutation.
+     * @param {Document} doc
+     * @returns {Diagnostic[]}
+     */
+    conform(doc) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            _assertClass(doc, Document);
+            wasm.quill_conform(retptr, this.__wbg_ptr, doc.__wbg_ptr);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            if (r2) {
+                throw takeObject(r1);
+            }
+            return takeObject(r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
     /**
      * Build a quill from a file tree. Pure: no backend, no engine; the
      * declared backend is resolved later, at render time.
@@ -1381,6 +1458,39 @@ export class Quill {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
+    /**
+     * Parse `markdown` and conform it against this quill: the **primary
+     * ingestion path**, and the bound twin of the schema-free
+     * `Document.fromMarkdown`. The returned document rests at its canonical
+     * form (a `richtext` field as a content object, a `plaintext` field as its
+     * literal string), so `getStored` no longer answers "corpus or string?"
+     * with "depends how this document was built".
+     *
+     * Parse warnings and the `conform::*` diagnostics both land on
+     * `doc.warnings`. Throws on a parse failure, or when `markdown` declares a
+     * `$quill` this quill does not answer to: nothing conforms under the wrong
+     * schema. To open a document whose `$quill` is stale, use the transport
+     * door (`Document.fromMarkdown`, `setQuillRef`, then `quill.conform`).
+     * @param {string} markdown
+     * @returns {Document}
+     */
+    parse(markdown) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passStringToWasm0(markdown, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            wasm.quill_parse(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 Document.__wrap(r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
     /**
      * The resolved-value view of `doc` against this quill's schema: for every
      * declared field the value the render projection would use and the

package/core/wasm_bg.wasm.d.ts

@@ -7,12 +7,12 @@ export const document__addCard: (a: number, b: number, c: number, d: number, e:
 export const document__commitField: (a: number, b: number, c: number, d: number, e: number) => void;
 export const document__commitFields: (a: number, b: number, c: number, d: number, e: number) => void;
 export const document__readerGet: (a: number, b: number, c: number, d: number) => void;
+export const document__readerGetContent: (a: number, b: number, c: number, d: number) => void;
 export const document__reviseField: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
 export const document_applyChange: (a: number, b: number, c: number, d: number) => void;
 export const document_blueprintInstruction: (a: number, b: number, c: number) => void;
 export const document_card: (a: number, b: number, c: number) => void;
 export const document_cardCount: (a: number) => number;
-export const document_cardIndexById: (a: number, b: number, c: number) => number;
 export const document_cards: (a: number, b: number) => void;
 export const document_clone: (a: number) => number;
 export const document_currentSchemaVersion: (a: number) => void;
@@ -63,8 +63,10 @@ export const mapPos: (a: number, b: number, c: number, d: number) => void;
 export const parseDocPath: (a: number, b: number, c: number) => void;
 export const quill_backendId: (a: number, b: number) => void;
 export const quill_blueprint: (a: number, b: number) => void;
+export const quill_conform: (a: number, b: number, c: number) => void;
 export const quill_fromTree: (a: number, b: number) => void;
 export const quill_metadata: (a: number, b: number) => void;
+export const quill_parse: (a: number, b: number, c: number, d: number) => void;
 export const quill_resolve: (a: number, b: number, c: number) => void;
 export const quill_schema: (a: number, b: number) => void;
 export const quill_seedCard: (a: number, b: number, c: number, d: number, e: number) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quillmark/wasm",
-  "version": "0.99.0",
+  "version": "0.100.0",
   "description": "WebAssembly bindings for Quillmark, a schema-driven document engine",
   "type": "module",
   "license": "Apache-2.0",

package/runtime/runtime.d.ts

@@ -674,12 +674,16 @@ export declare class DocumentWriter {
 	 */
 	setBody(markdown: string): void;
 	/**
-	 * Revise the richtext main-card field `name` from markdown: typed *and*
+	 * Revise the content main-card field `name` from authored text: typed *and*
 	 * anchor-preserving. Surviving anchors rebase, then the diffed result is
 	 * schema-conformed (`richtext(inline)` rejects a multi-block result). Throws
 	 * `UnknownField` for a name the schema does not declare. Returns the `Delta`.
+	 *
+	 * The codec comes from the declared type: `richtext` diffs markdown, while
+	 * `plaintext` diffs the literal text and never imports markdown, so a
+	 * byte-identical revise of a value carrying escapes is a byte no-op.
 	 */
-	reviseField(name: string, markdown: string): Delta;
+	reviseField(name: string, text: string): Delta;
 	/**
 	 * Build a composable card of `kind`, typed-commit `fields` onto it, set its
 	 * body from optional markdown, and place it: the fused `makeCard` + typed
@@ -696,8 +700,8 @@ export declare class DocumentWriter {
 	 * A {@link CardWriter} for the composable card at `index`. Index validity is
 	 * checked lazily at commit time, so an out-of-range index does not throw here.
 	 * The cursor is ephemeral: a `removeCard`/`addCard` between binding and writing
-	 * silently retargets it; for durable addressing stamp `$id` and re-resolve at
-	 * write.
+	 * silently retargets it; re-resolve the index at write time when cards may
+	 * move.
 	 */
 	card(index: number): CardWriter;
 }
@@ -723,12 +727,12 @@ export declare class CardWriter {
 	/** Set this card's body from markdown (edit semantics), discarding the delta. */
 	setBody(markdown: string): void;
 	/**
-	 * Revise the richtext field `name` on this card from markdown: typed *and*
-	 * anchor-preserving; the card twin of {@link DocumentWriter.reviseField}.
-	 * Throws `UnknownField` for an undeclared name and `IndexOutOfRange` if the
-	 * bound index is out of range. Returns the `Delta`.
+	 * Revise the content field `name` on this card from authored text: typed *and*
+	 * anchor-preserving; the card twin of {@link DocumentWriter.reviseField},
+	 * codec included. Throws `UnknownField` for an undeclared name and
+	 * `IndexOutOfRange` if the bound index is out of range. Returns the `Delta`.
 	 */
-	reviseField(name: string, markdown: string): Delta;
+	reviseField(name: string, text: string): Delta;
 }
 
 /**
@@ -745,6 +749,12 @@ export declare class CardWriter {
  * decode throws `FieldRichtextDecode`. A field's markdown lives here, not on the
  * body-only `Document.getMarkdown`. The body read stays quill-free (a body's type
  * is a format fact) and never throws.
+ *
+ * `getContent` is the same read at the other end of the codec, returning the
+ * corpus rather than the projection. It binds the quill for the same reason
+ * `get` does: a `richtext` string is markdown and a `plaintext` string is
+ * literal text, so the same stored bytes decode two ways and only the declared
+ * type says which.
  */
 export declare class DocumentReader {
 	constructor(quill: Quill, doc: Document);
@@ -759,6 +769,17 @@ export declare class DocumentReader {
 	 * `IndexOutOfRange` for a bad `addr.card`.
 	 */
 	get(addr: Addr | string): unknown;
+	/**
+	 * Read the content field at `addr` as its canonical `Content` corpus: the
+	 * corpus twin of {@link get}, which projects. Decodes through the codec the
+	 * declared type names (`richtext` as markdown, `plaintext` as literal text),
+	 * so a committed field and a parsed one read back the same corpus and the
+	 * storage form stops being the caller's business. An absent `addr.field`
+	 * reads the body corpus. `undefined` for an absent field; throws
+	 * `UnknownField`, `FieldNotContent` for a declared type that is not a content
+	 * leaf, `FieldRichtextDecode` for an undecodable value, and `IndexOutOfRange`.
+	 */
+	getContent(addr: Addr | string): Content | undefined;
 	/** The main body's markdown: the quill-free body read. Equals `get({})`. */
 	getBody(): string;
 	/**
@@ -791,6 +812,11 @@ export declare class CardReader {
 	 * `IndexOutOfRange` for a bad index.
 	 */
 	get(name: string): unknown;
+	/**
+	 * Read the content field `name` on this card as its canonical `Content`
+	 * corpus: the card twin of {@link DocumentReader.getContent}.
+	 */
+	getContent(name: string): Content | undefined;
 	/** This card's body markdown: the card twin of {@link DocumentReader.getBody}. */
 	getBody(): string;
 }

package/runtime/runtime.js

@@ -244,7 +244,7 @@ patchHandleChecked(Document.prototype, 'equals', (original) =>
 		return original.call(this, other);
 	}
 );
-for (const name of /** @type {const} */ (['validate', 'resolve'])) {
+for (const name of /** @type {const} */ (['validate', 'resolve', 'conform'])) {
 	// Named once per patch, not per call: `validate` runs per keystroke.
 	const method = `Quill.${name}`;
 	patchHandleChecked(Quill.prototype, name, (original) =>
@@ -917,17 +917,21 @@ export class DocumentWriter {
 		this.#doc.revise({}, markdown);
 	}
 	/**
-	 * Revise the richtext main-card field `name` from markdown: typed *and*
+	 * Revise the content main-card field `name` from authored text: typed *and*
 	 * anchor-preserving. Surviving anchors rebase, then the diffed result is
 	 * schema-conformed (`richtext(inline)` rejects a multi-block result). Throws
 	 * `UnknownField` for a name the schema does not declare. Returns the text
 	 * {@link Delta}.
+	 *
+	 * The codec comes from the declared type: `richtext` diffs markdown, while
+	 * `plaintext` diffs the literal text and never imports markdown, so a
+	 * byte-identical revise of a value carrying escapes is a byte no-op.
 	 * @param {string} name
-	 * @param {string} markdown
+	 * @param {string} text
 	 * @returns {import('../core/wasm.js').Delta}
 	 */
-	reviseField(name, markdown) {
-		return this.#doc._reviseField(this.#quill, name, markdown);
+	reviseField(name, text) {
+		return this.#doc._reviseField(this.#quill, name, text);
 	}
 	/**
 	 * Build a composable card of `kind`, typed-commit `fields` onto it, set its
@@ -964,8 +968,7 @@ export class DocumentWriter {
 	 *
 	 * The cursor is ephemeral: bind, write, discard. It holds `index`, not the
 	 * card: a `removeCard`/`addCard` between binding and writing silently
-	 * retargets it. For durable addressing stamp `$id` and re-resolve the index
-	 * at write time.
+	 * retargets it. Re-resolve the index at write time when cards may move.
 	 * @param {number} index
 	 * @returns {CardWriter}
 	 */
@@ -1039,16 +1042,17 @@ export class CardWriter {
 		this.#doc.revise({ card: this.#index }, markdown);
 	}
 	/**
-	 * Revise the richtext field `name` on this card from markdown: typed *and*
-	 * anchor-preserving; the card twin of {@link DocumentWriter.reviseField}.
-	 * Throws `UnknownField` for an undeclared name and `IndexOutOfRange` if the
-	 * bound index is out of range. Returns the text {@link Delta}.
+	 * Revise the content field `name` on this card from authored text: typed *and*
+	 * anchor-preserving; the card twin of {@link DocumentWriter.reviseField},
+	 * codec included. Throws `UnknownField` for an undeclared name and
+	 * `IndexOutOfRange` if the bound index is out of range. Returns the text
+	 * {@link Delta}.
 	 * @param {string} name
-	 * @param {string} markdown
+	 * @param {string} text
 	 * @returns {import('../core/wasm.js').Delta}
 	 */
-	reviseField(name, markdown) {
-		return this.#doc._reviseField(this.#quill, { card: this.#index, field: name }, markdown);
+	reviseField(name, text) {
+		return this.#doc._reviseField(this.#quill, { card: this.#index, field: name }, text);
 	}
 }
 
@@ -1119,6 +1123,22 @@ export class DocumentReader {
 	get(addr) {
 		return this.#doc._readerGet(this.#quill, addr);
 	}
+	/**
+	 * Read the content field at `addr` as its canonical `Content` corpus: the
+	 * corpus twin of {@link get}, which projects. Decodes through the codec the
+	 * declared type names (`richtext` as markdown, `plaintext` as literal text),
+	 * so a field the writer committed as a corpus and one a markdown parse left
+	 * as an authored string read back the same; no branching on how the
+	 * document was built. An absent `addr.field` reads the body corpus.
+	 * `undefined` for an absent field; throws `UnknownField`, `FieldNotContent`
+	 * for a type that is not a content leaf, `FieldRichtextDecode` for an undecodable
+	 * value, and `IndexOutOfRange` for a bad `addr.card`.
+	 * @param {import('../core/wasm.js').Addr | string} addr
+	 * @returns {import('../core/wasm.js').Content | undefined}
+	 */
+	getContent(addr) {
+		return this.#doc._readerGetContent(this.#quill, addr);
+	}
 	/**
 	 * The main body's markdown: the quill-free body read (a body's type is a
 	 * format fact, not a schema fact). Equivalent to `get({})`.
@@ -1184,6 +1204,15 @@ export class CardReader {
 	get(name) {
 		return this.#doc._readerGet(this.#quill, { card: this.#index, field: name });
 	}
+	/**
+	 * Read the content field `name` on this card as its canonical `Content`
+	 * corpus: the card twin of {@link DocumentReader.getContent}.
+	 * @param {string} name
+	 * @returns {import('../core/wasm.js').Content | undefined}
+	 */
+	getContent(name) {
+		return this.#doc._readerGetContent(this.#quill, { card: this.#index, field: name });
+	}
 	/**
 	 * This card's body markdown: the card twin of {@link DocumentReader.getBody}.
 	 * @returns {string}