@quillmark/wasm 0.92.1 → 0.94.0

package/runtime/runtime.js

@@ -52,7 +52,17 @@
 // (it is) so it tolerates handles from any core instance. The `runtime.test.js`
 // "re-exports the internal core build classes verbatim" case
 // (`Quill === CoreQuill`) is the executable guard for this invariant.
-export { Quill, Document, init } from '../core/wasm.js';
+//
+// Imported (not bare re-exported) so `Quill` is a local binding this module can
+// augment — `quill.writer(doc)` is patched onto its prototype below. The
+// 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 runtime subpath exposes `exportMarkdown(body)` (the on-demand markdown
+// projection that replaces the eager `bodyMarkdown`), `importMarkdown`, and the
+// position-mapping pair (`rebase`, `mapPos`).
+export { importMarkdown, exportMarkdown, rebase, mapPos } from '../core/wasm.js';
 
 /**
  * Narrow an unknown caught value to a `QuillmarkError` — the error every
@@ -79,15 +89,22 @@ export function isQuillmarkError(e) {
 // and `formats`/`canvas` are the REQUIRED static capability manifest so the
 // cheap probes (`supportedFormats`/`supportsCanvas`) ALWAYS answer without
 // loading the binary or cloning the quill. The manifest values are verified
-// against the backend's Rust source (`crates/backends/typst/src/lib.rs`
-// `SUPPORTED_FORMATS` and `supports_canvas`) and pinned by the `runtime.test.js`
-// drift-guard test, which renders once and asserts the loaded backend reports
-// the same list.
+// against each backend's Rust source (`crates/backends/<id>/src/lib.rs`
+// `SUPPORTED_FORMATS`) and pinned by the `runtime.test.js` drift-guard test,
+// which renders once and asserts the loaded backend reports the same list.
+// `canvas` mirrors `quillmark_core::formats_support_canvas`: true iff the
+// format list includes a visual-page format (`svg` or `png`).
 const DEFAULT_BACKENDS = {
 	typst: {
 		load: () => import('../backends/typst/wasm.js'),
 		formats: ['pdf', 'svg', 'png'], // crates/backends/typst/src/lib.rs SUPPORTED_FORMATS
-		canvas: true // crates/backends/typst/src/lib.rs supports_canvas() == true
+		canvas: true // has svg/png → formats_support_canvas == true
+	},
+	pdfform: {
+		load: () => import('../backends/pdfform/wasm.js'),
+		// crates/backends/pdfform/src/lib.rs SUPPORTED_FORMATS == [Pdf, Svg, Png]
+		formats: ['pdf', 'svg', 'png'],
+		canvas: true // has svg/png → formats_support_canvas == true
 	}
 };
 
@@ -210,16 +227,18 @@ export class Engine {
 
 	/**
 	 * Get (or materialize-and-cache) the backend-memory `Quill` clone for
-	 * `quill` under `backendId`. On a cache miss the clone is built via
-	 * `toTree`→`fromTree` and stored in the per-backend `WeakMap` keyed on the
+	 * `quill` under `backendId`. On a cache miss the clone is built from `tree`
+	 * — the caller's pre-await `toTree()` snapshot; the canonical handle may be
+	 * freed by now — and stored in the per-backend `WeakMap` keyed on the
 	 * canonical `Quill` instance, so a later call with the same instance reuses
 	 * it (the hot-path fix: no re-serialize / re-copy / re-validate per call).
 	 * @param {any} mod the backend build module
 	 * @param {string} backendId
-	 * @param {{ toTree(): Map<string, Uint8Array> }} quill
+	 * @param {object} quill the canonical instance (cache key only)
+	 * @param {Map<string, Uint8Array> | null} tree pre-await snapshot; `null` on a cache hit
 	 * @returns {any} the backend-memory quill clone
 	 */
-	#cachedQuillClone(mod, backendId, quill) {
+	#cachedQuillClone(mod, backendId, quill, tree) {
 		let perQuill = this.#quillClones.get(backendId);
 		if (!perQuill) {
 			perQuill = new WeakMap();
@@ -227,7 +246,7 @@ export class Engine {
 		}
 		let backendQuill = perQuill.get(quill);
 		if (!backendQuill) {
-			backendQuill = mod.Quill.fromTree(quill.toTree());
+			backendQuill = mod.Quill.fromTree(tree);
 			perQuill.set(quill, backendQuill);
 		}
 		return backendQuill;
@@ -238,6 +257,13 @@ export class Engine {
 	 * memory and run `fn` against the backend engine. Only `render`/`open` call
 	 * this, so `doc` is always present.
 	 *
+	 * OWNERSHIP WINDOW: both caller handles are snapshotted (`doc.toJson()`, and
+	 * `quill.toTree()` on a clone-cache miss) BEFORE the first await. The backend
+	 * load below is a real suspension point — a multi-MB `import()` on first
+	 * render — so reading the handles after it would race a caller that
+	 * `free()`s them as soon as this call returns its promise ("null pointer
+	 * passed to rust"). The snapshot makes that natural calling pattern correct.
+	 *
 	 * Clone lifetimes differ by design: the `doc` clone is TRANSIENT — freed in
 	 * the `finally` of every call. The `quill` clone is CACHED per (engine,
 	 * backend, canonical quill instance) and is NOT freed here; a `Quill`
@@ -251,6 +277,8 @@ export class Engine {
 	 * @param {(ctx: { mod: any, engine: any, quill: any, doc: any }) => any} fn
 	 */
 	async #withClones(backendId, quill, doc, fn) {
+		const docJson = doc.toJson();
+		const quillTree = this.#quillClones.get(backendId)?.has(quill) ? null : quill.toTree();
 		const { mod, engine } = await this.#resolveBackend(backendId);
 		// The quill clone is cached (see #cachedQuillClone); only the per-call doc
 		// clone is transient. Bring the doc clone + `fn` under one try so the doc
@@ -258,10 +286,10 @@ export class Engine {
 		// rejecting a cross-version DTO). The cached quill clone is intentionally
 		// NOT freed here. `fn` MUST be synchronous — the doc clone is freed as soon
 		// as it returns, so an async `fn` would have it freed mid-flight.
-		const backendQuill = this.#cachedQuillClone(mod, backendId, quill);
+		const backendQuill = this.#cachedQuillClone(mod, backendId, quill, quillTree);
 		let backendDoc = null;
 		try {
-			backendDoc = mod.Document.fromJson(doc.toJson());
+			backendDoc = mod.Document.fromJson(docJson);
 			return fn({ mod, engine, quill: backendQuill, doc: backendDoc });
 		} finally {
 			backendDoc?.free();
@@ -270,6 +298,8 @@ export class Engine {
 
 	/**
 	 * Render `doc` against `quill` in one shot, returning a `RenderResult`.
+	 * Both handles are read synchronously before the first await, so the caller
+	 * may `free()` them as soon as this call returns.
 	 * @param {Quill} quill
 	 * @param {Document} doc
 	 * @param {object} [options] render options (`{ format, ppi, pages, producer }`)
@@ -282,23 +312,22 @@ export class Engine {
 	}
 
 	/**
-	 * Open an iterative render session (for canvas preview / per-page paint).
-	 * The session is a self-contained compiled snapshot, so the transient quill
-	 * and document clones are freed before this returns; the caller owns the
-	 * returned session and must `.free()` it.
-	 * @experimental Ships ahead of its first production consumer (the designed
-	 * canvas live-preview path); the session/paint surface may change in any
-	 * 0.x release. `render()` is the stable path.
+	 * Open a live render session (canvas preview / per-page paint / `apply`).
+	 * The session is self-contained (it retains what it needs for `apply`), so
+	 * the transient quill and document clones are freed before this returns;
+	 * the caller owns the returned session and must `.free()` it. The `quill`
+	 * and `doc` handles are read synchronously before the first await, so the
+	 * caller may `free()` them as soon as this call returns.
 	 * @param {Quill} quill
 	 * @param {Document} doc
-	 * @returns {Promise<RenderSession>}
+	 * @returns {Promise<LiveSession>}
 	 */
 	async open(quill, doc) {
 		return this.#withClones(
 			quill.backendId,
 			quill,
 			doc,
-			({ engine, quill: q, doc: d }) => new RenderSession(engine.open(q, d))
+			({ mod, engine, quill: q, doc: d }) => new LiveSession(engine.open(q, d), mod)
 		);
 	}
 
@@ -317,9 +346,13 @@ export class Engine {
 	}
 
 	/**
-	 * Whether `quill`'s backend can paint sessions to a canvas. Same ALWAYS-free
-	 * probe as `supportedFormats`: answered from the descriptor's required
-	 * `canvas` manifest, no load and no clone.
+	 * Whether `quill`'s BACKEND can paint sessions to a canvas — a pre-session
+	 * ESTIMATE, not a fact about any particular compile. Same ALWAYS-free probe
+	 * as `supportedFormats`: answered from the descriptor's required `canvas`
+	 * manifest, no load and no clone. A specific compile can still refuse to
+	 * paint (e.g. a 0-page document), so this can answer `true` while the
+	 * resulting `LiveSession.supportsCanvas` answers `false` — gate mounting a
+	 * canvas UI on this, gate the actual `paint` call on the session's getter.
 	 * @param {Quill} quill
 	 * @returns {Promise<boolean>}
 	 */
@@ -330,15 +363,49 @@ export class Engine {
 }
 
 /**
- * Thin wrapper over a backend's iterative render session. Holds the compiled
- * snapshot; the quill/document it was opened from have already been freed.
+ * Thin wrapper over a backend's live render session. Reads serve the current
+ * compile; `apply(doc)` recompiles in place (transactional: on throw, reads
+ * keep serving the last-good compile). The quill/document clones it was
+ * opened from have already been freed — the session retains what `apply`
+ * needs.
+ *
+ * Geometry reads (`regions`, `positionAt`, `locate`) resolve against the
+ * current compile; anchoring a caret or selection across edits is the editor's
+ * job (its own transaction mapping) — re-read geometry after each committed
+ * `apply`.
+ *
+ * `paint` writes a COMPLETE page raster — all content visible, no caller-side
+ * compositing — for every backend that supports canvas (Typst rasterizes
+ * natively; pdfform rasterizes its pre-flattened page). See `runtime.d.ts`.
  */
-export class RenderSession {
-	/** @param {import('../backends/typst/wasm').RenderSession} inner */
-	constructor(inner) {
+export class LiveSession {
+	/**
+	 * @param {{ pageCount: number, backendId: string, supportsCanvas: boolean, warnings: any[], apply: Function, render: Function, regions: Function, pageSize: Function, paint: Function, free: Function }} inner backend-build LiveSession (typst or pdfform)
+	 * @param {{ Document: { fromJson(json: string): any } }} mod the session's backend build, used to materialize `apply` documents in its linear memory
+	 */
+	constructor(inner, mod) {
 		this.#inner = inner;
+		this.#mod = mod;
 	}
 	#inner;
+	#mod;
+
+	/**
+	 * Recompile the session against `doc` — the edit verb of a live preview.
+	 * Transactional: on throw every read keeps serving the last-good compile.
+	 * On success reads serve the new compile; repaint `dirtyPages ∩ visible`.
+	 * @param {Document} doc
+	 * @returns {import('./runtime.d.ts').ChangeSet}
+	 */
+	apply(doc) {
+		let backendDoc = null;
+		try {
+			backendDoc = this.#mod.Document.fromJson(doc.toJson());
+			return this.#inner.apply(backendDoc);
+		} finally {
+			backendDoc?.free();
+		}
+	}
 
 	get pageCount() {
 		return this.#inner.pageCount;
@@ -346,6 +413,16 @@ export class RenderSession {
 	get backendId() {
 		return this.#inner.backendId;
 	}
+	/**
+	 * `true` iff `paint`/`pageSize` will succeed for THIS compile — the
+	 * authoritative answer, derived from the session's canvas seam, so it can
+	 * never disagree with what `paint` actually does. This can be `false` even
+	 * when `Engine.supportsCanvas` answered `true` for the same `quill` (that
+	 * probe is a pre-session backend estimate; e.g. a canvas-capable backend
+	 * compiled to a 0-page document has nothing to paint). Re-check this getter
+	 * after `open()` rather than relying on the engine hint alone.
+	 * @returns {boolean}
+	 */
 	get supportsCanvas() {
 		return this.#inner.supportsCanvas;
 	}
@@ -358,12 +435,75 @@ export class RenderSession {
 		return this.#inner.render(options ?? undefined);
 	}
 
+	/**
+	 * Schema-field geometry for this compiled session — one region per
+	 * schema-bound field, keyed on its quill schema field path. A session-level
+	 * query (no render); read it to place field overlays / cross-navigation over
+	 * a `paint`-ed canvas.
+	 * @returns {import('./runtime.d.ts').FieldRegion[]}
+	 */
+	regions() {
+		return this.#inner.regions();
+	}
+
+	/**
+	 * The whole-field highlight boxes for `field` — one union rect per page,
+	 * over the field's `span`-bearing content segments. Owns the union
+	 * `regions()` leaves derived (span-filter + per-page union), so a "highlight
+	 * the focused field" consumer stops reimplementing it. Content only: a field
+	 * placed solely as a scalar reference or a bound widget returns `[]` — its
+	 * box is a single `regions()` rect.
+	 * @param {string} field
+	 * @returns {import('./runtime.d.ts').FieldRegion[]}
+	 */
+	fieldBoxes(field) {
+		return this.#inner.fieldBoxes(field);
+	}
+
+	/**
+	 * The schema field whose content is under a point on `page` — the forward
+	 * (click → field) direction, resolving *every* placement, not just the first
+	 * that `regions` enumerates. `x`/`y` are PDF points with a bottom-left origin
+	 * (the `FieldRegion.rect` space). See `runtime.d.ts` for the click-to-point
+	 * inverse transform.
+	 * @param {number} page
+	 * @param {number} x
+	 * @param {number} y
+	 * @returns {string | undefined}
+	 */
+	fieldAt(page, x, y) {
+		return this.#inner.fieldAt(page, x, y);
+	}
+
+	/**
+	 * @param {number} page
+	 * @param {number} x
+	 * @param {number} y
+	 * @returns {import('./runtime.d.ts').CorpusHit | undefined}
+	 */
+	positionAt(page, x, y) {
+		return this.#inner.positionAt(page, x, y);
+	}
+
+	/**
+	 * @param {string} field
+	 * @param {number} pos
+	 * @returns {import('./runtime.d.ts').FieldRegion | undefined}
+	 */
+	locate(field, pos) {
+		return this.#inner.locate(field, pos);
+	}
+
 	/** @param {number} page */
 	pageSize(page) {
 		return this.#inner.pageSize(page);
 	}
 
 	/**
+	 * Paint `page` into a 2D canvas context. The painted raster is COMPLETE —
+	 * all page content visible, no caller-side compositing — for both the Typst
+	 * and pdfform backends. See `runtime.d.ts` for the DPR/clamp math and the
+	 * region-overlay coordinate transform.
 	 * @param {CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D} ctx
 	 * @param {number} page
 	 * @param {object} [options]
@@ -376,3 +516,188 @@ export class RenderSession {
 		this.#inner.free();
 	}
 }
+
+// ── Typed-writer sugar: bind the quill once ─────────────────────────────────
+// Rust exposes `quill.writer(&mut doc)` so a caller issues bare `set` / `set_all`
+// without threading the schema per write. The WASM `commit*` verbs can't borrow
+// like that — a `Document` carries only a `$quill` REFERENCE, not the resolved
+// schema, so each `commit*` method takes the `quill` handle as its first
+// argument. These pure-JS classes restore the Rust ergonomics: bind `quill` +
+// `doc` once, then issue `set` / `setAll` / `card(i).set`.
+//
+// They hold JS references to the caller's EXISTING handles — no WASM object of
+// their own, no `free()` burden, no second owner of either handle — and every
+// write delegates straight to the underlying `commit*` verb: a schema field is
+// 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.
+
+/**
+ * A {@link Document} bound to its {@link Quill} for typed writes — the JS twin
+ * of Rust's `quill.writer(&mut doc)`. Writes 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 DocumentWriter {
+	#quill;
+	#doc;
+	/**
+	 * @param {Quill} quill the schema source for typed commits
+	 * @param {Document} doc the document to mutate, held by reference (not owned)
+	 */
+	constructor(quill, doc) {
+		this.#quill = quill;
+		this.#doc = doc;
+	}
+	/** The bound document — the same instance passed in, mutated in place. */
+	get document() {
+		return this.#doc;
+	}
+	/**
+	 * Typed-commit one main-card field (strict coerce, mismatch throws now).
+	 * Throws `UnknownField` for a name the schema does not declare. See
+	 * `Document.commitField`.
+	 * @param {string} name
+	 * @param {unknown} value
+	 * @returns {void}
+	 */
+	set(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`.
+	 * @param {Record<string, unknown>} fields
+	 * @returns {void}
+	 */
+	setAll(fields) {
+		return this.#doc.commitFields(this.#quill, 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.
+	 * @param {string} markdown
+	 * @returns {void}
+	 */
+	setBody(markdown) {
+		this.#doc.revise({}, 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`.
+	 * @param {string} kind
+	 * @param {Record<string, unknown>} [fields]
+	 * @param {string} [body]
+	 * @returns {void}
+	 */
+	addCard(kind, fields, body) {
+		return this.#doc.addCard(this.#quill, kind, fields, body);
+	}
+	/**
+	 * Remove the composable card at `index`, returning it (or `undefined` if the
+	 * index is out of range) — the tier-1 spelling of `Document.removeCard`.
+	 * @param {number} index
+	 * @returns {import('../core/wasm.js').Card | undefined}
+	 */
+	removeCard(index) {
+		return this.#doc.removeCard(index);
+	}
+	/**
+	 * A {@link CardWriter} bound to the composable card at `index`. Index
+	 * validity is checked lazily by the underlying write (it throws
+	 * `IndexOutOfRange` at commit time), so constructing one never throws.
+	 *
+	 * 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.
+	 * @param {number} index
+	 * @returns {CardWriter}
+	 */
+	card(index) {
+		return new CardWriter(this.#quill, this.#doc, index);
+	}
+}
+
+/**
+ * A single composable card bound to its {@link Quill} for typed writes, from
+ * {@link DocumentWriter.card}. Same `set` / `setAll` verbs as
+ * {@link DocumentWriter}, targeting the card at its bound index.
+ */
+export class CardWriter {
+	#quill;
+	#doc;
+	#index;
+	/**
+	 * @param {Quill} quill the schema source
+	 * @param {Document} doc the document to mutate, 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;
+	}
+	/**
+	 * 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.
+	 * @param {string} name
+	 * @param {unknown} value
+	 * @returns {void}
+	 */
+	set(name, value) {
+		return this.#doc.commitCardField(this.#quill, this.#index, 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.
+	 * @param {Record<string, unknown>} fields
+	 * @returns {void}
+	 */
+	setAll(fields) {
+		return this.#doc.commitCardFields(this.#quill, this.#index, fields);
+	}
+	/**
+	 * Set this card's body from markdown (edit semantics), discarding the delta —
+	 * the card twin of {@link DocumentWriter.setBody}.
+	 * @param {string} markdown
+	 * @returns {void}
+	 */
+	setBody(markdown) {
+		this.#doc.revise({ card: this.#index }, markdown);
+	}
+}
+
+// ── `quill.writer(doc)` — the typed front door ──────────────────────────────
+// The tier-1 default: 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`
+// stays true (the identity invariant above); this only adds a method that
+// constructs the pure-JS writer, which owns no WASM handle.
+/**
+ * A {@link DocumentWriter} binding this quill's schema to `doc` for typed
+ * writes — the documented front door. The returned writer holds both handles by
+ * reference and owns neither, so there is nothing to `free()`. Ephemeral by
+ * convention: bind, write, discard.
+ * @this {Quill}
+ * @param {Document} doc the document to mutate, held by reference (not owned)
+ * @returns {DocumentWriter}
+ */
+Quill.prototype.writer = function writer(doc) {
+	return new DocumentWriter(this, doc);
+};