@quillmark/wasm 0.124.0 → 0.125.0

package/runtime/runtime.d.ts

@@ -142,6 +142,7 @@ export type {
 	Revised,
 	DocumentRevised,
 	AnnotatedMarkdown,
+	DocumentAnchor,
 	Imported,
 	Assoc,
 	IslandOp,
@@ -332,14 +333,30 @@ export interface FieldRegion {
 	rect: [number, number, number, number];
 	/**
 	 * The content slice this box covers: USV `[start, end)` into the field's
-	 * `Content` for content ink (one segment), absent for a scalar reference
-	 * site or widget. Consumers key segment highlights on it;
+	 * `Content` for content ink (one segment), absent for a scalar's or a
+	 * date's ink, a claim or a widget. Consumers key segment highlights on it;
 	 * {@link LiveSession.fieldBoxes} unions same-page segments for the
 	 * whole-field box.
 	 */
 	span?: [number, number];
 }
 
+/**
+ * One address a compiled document fills, and the region address a click
+ * reaches it through. A report, not a gate: a field a quill never prints is
+ * legitimately unreachable.
+ */
+export interface FieldCoverage {
+	/** The field's canonical `DocPath` address, as {@link FieldRegion.field}. */
+	field: string;
+	/**
+	 * The `DocPath` of the region reaching `field`: `field` itself, or the
+	 * nearest enclosing address a region carries (a row claim reaching its
+	 * cells, a whole array its elements). Absent where no click reaches it.
+	 */
+	coveredBy?: string;
+}
+
 /** Result of one render. */
 export interface RenderResult {
 	artifacts: Artifact[];
@@ -415,8 +432,8 @@ export declare class Engine {
 	 * soon as this call returns.
 	 *
 	 * {@link RenderResult.warnings} carries every `quill.validate(doc)` warning
-	 * but `validation::declined_construct`, which the compile raises as
-	 * `backend::declined_construct`, then the compile's own. The load's (parse
+	 * but `backend::declined_construct`, then the compile's own, a decline among
+	 * them. The load's (parse
 	 * and `conform::*`) stay on `doc.warnings`, and a revise's on its receipt.
 	 * A {@link LiveSession} carries the compile's alone: read
 	 * `quill.validate(doc)` beside it.
@@ -494,22 +511,27 @@ export declare class LiveSession {
 	 * Empty for backends that place no schema fields.
 	 *
 	 * `field` is **not** unique: a content field surfaces its **first placement**
-	 * as one {@link FieldRegion} per page that placement touches, a scalar
-	 * referenced at several plate sites surfaces each site, and tracked content
-	 * plus a `field:`-bound widget yields both, widget first. Group by `field`.
-	 * Later placements of one content value are not enumerated; {@link fieldAt}
-	 * still resolves clicks on them.
+	 * as one {@link FieldRegion} per page that placement touches, each claim on
+	 * a field surfaces its own, and tracked content plus a `field:`-bound widget
+	 * yields both, widget first. Group by `field`. Later placements of one value
+	 * are not enumerated; {@link fieldAt} still resolves clicks on them.
 	 */
 	regions(): FieldRegion[];
 	/**
 	 * The whole-field highlight boxes for `field` (a canonical `DocPath` address,
 	 * as {@link regions} keys): one union rect per page over the field's
 	 * `span`-bearing content segments, the union {@link regions} leaves derived.
-	 * **Content only**: a field placed solely as a scalar reference or a bound
-	 * widget carries no `span` and returns `[]`, its box being a single
+	 * **Content only**: a field placed solely as a scalar's ink, a claim or a
+	 * bound widget carries no `span` and returns `[]`, its box being a single
 	 * {@link regions} rect. Reflects the current compile.
 	 */
 	fieldBoxes(field: string): FieldRegion[];
+	/**
+	 * Every address the current compile fills that a reader could want to
+	 * click — each non-blank declared leaf, every roster member held or not —
+	 * with the region reaching it. Reflects the current compile.
+	 */
+	coverage(): FieldCoverage[];
 	/**
 	 * The schema field whose content is under a point on `page`: the canonical
 	 * `DocPath` address to focus in the editor, or `undefined` off any field's
@@ -616,15 +638,18 @@ export declare class DocumentWriter {
 	readonly document: Document;
 	/**
 	 * Typed-commit one main-card field (strict coerce, mismatch throws now).
-	 * Throws `UnknownField` for a name the schema does not declare.
+	 * Throws `UnknownField` for a name the schema does not declare. Returns a
+	 * `parse::dropped_construct` warning per construct a `richtext` markdown
+	 * string in the value dropped, at the string's path.
 	 */
-	set(name: string, value: unknown): void;
+	set(name: string, value: unknown): Diagnostic[];
 	/**
 	 * Typed-commit several main-card fields atomically: nothing is applied on
 	 * error (throws a {@link QuillmarkError} carrying one diagnostic per
 	 * offending field, including an `UnknownField` for each undeclared name).
+	 * Returns `set`'s warnings for every field, in batch order.
 	 */
-	setAll(fields: Record<string, unknown>): void;
+	setAll(fields: Record<string, unknown>): Diagnostic[];
 	/**
 	 * Revise the main body from markdown; anchors rebase. Returns the
 	 * `Revised` receipt, its warnings at `main.body`: a body carries no field
@@ -660,8 +685,8 @@ export declare class DocumentWriter {
 	 * body from optional markdown, and place it. `at` omitted appends, a number
 	 * inserts at that index. Transactional: a rejected field (throwing a per-field
 	 * diagnostic bundle) or an invalid kind, body, or position leaves the document
-	 * untouched. Returns the body import's `parse::dropped_construct` warnings,
-	 * anchored at the placed card's body.
+	 * untouched. Returns the fields' `parse::dropped_construct` warnings, then
+	 * the body import's, anchored under the placed card.
 	 */
 	addCard(kind: string, fields?: Record<string, unknown>, body?: string, at?: number): Diagnostic[];
 	/** Remove the composable card at `index`, returning it (or `undefined`). */
@@ -691,8 +716,8 @@ export declare class CardWriter {
 	 * index.
 	 */
 	readonly kind: string;
-	set(name: string, value: unknown): void;
-	setAll(fields: Record<string, unknown>): void;
+	set(name: string, value: unknown): Diagnostic[];
+	setAll(fields: Record<string, unknown>): Diagnostic[];
 	/**
 	 * Revise this card's body from markdown (edit semantics), returning the
 	 * `Revised` receipt, its warnings at the card's body.

package/runtime/runtime.js

@@ -693,6 +693,13 @@ export class LiveSession {
 		return this.#inner.fieldBoxes(field);
 	}
 
+	/**
+	 * @returns {import('./runtime.d.ts').FieldCoverage[]}
+	 */
+	coverage() {
+		return this.#inner.coverage();
+	}
+
 	/**
 	 * @param {number} page
 	 * @param {number} x
@@ -767,14 +774,14 @@ export class DocumentWriter {
 	/**
 	 * @param {string} name
 	 * @param {unknown} value
-	 * @returns {void}
+	 * @returns {import('../core/wasm.js').Diagnostic[]}
 	 */
 	set(name, value) {
 		return this.#doc._commitField(this.#quill, name, value);
 	}
 	/**
 	 * @param {Record<string, unknown>} fields
-	 * @returns {void}
+	 * @returns {import('../core/wasm.js').Diagnostic[]}
 	 */
 	setAll(fields) {
 		return this.#doc._commitFields(this.#quill, MAIN_CARD_ADDR, fields);
@@ -855,14 +862,14 @@ export class CardWriter {
 	/**
 	 * @param {string} name
 	 * @param {unknown} value
-	 * @returns {void}
+	 * @returns {import('../core/wasm.js').Diagnostic[]}
 	 */
 	set(name, value) {
 		return this.#doc._commitField(this.#quill, { card: this.#index, field: name }, value);
 	}
 	/**
 	 * @param {Record<string, unknown>} fields
-	 * @returns {void}
+	 * @returns {import('../core/wasm.js').Diagnostic[]}
 	 */
 	setAll(fields) {
 		return this.#doc._commitFields(this.#quill, { card: this.#index }, fields);