@quillmark/wasm 0.101.0 → 0.102.0

package/runtime/runtime.js

@@ -52,6 +52,10 @@
 // verbatim" case (`Quill === CoreQuill`) is the executable guard for this
 // invariant.
 //
+// It is also why the pre-init guard sits inside the generated builds instead
+// of here: nothing may stand between a consumer and these classes
+// (runtime/uninit.js).
+//
 // The identity is what makes `instanceof` the whole membership test: a handle
 // either belongs to this copy's classes or it belongs to another copy, and the
 // second is always a consumer bug. `Engine` is NOT duck-typed on its inputs; it
@@ -60,8 +64,16 @@
 // 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 default import is the core build's generated instantiation entry
+// (`--target web`); `init` below is the only thing that calls it.
+import initCore, { Quill, Document } from '../core/wasm.js';
+export { Quill, Document };
+// The wasm byte source, resolved per environment by package.json's `imports`
+// map: a pass-through in a browser (the glue fetches and streams the URL
+// itself), a `node:fs` read under Node, whose `fetch` rejects `file:` URLs.
+// Resolution-time, so `node:fs` never enters a browser graph.
+import { toModuleSource } from '#quillmark-env';
 // The document-free content codec: re-exported verbatim from the core build so
 // the runtime subpath exposes `exportMarkdown(body)` (the on-demand markdown
 // projection), `importMarkdown`, and the position-mapping pair (`rebase`,
@@ -72,6 +84,100 @@ export { importMarkdown, exportMarkdown, rebase, mapPos } from '../core/wasm.js'
 // segments instead of reverse-engineering the grammar.
 export { parseDocPath, formatDocPath } from '../core/wasm.js';
 
+// ── Initialization ──────────────────────────────────────────────────────────
+// The builds are `--target web`: they export their classes synchronously but
+// carry no wasm instance until something instantiates them. This module owns
+// that for core, behind one awaited gate; `Engine` owns it for the backends,
+// inside their lazy load, so a consumer never initializes a backend by hand.
+//
+// The gate is the shape the lazy-backend idiom (§ DEFAULT_BACKENDS) takes when
+// the surface it guards cannot be async: `Quill.fromTree` and `seedDocument`
+// are sync and static, so there is nowhere to hide an await except in front.
+//
+// Reaching core before the gate resolves is not a silent wrong answer: the
+// build is patched to throw `runtime::not_initialized` naming the fix
+// (runtime/uninit.js).
+
+/** The in-flight or settled core instantiation. The memo is the PROMISE, not a
+ * boolean, so concurrent callers share one instantiation instead of racing. */
+let coreInit;
+/** The source `init` was first called with; the conflict check reads it. */
+let coreInitSource;
+
+/**
+ * Instantiate the core WASM build. Call once at startup, before any other
+ * export is used; extra calls are free.
+ *
+ * ```js
+ * import { init, Quill, Engine } from '@quillmark/wasm';
+ * await init();
+ * ```
+ *
+ * Identical in every environment: in a browser the binary is fetched and
+ * streamed, under Node it is read off disk, and the call site is the same line.
+ *
+ * Idempotent and concurrency-safe: every call returns the same promise, so
+ * `await init()` at each of several entry points costs one instantiation. A
+ * failed init clears the memo, so a retry is possible.
+ *
+ * @param {import('../core/wasm.js').InitInput} [source] override the binary's
+ *   source (bytes, a `Response`, a `WebAssembly.Module`, a URL) for hosts that
+ *   route assets themselves or embed the binary. Pass it on the FIRST call; a
+ *   later call passing a *different* source throws `runtime::init_conflict`
+ *   rather than silently ignoring it. Passing the same value again is fine, so
+ *   several entry points may each `await init(BYTES)` against one constant.
+ * @returns {Promise<void>} resolves when the sync surface is usable
+ */
+export function init(source) {
+	if (coreInit) {
+		if (source !== undefined && source !== coreInitSource) {
+			throw quillmarkError(
+				'runtime::init_conflict',
+				'init(source): core is already initializing or initialized from a different source.',
+				'Pass a source on the first call only, or pass the same value every time.'
+			);
+		}
+		return coreInit;
+	}
+	coreInitSource = source;
+	// Assign before the first await so a synchronous second call sees the memo.
+	coreInit = instantiateCore(source).catch((err) => {
+		// Self-heal, as `#resolveBackend` does: one transient failure (a 404, an
+		// offline fetch) must not poison every later attempt.
+		coreInit = undefined;
+		coreInitSource = undefined;
+		throw err;
+	});
+	return coreInit;
+}
+
+/**
+ * @param {import('../core/wasm.js').InitInput | undefined} source
+ * @returns {Promise<void>}
+ */
+async function instantiateCore(source) {
+	// The literal `new URL(..., import.meta.url)` form: every bundler rewrites it
+	// into an emitted asset, and unbundled browsers and Node resolve it against
+	// the shipped package layout.
+	const resolved = await toModuleSource(
+		source ?? new URL('../core/wasm_bg.wasm', import.meta.url)
+	);
+	try {
+		await initCore({ module_or_path: resolved });
+	} catch (cause) {
+		throw Object.assign(
+			quillmarkError(
+				'runtime::init_failed',
+				`init(): could not load or instantiate the core WASM binary: ${
+					/** @type {any} */ (cause)?.message ?? cause
+				}`,
+				"The binary ships beside the package files; check the network tab for a 404 or an HTML response. Under Vite's dev server, dependency pre-bundling moves the package away from it: add optimizeDeps: { exclude: ['@quillmark/wasm'] }."
+			),
+			{ cause }
+		);
+	}
+}
+
 // ── The main-card address ───────────────────────────────────────────────────
 /**
  * The main card's address: the default target of the card-scoped verbs
@@ -143,7 +249,7 @@ function quillmarkError(code, message, hint) {
 // front-run it with a `QuillmarkError` that names both.
 //
 // They also cover the seams with NO `_assertClass` to front-run: `Engine` and
-// `LiveSession.apply` cross into backend memory as data (`toTree`/`toJson`), so
+// `LiveSession.update` cross into backend memory as data (`toTree`/`toJson`), so
 // a foreign handle there would silently work, at the price of the round-trip
 // above and a quill clone cache split per copy.
 //
@@ -391,11 +497,51 @@ export function isUnknownIsland(island) {
 	return typeof island?.type === 'string' && !KNOWN_ISLAND_TYPES.has(island.type);
 }
 
+/**
+ * Build a `load` thunk: dynamic-import a backend build, then instantiate it.
+ *
+ * Under `--target web` a freshly imported build is inert (the import resolves
+ * before there is a wasm instance behind the classes), so instantiation is part
+ * of loading and the consumer never sees it. Memoized at MODULE scope, not per
+ * `Engine`: two engines issuing their first render concurrently must share one
+ * instantiation, and the generated entry's own `wasm !== undefined` guard only
+ * catches a call that arrives after one finished, not one already in flight.
+ *
+ * @param {string} id backend id, for the failure message
+ * @param {() => Promise<any>} importThunk the dynamic `import()`
+ * @param {() => URL} wasmUrl the build's binary, resolved at call time
+ * @returns {() => Promise<any>} resolves to a ready-to-use module
+ */
+function backendLoad(id, importThunk, wasmUrl) {
+	/** @type {Promise<any> | undefined} */
+	let loaded;
+	return () =>
+		(loaded ??= (async () => {
+			const mod = await importThunk();
+			await mod.default({ module_or_path: await toModuleSource(wasmUrl()) });
+			return mod;
+		})().catch((cause) => {
+			// Self-heal, as core's `init` does.
+			loaded = undefined;
+			throw Object.assign(
+				quillmarkError(
+					'runtime::backend_load_failed',
+					`Engine: could not load the '${id}' backend: ${
+						/** @type {any} */ (cause)?.message ?? cause
+					}`,
+					'The backend binary ships beside the package files; check the network tab for a 404 or an HTML response.'
+				),
+				{ cause }
+			);
+		}));
+}
+
 // Backend builds are NEVER statically imported here: that would pull a
 // multi-MB binary into the eager graph and defeat lazy loading. Each entry is a
-// DESCRIPTOR: `load` is a thunk returning a dynamic `import()` (a backend's
-// chunk is fetched only when something actually renders against that backend),
-// and `formats`/`canvas` are the REQUIRED static capability manifest so the
+// DESCRIPTOR: `load` is a thunk that dynamically imports a backend's chunk and
+// instantiates it, so the binary is fetched only when something actually renders
+// against that backend and is ready to use when the promise resolves;
+// `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 each backend's Rust source (`crates/backends/<id>/src/lib.rs`
@@ -405,12 +551,20 @@ export function isUnknownIsland(island) {
 // format list includes a visual-page format (`svg` or `png`).
 const DEFAULT_BACKENDS = {
 	typst: {
-		load: () => import('../backends/typst/wasm.js'),
+		load: backendLoad(
+			'typst',
+			() => import('../backends/typst/wasm.js'),
+			() => new URL('../backends/typst/wasm_bg.wasm', import.meta.url)
+		),
 		formats: ['pdf', 'svg', 'png'], // crates/backends/typst/src/lib.rs SUPPORTED_FORMATS
 		canvas: true // has svg/png → formats_support_canvas == true
 	},
 	pdfform: {
-		load: () => import('../backends/pdfform/wasm.js'),
+		load: backendLoad(
+			'pdfform',
+			() => import('../backends/pdfform/wasm.js'),
+			() => new URL('../backends/pdfform/wasm_bg.wasm', import.meta.url)
+		),
 		// crates/backends/pdfform/src/lib.rs SUPPORTED_FORMATS == [Pdf, Svg, Png]
 		formats: ['pdf', 'svg', 'png'],
 		canvas: true // has svg/png → formats_support_canvas == true
@@ -475,6 +629,10 @@ export class Engine {
 	 *   `supportedFormats`/`supportsCanvas` always free (no binary load, no quill
 	 *   clone). Malformed entries throw here, at construction. The default
 	 *   registry maps `"typst"` to the bundled Typst build.
+	 *
+	 *   `load` resolves to a READY module: a registrant shipping its own
+	 *   `--target web` build instantiates inside the thunk. More than one
+	 *   `Engine` may call it, so memoize (the built-ins do, at module scope).
 	 */
 	constructor(options) {
 		const merged = { ...DEFAULT_BACKENDS, ...(options?.backends ?? {}) };
@@ -641,8 +799,8 @@ export class Engine {
 	}
 
 	/**
-	 * Open a live render session (canvas preview / per-page paint / `apply`).
-	 * The session is self-contained (it retains what it needs for `apply`), so
+	 * Open a live render session (canvas preview / per-page paint / `update`).
+	 * The session is self-contained (it retains what it needs for `update`), 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
@@ -693,15 +851,15 @@ export class Engine {
 
 /**
  * Thin wrapper over a backend's live render session. Reads serve the current
- * compile; `apply(doc)` recompiles in place (transactional: on throw, reads
+ * compile; `update(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`
+ * opened from have already been freed: the session retains what `update`
  * 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`.
+ * `update`.
  *
  * `paint` writes a COMPLETE page raster (all content visible, no caller-side
  * compositing) for every backend that supports canvas (Typst rasterizes
@@ -709,8 +867,8 @@ export class Engine {
  */
 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
+	 * @param {{ pageCount: number, backendId: string, supportsCanvas: boolean, warnings: any[], update: 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 `update` documents in its linear memory
 	 */
 	constructor(inner, mod) {
 		this.#inner = inner;
@@ -726,12 +884,12 @@ export class LiveSession {
 	 * @param {Document} doc
 	 * @returns {import('./runtime.d.ts').ChangeSet}
 	 */
-	apply(doc) {
-		requireLocalDoc(doc, 'session.apply(doc)');
+	update(doc) {
+		requireLocalDoc(doc, 'session.update(doc)');
 		let backendDoc = null;
 		try {
 			backendDoc = this.#mod.Document.fromJson(doc.toJson());
-			return this.#inner.apply(backendDoc);
+			return this.#inner.update(backendDoc);
 		} finally {
 			backendDoc?.free();
 		}
@@ -907,14 +1065,15 @@ export class DocumentWriter {
 		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.
+	 * Revise the main body from markdown (edit semantics: surviving anchors
+	 * rebase), returning the text {@link Delta}. The content lane's `revise`
+	 * reached through the writer: a body carries no field schema, so there is
+	 * nothing for a typed verb to type, and the receipt is the content lane's.
 	 * @param {string} markdown
-	 * @returns {void}
+	 * @returns {import('../core/wasm.js').Delta}
 	 */
-	setBody(markdown) {
-		this.#doc.revise({}, markdown);
+	reviseBody(markdown) {
+		return this.#doc.revise({}, markdown);
 	}
 	/**
 	 * Revise the content main-card field `name` from authored text: typed *and*
@@ -1033,13 +1192,13 @@ export class CardWriter {
 		return this.#doc._commitFields(this.#quill, { card: this.#index }, fields);
 	}
 	/**
-	 * Set this card's body from markdown (edit semantics), discarding the delta:
-	 * the card twin of {@link DocumentWriter.setBody}.
+	 * Revise this card's body from markdown (edit semantics), returning the text
+	 * {@link Delta}: the card twin of {@link DocumentWriter.reviseBody}.
 	 * @param {string} markdown
-	 * @returns {void}
+	 * @returns {import('../core/wasm.js').Delta}
 	 */
-	setBody(markdown) {
-		this.#doc.revise({ card: this.#index }, markdown);
+	reviseBody(markdown) {
+		return this.#doc.revise({ card: this.#index }, markdown);
 	}
 	/**
 	 * Revise the content field `name` on this card from authored text: typed *and*
@@ -1084,7 +1243,7 @@ Quill.prototype.writer = function writer(doc) {
 // 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
+// `bodyMarkdown`. Like the writer classes these hold the caller's handles by
 // reference, own no WASM object, and have nothing to `free()`.
 
 /**
@@ -1115,7 +1274,7 @@ export class DocumentReader {
 	 * 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
+	 * declare, `FieldDecode` 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}
@@ -1124,14 +1283,14 @@ export class DocumentReader {
 		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
+	 * Read the content field at `addr` as its canonical `Content`: the
+	 * `Content` 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
+	 * so a field the writer committed as a `Content` 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.
+	 * document was built. An absent `addr.field` reads the body `Content`.
 	 * `undefined` for an absent field; throws `UnknownField`, `FieldNotContent`
-	 * for a type that is not a content leaf, `FieldRichtextDecode` for an undecodable
+	 * for a type that is not a content leaf, `FieldDecode` 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}
@@ -1144,7 +1303,7 @@ export class DocumentReader {
 	 * format fact, not a schema fact). Equivalent to `get({})`.
 	 * @returns {string}
 	 */
-	getBody() {
+	bodyMarkdown() {
 		return this.#doc._readerGet(this.#quill, {});
 	}
 	/**
@@ -1163,7 +1322,7 @@ export class DocumentReader {
 
 /**
  * A single composable card bound to its {@link Quill} for typed reads, from
- * {@link DocumentReader.card}. Same `get` / `getBody` verbs as
+ * {@link DocumentReader.card}. Same `get` / `bodyMarkdown` verbs as
  * {@link DocumentReader}, reading the card at its bound index.
  */
 export class CardReader {
@@ -1206,7 +1365,7 @@ export class CardReader {
 	}
 	/**
 	 * Read the content field `name` on this card as its canonical `Content`
-	 * corpus: the card twin of {@link DocumentReader.getContent}.
+	 * `Content`: the card twin of {@link DocumentReader.getContent}.
 	 * @param {string} name
 	 * @returns {import('../core/wasm.js').Content | undefined}
 	 */
@@ -1214,10 +1373,10 @@ export class CardReader {
 		return this.#doc._readerGetContent(this.#quill, { card: this.#index, field: name });
 	}
 	/**
-	 * This card's body markdown: the card twin of {@link DocumentReader.getBody}.
+	 * This card's body markdown: the card twin of {@link DocumentReader.bodyMarkdown}.
 	 * @returns {string}
 	 */
-	getBody() {
+	bodyMarkdown() {
 		return this.#doc._readerGet(this.#quill, { card: this.#index });
 	}
 }

package/runtime/uninit.js

@@ -0,0 +1,57 @@
+// The pre-initialization sentinel.
+//
+// wasm-bindgen's `--target web` glue holds its instance exports in one
+// module-level binding (`let wasmModule, wasm;`) that every generated path
+// reads through: constructors, statics, methods, free functions. Until
+// instantiation assigns it, that binding is `undefined`, so a consumer who
+// skipped `await init()` gets `Cannot read properties of undefined (reading
+// 'quill_fromTree')` from inside generated code.
+//
+// `scripts/build-wasm.sh` (`guard_wasm_js`) patches the binding to start as
+// this sentinel, so the same access throws a `QuillmarkError` naming the cause
+// and the fix. The patch is three line edits per variant, shape-asserted before
+// it applies; the logic lives here rather than inside the awk program.
+//
+// It sits in the generated build, not in the runtime layer, because the
+// canonical invariant (`runtime.js` § "CANONICAL INVARIANT") requires the root
+// to re-export `Quill`/`Document` VERBATIM: no wrapper, subclass, or proxy may
+// stand between a consumer and those classes. Prototype patching preserves
+// identity but cannot cover a public constructor (`new Document(...)`) without
+// wrapping the class. The binding they all read through is the one place that
+// covers every path and touches no class.
+
+/**
+ * A stand-in for a wasm build's exports that throws on use. Every property read
+ * throws except the marker the patched init guards test, and `then`,
+ * `constructor`, and symbols, which return `undefined`: an incidental `await`
+ * or `util.inspect` reports nothing rather than throwing somewhere unrelated to
+ * the cause.
+ *
+ * @param {string} message what a consumer sees when they reach a build early
+ * @param {string} hint the fix, as a `Diagnostic.hint`
+ * @returns {any} the sentinel
+ */
+export function uninitSentinel(message, hint) {
+	return new Proxy(
+		{},
+		{
+			get(_target, prop) {
+				if (prop === UNINIT) return true;
+				if (prop === 'then' || prop === 'constructor' || typeof prop === 'symbol') {
+					return undefined;
+				}
+				const err = /** @type {any} */ (new Error(message));
+				err.diagnostics = [
+					{ severity: 'error', code: 'runtime::not_initialized', message, hint }
+				];
+				throw err;
+			}
+		}
+	);
+}
+
+/**
+ * The marker the patched `if (wasm !== undefined)` guards read to tell a
+ * sentinel from real instance exports, which never carry it.
+ */
+export const UNINIT = '__quillmarkUninit';