@quillmark/wasm 0.124.0 → 0.126.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,14 +432,21 @@ 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.
 	 *
 	 * `today` reads as on {@link open}. An `options` key outside
 	 * {@link RenderOptions} rejects, `today` among them.
+	 *
+	 * A compile that traps (out of memory, a panic) rejects as
+	 * `runtime::backend_trapped`, the `WebAssembly.RuntimeError` on `cause`, as
+	 * does a trap in {@link LiveSession}'s `update` / `render` / `paint`, and a
+	 * `RangeError` or Firefox's `InternalError` for stack or memory exhaustion,
+	 * which engines raise for a stack overflow inside wasm. The build's state is then undefined: discard the
+	 * realm.
 	 */
 	render(quill: Quill, doc: Document, options?: RenderOptions, today?: string): Promise<RenderResult>;
 
@@ -494,22 +518,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 +645,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
@@ -635,12 +667,12 @@ export declare class DocumentWriter {
 	/**
 	 * 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
+	 * schema-conformed (a one-paragraph `richtext` rejects a multi-block result). Throws
 	 * `UnknownField` for a name the schema does not declare. Returns the
 	 * `Revised` receipt, its warnings at the field.
 	 *
 	 * The codec comes from the declared type: `richtext` diffs markdown, while
-	 * `plaintext` diffs the literal text and never imports markdown, so a
+	 * `text` 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, text: string): Revised;
@@ -660,8 +692,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 +723,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.
@@ -709,7 +741,7 @@ export declare class CardWriter {
  * A `Document` bound to its `Quill` for interpreted reads, from
  * {@link Quill.reader}: the read twin of {@link DocumentWriter}. One `get` reads
  * each field by its declared type — a richtext field to its markdown projection,
- * a plaintext field to its literal text, every other type verbatim.
+ * a text field to its literal text, every other type verbatim.
  *
  * The schema authority is the point: unlike the quill-free `Document.getStored`,
  * an undeclared name throws `UnknownField` rather than reading back `undefined`,

package/runtime/runtime.js

@@ -161,6 +161,53 @@ function quillmarkError(code, message, hint) {
 	return err;
 }
 
+/**
+ * `err` as `runtime::backend_trapped` when it is a `WebAssembly.RuntimeError`,
+ * or a `RangeError` (V8, JavaScriptCore) or `InternalError` (SpiderMonkey) for
+ * stack or memory exhaustion, which those engines raise for native stack
+ * overflow inside wasm; else unchanged.
+ * @param {unknown} err
+ * @returns {unknown}
+ */
+function backendTrap(err) {
+	const exhausted =
+		(err instanceof RangeError || (err instanceof Error && err.name === 'InternalError')) &&
+		/Maximum call stack|stack overflow|too much recursion|out of memory/i.test(err.message);
+	if (!(err instanceof WebAssembly.RuntimeError) && !exhausted) return err;
+	return Object.assign(
+		quillmarkError(
+			'runtime::backend_trapped',
+			`The backend build trapped (${err.message}); its state is now undefined.`,
+			'A render ran out of memory or stack, or panicked. Discard the realm before rendering again: terminate the Worker or restart the process. For untrusted input, cap the document size.'
+		),
+		{ cause: err }
+	);
+}
+
+/**
+ * Run `fn` on a transient clone of `docJson` in `mod`'s memory, then free it. A
+ * call that throws can leave the clone borrowed, so its `free()` throws too, and
+ * the error in flight is the one that propagates.
+ * @param {any} mod
+ * @param {string} docJson
+ * @param {(doc: any) => any} fn
+ * @returns {any}
+ */
+function withDocClone(mod, docJson, fn) {
+	const backendDoc = mod.Document.fromStored(docJson);
+	let result;
+	try {
+		result = fn(backendDoc);
+	} catch (err) {
+		try {
+			backendDoc.free();
+		} catch {}
+		throw err;
+	}
+	backendDoc.free();
+	return result;
+}
+
 /**
  * Throw on options that are not a plain object, or on a key of them, or of a
  * null-prototype object they inherit from, outside `known`. The JS twin of the
@@ -568,16 +615,15 @@ export class Engine {
 			? null
 			: quill.toTree();
 		const { mod, engine } = await this.#resolveBackend(backendId);
-		// The doc clone and `fn` share one try so the clone is freed even if a
-		// later step throws; the cached quill clone is intentionally not freed.
-		// `fn` MUST be synchronous: an async one would run against a freed clone.
-		const backendQuill = this.#cachedQuillClone(mod, backendId, quill, quillTree);
-		let backendDoc = null;
+		// The cached quill clone is intentionally not freed. `fn` MUST be
+		// synchronous: an async one would run against a freed doc clone.
 		try {
-			backendDoc = mod.Document.fromStored(docJson);
-			return fn({ mod, engine, quill: backendQuill, doc: backendDoc });
-		} finally {
-			backendDoc?.free();
+			const backendQuill = this.#cachedQuillClone(mod, backendId, quill, quillTree);
+			return withDocClone(mod, docJson, (backendDoc) =>
+				fn({ mod, engine, quill: backendQuill, doc: backendDoc })
+			);
+		} catch (err) {
+			throw backendTrap(err);
 		}
 	}
 
@@ -654,12 +700,11 @@ export class LiveSession {
 	 */
 	update(doc) {
 		requireLocalDoc(doc, 'session.update(doc)');
-		let backendDoc = null;
+		const docJson = doc.toStored();
 		try {
-			backendDoc = this.#mod.Document.fromStored(doc.toStored());
-			return this.#inner.update(backendDoc);
-		} finally {
-			backendDoc?.free();
+			return withDocClone(this.#mod, docJson, (backendDoc) => this.#inner.update(backendDoc));
+		} catch (err) {
+			throw backendTrap(err);
 		}
 	}
 
@@ -675,7 +720,11 @@ export class LiveSession {
 
 	/** @param {object} [options] */
 	render(options) {
-		return this.#inner.render(options ?? undefined);
+		try {
+			return this.#inner.render(options ?? undefined);
+		} catch (err) {
+			throw backendTrap(err);
+		}
 	}
 
 	/**
@@ -693,6 +742,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
@@ -735,7 +791,11 @@ export class LiveSession {
 	 * @param {number} scale
 	 */
 	paint(ctx, page, scale) {
-		this.#inner.paint(ctx, page, scale);
+		try {
+			this.#inner.paint(ctx, page, scale);
+		} catch (err) {
+			throw backendTrap(err);
+		}
 	}
 
 	free() {
@@ -767,14 +827,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 +915,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);