@quillmark/wasm 0.94.0 → 0.96.0

package/runtime/runtime.js

@@ -58,11 +58,27 @@
 // re-export keeps the identity: the exported `Quill` IS the core class.
 import { Quill, Document, init } from '../core/wasm.js';
 export { Quill, Document, init };
-// The document-free corpus codec — re-exported verbatim from the core build so
+// The document-free content codec — re-exported verbatim from the core build so
 // the runtime subpath exposes `exportMarkdown(body)` (the on-demand markdown
-// projection that replaces the eager `bodyMarkdown`), `importMarkdown`, and the
-// position-mapping pair (`rebase`, `mapPos`).
+// projection), `importMarkdown`, and the position-mapping pair (`rebase`,
+// `mapPos`).
 export { importMarkdown, exportMarkdown, rebase, mapPos } from '../core/wasm.js';
+// The document-model path parser/serializer: `parseDocPath(str) => DocPathSeg[]`
+// and its inverse `formatDocPath`, so a consumer routes on `Diagnostic.path`
+// segments instead of reverse-engineering the grammar.
+export { parseDocPath, formatDocPath } from '../core/wasm.js';
+
+// ── The main-card address ───────────────────────────────────────────────────
+/**
+ * The main card's address — the default target of the card-scoped verbs
+ * (`storeFields` / `storeExt` / `commitFields` / …). A named, `CardAddr`-typed
+ * alias for the empty address `{}`, so a main-card write names its target:
+ * `doc.storeFields(MAIN_CARD_ADDR, fields)`. It IS `{}` (frozen), a pure alias —
+ * `{}` and `undefined` stay equally valid. Card axis only: a card selector,
+ * never a field address.
+ * @type {import('../core/wasm.js').CardAddr}
+ */
+export const MAIN_CARD_ADDR = Object.freeze({});
 
 /**
  * Narrow an unknown caught value to a `QuillmarkError` — the error every
@@ -479,7 +495,7 @@ export class LiveSession {
 	 * @param {number} page
 	 * @param {number} x
 	 * @param {number} y
-	 * @returns {import('./runtime.d.ts').CorpusHit | undefined}
+	 * @returns {import('./runtime.d.ts').ContentHit | undefined}
 	 */
 	positionAt(page, x, y) {
 		return this.#inner.positionAt(page, x, y);
@@ -531,7 +547,7 @@ export class LiveSession {
 // typed-committed (coerced to canonical form, mismatch throws now), and a name
 // the schema does not declare throws `UnknownField` rather than falling to the
 // opaque store — on the typed path an undeclared name is a typo. Opaque storage
-// stays available through the raw `Document.setField` / `setCardField` verbs.
+// stays available through the raw addressed `Document.storeField` verb.
 
 /**
  * A {@link Document} bound to its {@link Quill} for typed writes — the JS twin
@@ -556,54 +572,68 @@ export class DocumentWriter {
 	}
 	/**
 	 * Typed-commit one main-card field (strict coerce, mismatch throws now).
-	 * Throws `UnknownField` for a name the schema does not declare. See
-	 * `Document.commitField`.
+	 * Throws `UnknownField` for a name the schema does not declare.
 	 * @param {string} name
 	 * @param {unknown} value
 	 * @returns {void}
 	 */
 	set(name, value) {
-		return this.#doc.commitField(this.#quill, name, value);
+		return this.#doc._commitField(this.#quill, name, value);
 	}
 	/**
 	 * Typed-commit several main-card fields atomically — nothing is applied on
 	 * error (throws a per-field diagnostic bundle, including an `UnknownField`
-	 * for each undeclared name). See `Document.commitFields`.
+	 * for each undeclared name).
 	 * @param {Record<string, unknown>} fields
 	 * @returns {void}
 	 */
 	setAll(fields) {
-		return this.#doc.commitFields(this.#quill, fields);
+		return this.#doc._commitFields(this.#quill, MAIN_CARD_ADDR, fields);
 	}
 	/**
 	 * Set the main body from markdown (edit semantics: surviving anchors rebase),
 	 * discarding the text delta — the receipt-free body write. Call
-	 * `doc.revise({}, md)` for the {@link Delta} receipt (the corpus-lane
-	 * spelling). Markdown in, no corpus or receipt in sight.
+	 * `doc.revise({}, md)` for the {@link Delta} receipt.
 	 * @param {string} markdown
 	 * @returns {void}
 	 */
 	setBody(markdown) {
 		this.#doc.revise({}, markdown);
 	}
+	/**
+	 * Revise the richtext main-card field `name` from markdown — 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}.
+	 * @param {string} name
+	 * @param {string} markdown
+	 * @returns {import('../core/wasm.js').Delta}
+	 */
+	reviseField(name, markdown) {
+		return this.#doc._reviseField(this.#quill, name, markdown);
+	}
 	/**
 	 * Build a composable card of `kind`, typed-commit `fields` onto it, set its
-	 * body from optional markdown, and append it — the fused `makeCard` + typed
-	 * commit + `pushCard`. Transactional: the card is committed in full before it
-	 * joins the document, so a rejected field (throws a per-field diagnostic
-	 * bundle, `UnknownField` per undeclared name) or an invalid kind/body leaves
-	 * the document untouched. See `Document.addCard`.
+	 * body from optional markdown, and place it — the fused `makeCard` + typed
+	 * commit + insertion. `at` picks the position: omitted appends, a number
+	 * inserts at that index (`0..=cardCount`), so a positioned typed insert is one
+	 * atomic call rather than `addCard` + `moveCard`. Transactional: the card is
+	 * committed in full before it joins the document, so a rejected field (throws
+	 * a per-field diagnostic bundle, `UnknownField` per undeclared name) or an
+	 * invalid kind/body/position leaves the document untouched.
 	 * @param {string} kind
 	 * @param {Record<string, unknown>} [fields]
 	 * @param {string} [body]
+	 * @param {number} [at] insertion index; appends when omitted
 	 * @returns {void}
 	 */
-	addCard(kind, fields, body) {
-		return this.#doc.addCard(this.#quill, kind, fields, body);
+	addCard(kind, fields, body, at) {
+		return this.#doc._addCard(this.#quill, kind, fields, body, at);
 	}
 	/**
 	 * Remove the composable card at `index`, returning it (or `undefined` if the
-	 * index is out of range) — the tier-1 spelling of `Document.removeCard`.
+	 * index is out of range) — the writer spelling of `Document.removeCard`.
 	 * @param {number} index
 	 * @returns {import('../core/wasm.js').Card | undefined}
 	 */
@@ -651,25 +681,34 @@ export class CardWriter {
 		return this.#index;
 	}
 	/**
-	 * Typed-commit one field on this card, per `Document.commitCardField`.
-	 * Throws `UnknownField` for an undeclared name and `IndexOutOfRange` if the
-	 * bound index is out of range.
+	 * The bound card's `$kind` (empty string when it carries none), read through
+	 * the document — mirrors core `CardWriter::kind()`. Ephemeral like the cursor
+	 * itself: throws `IndexOutOfRange` if the bound index is out of range.
+	 * @returns {string}
+	 */
+	get kind() {
+		return this.#doc.card(this.#index).kind;
+	}
+	/**
+	 * Typed-commit one field on this card, addressed at `{ card, field }`. Throws
+	 * `UnknownField` for an undeclared name and `IndexOutOfRange` if the bound
+	 * index is out of range.
 	 * @param {string} name
 	 * @param {unknown} value
 	 * @returns {void}
 	 */
 	set(name, value) {
-		return this.#doc.commitCardField(this.#quill, this.#index, name, value);
+		return this.#doc._commitField(this.#quill, { card: this.#index, field: name }, value);
 	}
 	/**
-	 * Typed-commit several fields on this card atomically, per
-	 * `Document.commitCardFields`. Throws a per-field diagnostic bundle on error
-	 * and `IndexOutOfRange` if the bound index is out of range.
+	 * Typed-commit several fields on this card atomically, addressed at
+	 * `{ card }`. Throws a per-field diagnostic bundle on error and
+	 * `IndexOutOfRange` if the bound index is out of range.
 	 * @param {Record<string, unknown>} fields
 	 * @returns {void}
 	 */
 	setAll(fields) {
-		return this.#doc.commitCardFields(this.#quill, this.#index, fields);
+		return this.#doc._commitFields(this.#quill, { card: this.#index }, fields);
 	}
 	/**
 	 * Set this card's body from markdown (edit semantics), discarding the delta —
@@ -680,10 +719,22 @@ export class CardWriter {
 	setBody(markdown) {
 		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}.
+	 * @param {string} name
+	 * @param {string} markdown
+	 * @returns {import('../core/wasm.js').Delta}
+	 */
+	reviseField(name, markdown) {
+		return this.#doc._reviseField(this.#quill, { card: this.#index, field: name }, markdown);
+	}
 }
 
 // ── `quill.writer(doc)` — the typed front door ──────────────────────────────
-// The tier-1 default: bind the quill's schema to a document and issue bare
+// The schema-bound writer: bind the quill's schema to a document and issue bare
 // typed writes. Mirrors core's `quill.writer(&mut doc)` — the schema grants the
 // typing, so the quill (not the document) is the factory. Patched onto the
 // re-exported `Quill` prototype rather than wrapped: `Quill === CoreQuill`
@@ -701,3 +752,137 @@ export class CardWriter {
 Quill.prototype.writer = function writer(doc) {
 	return new DocumentWriter(this, doc);
 };
+
+// ── Typed-reader sugar: the schema-plane read surface ──────────────────────────
+// The read twin of the writer above. The transport `Document.get` is schema-free
+// — a `Document` cannot say which fields are richtext, so an unknown field name
+// reads back `undefined` rather than as the typo it is. Binding the quill's
+// schema (`_readerGet` takes the handle, like the `commit*` verbs) lets one `get`
+// interpret by declared type: a richtext field to markdown, a plaintext field to
+// its literal text, every other type verbatim, and an unknown name throws
+// `UnknownField`. A field's markdown lives here, not on the body-only
+// `getMarkdown`. Like the writer classes these hold the caller's handles by
+// reference, own no WASM object, and have nothing to `free()`.
+
+/**
+ * A {@link Document} bound to its {@link Quill} for typed reads — the JS twin of
+ * Rust's `quill.reader(&doc)` and the read counterpart of {@link DocumentWriter}.
+ * Reads target the main card; use {@link card} for a composable card. Holds both
+ * handles by reference and owns neither, so there is nothing to `free()`.
+ */
+export class DocumentReader {
+	#quill;
+	#doc;
+	/**
+	 * @param {Quill} quill the schema source for interpreted reads
+	 * @param {Document} doc the document to read, held by reference (not owned)
+	 */
+	constructor(quill, doc) {
+		this.#quill = quill;
+		this.#doc = doc;
+	}
+	/** The bound document — the same instance passed in. */
+	get document() {
+		return this.#doc;
+	}
+	/**
+	 * Read the value at `addr`, interpreted by its declared type: a richtext field
+	 * to markdown, every other type verbatim. A bare string is `Addr` shorthand
+	 * for `{ field }`; an absent `addr.field` reads the body markdown. `undefined`
+	 * for an absent field; throws `UnknownField` for a name the schema does not
+	 * declare, `FieldRichtextDecode` for a richtext field holding an undecodable
+	 * value, and `IndexOutOfRange` for a bad `addr.card`.
+	 * @param {import('../core/wasm.js').Addr | string} addr
+	 * @returns {unknown}
+	 */
+	get(addr) {
+		return this.#doc._readerGet(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({})`.
+	 * @returns {string}
+	 */
+	getBody() {
+		return this.#doc._readerGet(this.#quill, {});
+	}
+	/**
+	 * A {@link CardReader} bound to the composable card at `index`. Index validity
+	 * is checked lazily by the underlying read (it throws `IndexOutOfRange` at read
+	 * time), so constructing one never throws. Ephemeral like the writer cursor —
+	 * it holds `index`, not the card, so a `removeCard`/`addCard` between binding
+	 * and reading silently retargets it.
+	 * @param {number} index
+	 * @returns {CardReader}
+	 */
+	card(index) {
+		return new CardReader(this.#quill, this.#doc, index);
+	}
+}
+
+/**
+ * A single composable card bound to its {@link Quill} for typed reads, from
+ * {@link DocumentReader.card}. Same `get` / `getBody` verbs as
+ * {@link DocumentReader}, reading the card at its bound index.
+ */
+export class CardReader {
+	#quill;
+	#doc;
+	#index;
+	/**
+	 * @param {Quill} quill the schema source
+	 * @param {Document} doc the document to read, held by reference (not owned)
+	 * @param {number} index the composable card's index
+	 */
+	constructor(quill, doc, index) {
+		this.#quill = quill;
+		this.#doc = doc;
+		this.#index = index;
+	}
+	/** The bound card index. */
+	get index() {
+		return this.#index;
+	}
+	/**
+	 * The bound card's `$kind` (empty string when it carries none), read through
+	 * the document. Throws `IndexOutOfRange` if the bound index is out of range.
+	 * @returns {string}
+	 */
+	get kind() {
+		return this.#doc.card(this.#index).kind;
+	}
+	/**
+	 * Read the field `name` on this card, interpreted by its declared type,
+	 * addressed at `{ card, field }`. `undefined` when absent; throws
+	 * `UnknownField` for an undeclared name and `IndexOutOfRange` for a bad index.
+	 * @param {string} name
+	 * @returns {unknown}
+	 */
+	get(name) {
+		return this.#doc._readerGet(this.#quill, { card: this.#index, field: name });
+	}
+	/**
+	 * This card's body markdown — the card twin of {@link DocumentReader.getBody}.
+	 * @returns {string}
+	 */
+	getBody() {
+		return this.#doc._readerGet(this.#quill, { card: this.#index });
+	}
+}
+
+// ── `quill.reader(doc)` — the schema-plane read front door ─────────────────────
+// The read twin of `quill.writer(doc)`, patched onto the same re-exported `Quill`
+// prototype (the `Quill === CoreQuill` identity invariant holds — this only adds
+// a method constructing the pure-JS reader, which owns no WASM handle).
+/**
+ * A {@link DocumentReader} binding this quill's schema to `doc` for interpreted
+ * reads — the read front door, mirroring core's `quill.reader(&doc)`. The returned
+ * reader holds both handles by reference and owns neither, so there is nothing to
+ * `free()`. Ephemeral by convention: bind, read, discard.
+ * @this {Quill}
+ * @param {Document} doc the document to read, held by reference (not owned)
+ * @returns {DocumentReader}
+ */
+Quill.prototype.reader = function reader(doc) {
+	return new DocumentReader(this, doc);
+};