@quillmark/wasm 0.102.0 → 0.104.0

package/runtime/runtime.js

@@ -2,15 +2,17 @@
 //
 // @quillmark/wasm/runtime: the canonical consumer API.
 //
-// Consumers import `Quill`, `Document`, and `Engine` from here and never touch
-// the build-specific subpaths. The package ships multiple WASM binaries with
-// SEPARATE linear memories: a Typst-less `core` build (small, eager) that is
-// the canonical home of `Quill`/`Document`, and one private backend binary per
-// backend (`backends/typst/` today; more later) that carries an engine. A
-// handle from one memory cannot be used by another. This module hides that seam
-// and is exposed at the package root (`@quillmark/wasm`):
+// Consumers reach `Quill` and `Document` through `await init()` and `Engine`
+// as a static export, and never touch the build-specific subpaths. The package
+// ships multiple WASM binaries with SEPARATE linear memories: a Typst-less
+// `core` build (small, eager) that is the canonical home of `Quill`/`Document`,
+// and one private backend binary per backend (`backends/typst/` today; more
+// later) that carries an engine. A handle from one memory cannot be used by
+// another. This module hides that seam and is exposed at the package root
+// (`@quillmark/wasm`):
 //
-//   - `Quill` and `Document` ARE the core build's classes, re-exported. They
+//   - `Quill` and `Document` ARE the core build's classes, handed out by the
+//     gate (§ "Initialization"). They
 //     hold the canonical data and the full sync surface (schema / validate /
 //     seed / mutate / toJson / toTree). No backend is loaded to use them, so
 //     the editor/validation path never pays for a multi-MB backend binary.
@@ -38,51 +40,42 @@
 // The cross-memory crossing is therefore invisible: a consumer hands canonical
 // `Quill`/`Document` to `engine.render(...)` and gets a `RenderResult` back.
 
-// ── CANONICAL INVARIANT: re-export the core build, never wrap ───────────────
-// The root re-exports the core build's `Quill`/`Document` classes verbatim,
-// NOT subclasses or wrappers. There is exactly ONE public entry point (this
-// module), so this identity is a structural fact: `Quill`/`Document` ARE the
-// core classes, and the only boundary that needs crossing is core→backend (a
-// separate WASM memory), which `Engine` does internally as data
-// (`toTree`/`toJson`).
+// ── CANONICAL INVARIANT: hand out the core build's classes, never wrap ──────
+// The `Quill`/`Document` a consumer holds ARE the core build's classes, NOT
+// subclasses or wrappers. `init` resolves to them (§ "Initialization"); which
+// door they come through changes nothing about the identity. The only boundary
+// that needs crossing is core→backend (a separate WASM memory), which `Engine`
+// does internally as data (`toTree`/`toJson`).
 //
-// Do NOT replace this with a wrapper class: that breaks the identity and turns
-// a structural fact into a converted type (a breaking design change, not a
-// refactor). The `runtime.test.js` "re-exports the internal core build classes
-// 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).
+// Do NOT hand out a wrapper: that breaks the identity and turns a structural
+// fact into a converted type (a breaking design change, not a refactor). The
+// `runtime.test.js` "hands out the internal core build classes verbatim" case
+// (`Quill === CoreQuill`) is the executable guard for this invariant.
 //
 // 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
 // checks them. See § "Handles from another copy" below.
 //
-// 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.
+// Local bindings, so this module can augment them: `quill.writer(doc)` is
+// patched onto the prototype below, and `instanceof` reads them directly.
 //
 // 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`,
-// `mapPos`).
-export { importMarkdown, exportMarkdown, rebase, mapPos } from '../core/wasm.js';
+// The document-free content codec: `exportMarkdown(body)` (the on-demand
+// markdown projection), `importMarkdown`, and the position-mapping pair
+// (`rebase`, `mapPos`).
+import { 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';
+import { parseDocPath, formatDocPath } from '../core/wasm.js';
 
 // ── Initialization ──────────────────────────────────────────────────────────
 // The builds are `--target web`: they export their classes synchronously but
@@ -90,64 +83,135 @@ export { parseDocPath, formatDocPath } from '../core/wasm.js';
 // 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 ONLY DOOR. `init` resolves to the core surface, and this
+// module exports none of it statically, so a handle is unobtainable without
+// having awaited: the precondition is structural rather than a convention the
+// caller has to know. package.json's `exports` map carries exactly one entry,
+// so there is no subpath around the gate either.
+//
 // 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.
+// the surface it guards cannot be async: `Quill.fromTree` and
+// `quill.seedDocument` return synchronously, so there is nowhere to hide an
+// await except in front.
+//
+// WHAT STAYS A STATIC EXPORT is what needs no instance. `MAIN_CARD_ADDR`, the
+// open-set guards and `isQuillmarkError` are pure JS over plain objects; gating
+// them would cost a consumer of one an await it has no use for.
 //
-// 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).
+// `Engine`, `LiveSession` and the four writer/reader classes stay static too,
+// gated by their ARGUMENTS rather than by the door. Every `Engine` verb takes a
+// `Quill` first (`#backendOf` is the single reader) and the writer/reader
+// constructors take both handles, so a caller who has not awaited cannot
+// produce an argument to call them with. The two constructors taking no handle
+// reach no wasm: `new Engine()` validates a descriptor map, and a `LiveSession`
+// forwards to the backend session `engine.open` is the sole source of. None of
+// the six carries a static method, the one member shape an argument cannot
+// gate. `gate.test.js` is the executable guard, driving the whole static
+// surface before `init`. Holding them out of the gate keeps them tree-shakable,
+// so the editor path drops the dispatcher it never calls.
+//
+// FAILURE DELIVERY follows the FUNCTION kind, not the failure kind: a sync verb
+// throws, a promise-returning verb rejects, and nothing does both. A
+// programming error reached through a promise-returning verb
+// (`runtime::foreign_handle` inside `Engine.render`) rejects like any other.
+// `init` is the one promise-returning export not declared `async`, because the
+// memo is returned by identity; its conflict guard rejects explicitly to hold
+// the rule, which the return type cannot declare and a `.catch` would not see.
 
-/** The in-flight or settled core instantiation. The memo is the PROMISE, not a
- * boolean, so concurrent callers share one instantiation instead of racing. */
+/**
+ * The gated surface: the core build's values, which are exactly the ones its
+ * instance stands behind. Frozen and built at module scope, because the classes
+ * and functions themselves resolve synchronously (only the instance behind them
+ * is late), so there is nothing to defer and no per-call allocation.
+ *
+ * Membership is derived, not chosen: it is the core build's exports minus its
+ * instantiation machinery (`default`, `initSync`, and the start-section
+ * `start`), which `init` owns and no consumer calls. `init.test.js` § "the
+ * gated surface" computes that set and pins it, so a new core export that never
+ * reaches here fails there rather than going missing.
+ * @type {import('./runtime.js').CoreSurface}
+ */
+const CORE_SURFACE = Object.freeze({
+	Quill,
+	Document,
+	importMarkdown,
+	exportMarkdown,
+	rebase,
+	mapPos,
+	parseDocPath,
+	formatDocPath
+});
+
+/** The in-flight or settled core instantiation, resolving to `CORE_SURFACE`.
+ * The memo is the PROMISE, not a boolean, so concurrent callers share one
+ * instantiation instead of racing.
+ * @type {Promise<import('./runtime.js').CoreSurface> | undefined} */
 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.
+ * Instantiate the core WASM build and resolve to its surface.
  *
  * ```js
- * import { init, Quill, Engine } from '@quillmark/wasm';
- * await init();
+ * import { init } from '@quillmark/wasm';
+ * const { Quill, Document } = await init();
  * ```
  *
+ * The classes and the free functions come from here and nowhere else, so the
+ * pre-init mistake is not expressible. Destructure at each entry point (route
+ * loader, hydration path, worker) rather than threading one result around: the
+ * gate is memoized, so every await after the first is free.
+ *
  * 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.
+ * Idempotent and concurrency-safe: every non-conflicting call returns the same
+ * promise, so several entry points cost one instantiation. A failed init clears
+ * the memo, so a retry is possible.
+ *
+ * Both failures reject (§ "Initialization", FAILURE DELIVERY): one `catch`
+ * around `await init(...)` covers `runtime::init_conflict` and
+ * `runtime::init_failed` alike.
  *
  * @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
+ *   later call passing a *different* source rejects with
+ *   `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<import('./runtime.js').CoreSurface>} the core surface, once
+ *   its instance is live
  */
 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.'
+			// A rejection, not a throw: this is the one failure on the
+			// promise-returning surface that could land on the caller's stack, where
+			// `init(BYTES).catch(…)` would not see it.
+			return Promise.reject(
+				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;
-	});
+	coreInit = instantiateCore(source).then(
+		() => CORE_SURFACE,
+		(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;
 }
 
@@ -452,9 +516,10 @@ export function isListItemContainer(container) {
 // A predicate rather than an exported name list, because the known tables below
 // are upstream's business. They are pinned against the Rust source
 // (`Content::RESERVED_*` and `KnownIslandType`) by the
-// `known_open_set_names_are_pinned` drift-guard test in
-// `crates/content/src/model.rs`: adding a built-in means editing there, here, and
-// the TS unions in `crates/bindings/wasm/src/engine.rs` in one commit.
+// `js_known_name_tables_match_the_rust_open_sets` drift-guard test in
+// `crates/bindings/wasm/tests/known_names_drift.rs`: adding a built-in means
+// editing there, here, and the TS unions in `crates/bindings/wasm/src/engine.rs`
+// in one commit.
 //
 // These classify unknown *tags*, not unknown *payloads on known tags*. A future
 // `kind: "footnote"` with a sibling `ref` loses `ref` at a consumer that predates

package/runtime/uninit.js

@@ -1,57 +0,0 @@
-// 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';