@quillmark/wasm 0.112.0 → 0.114.0

package/runtime/runtime.js

@@ -1,34 +1,13 @@
 /* @ts-self-types="./runtime.d.ts" */
 //
-// @quillmark/wasm/runtime: the canonical consumer API.
+// The canonical consumer API, and the package's sole export. Its contract is
+// `runtime.d.ts`, which a consumer's TypeScript reads through the package's
+// `exports.types` map; the multi-binary design it implements is
+// `prose/canon/BINDINGS.md`.
 //
-// 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 binary per backend that carries an engine.
-// A handle from one memory cannot be used by another; this module hides that
-// seam behind `await init()` and a static `Engine`.
-//
-//   - `Quill` and `Document` ARE the core build's classes, handed out by the
-//     gate below, never subclasses or wrappers: that identity is what makes
-//     `instanceof` the whole membership test, so a handle either belongs to this
-//     copy or to another copy, and the second is always a consumer bug.
-//     `runtime.test.js` guards it (`Quill === CoreQuill`). No backend is loaded
-//     to use them, so the editor path never pays for a multi-MB binary.
-//
-//   - `Engine` is the render dispatcher. It routes on `quill.backendId`, lazily
-//     imports that backend's build, clones the canonical `Quill`/`Document` into
-//     the backend's memory as data (`toTree`→`fromTree`, `toJson`→`fromJson`),
-//     renders, and never lets the backend handles escape.
-//
-//     CLONE LIFETIMES: the per-call `Document` clone is transient, since
-//     documents are small and mutate freely. The `Quill` clone is CACHED,
-//     because re-cloning re-serializes its whole file tree, copies it into
-//     backend memory, and re-parses + re-validates the bundle every call. Each
-//     `Engine` memoizes it in a `WeakMap` keyed on the canonical `Quill`, so
-//     dropping the core quill makes the entry collectable and `--weak-refs`
-//     frees the backend handle. The contract this buys: a `Quill` instance's
-//     contents never change after construction — mutate by replacing the
-//     instance.
+// A `Quill` instance's contents never change after construction — mutate by
+// replacing the instance — which is what makes the cached backend clone below
+// safe to hand out for the instance's whole life.
 
 // Local bindings, so this module can augment them: `quill.writer(doc)` is
 // patched onto the prototype below, and `instanceof` reads them directly. The
@@ -41,34 +20,13 @@ import initCore, { Quill, Document } from '../core/wasm.js';
 // Resolution-time, so `node:fs` never enters a browser graph.
 import { toModuleSource } from '#quillmark-env';
 import { importMarkdown, exportMarkdown, rebase, mapPos, mapMarks } from '../core/wasm.js';
-import { parseDocPath, formatDocPath } from '../core/wasm.js';
+import { parseDocPath, formatDocPath, formatDiagnostic } 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.
-//
-// THE GATE IS THE ONLY DOOR: `init` resolves to the core surface and nothing
-// here exports it statically, so a handle is unobtainable without having
-// awaited, and package.json's `exports` map carries exactly one entry. The
-// guarded surface 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.
-// `Engine`, `LiveSession` and the four writer/reader classes stay static too,
-// gated by their ARGUMENTS instead — every verb takes a `Quill` or both
-// handles, so a caller who has not awaited cannot produce an argument, and the
-// two constructors taking no handle reach no wasm. None carries a static
-// method, the one member shape an argument cannot gate. `gate.test.js` drives
-// the whole static surface before `init`. Holding them out of the gate also
-// keeps them tree-shakable.
-//
-// FAILURE DELIVERY follows the FUNCTION kind, not the failure kind: a sync verb
-// throws, a promise-returning verb rejects, and nothing does both. `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.
+// A `--target web` build exports its classes synchronously but carries no wasm
+// instance until something instantiates it. This module owns that for core,
+// behind one awaited gate; `Engine` owns it for the backends, inside their lazy
+// load. Which values that gate holds and which stay static exports:
+// `prose/canon/BINDINGS.md`.
 
 /**
  * The gated surface: the core build's values, which are exactly the ones its
@@ -92,7 +50,8 @@ const CORE_SURFACE = Object.freeze({
 	mapPos,
 	mapMarks,
 	parseDocPath,
-	formatDocPath
+	formatDocPath,
+	formatDiagnostic
 });
 
 /** The in-flight or settled core instantiation, resolving to `CORE_SURFACE`.
@@ -104,38 +63,8 @@ let coreInit;
 let coreInitSource;
 
 /**
- * Instantiate the core WASM build and resolve to its surface.
- *
- * ```js
- * 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 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 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
+ * @param {import('../core/wasm.js').InitInput} [source]
+ * @returns {Promise<import('./runtime.js').CoreSurface>}
  */
 export function init(source) {
 	if (coreInit) {
@@ -195,46 +124,17 @@ async function instantiateCore(source) {
 	}
 }
 
-// ── The main-card address ───────────────────────────────────────────────────
 /**
- * The main card's address: the default target of the card-scoped verbs
- * (`storeFields` / `storeExt` / `commitFields` / …). A named, `CardAddr`-typed
- * alias for the empty address `{}`, so a main-card write names its target:
- * `doc.storeFields(MAIN_CARD_ADDR, fields)`. It IS `{}` (frozen), a pure alias:
- * `{}` and `undefined` stay equally valid. Card axis only: a card selector,
- * never a field address.
  * @type {import('../core/wasm.js').CardAddr}
  */
 export const MAIN_CARD_ADDR = Object.freeze({});
 
-// ── The variant discriminant key ────────────────────────────────────────────
 /**
- * The key carrying the discriminant inside a variant-bearing enum's value.
- *
- * A field declaring `variants:` rests as a container, `{value: <member>, …that
- * member's fields}`, so reading or writing one means naming this key:
- * `doc.storeFields(MAIN_CARD_ADDR, { classification: { [VARIANT_DISCRIMINANT_KEY]: 'CUI' } })`.
- * It crosses the boundary inside untyped container data, with no type to read
- * it off.
- *
- * Reserved: no variant may declare a field under it
- * (`quill::variant_reserved_field_name`), and `QuillFieldSchema.variants`,
- * keyed by member, never contains it.
  * @type {'value'}
  */
 export const VARIANT_DISCRIMINANT_KEY = 'value';
 
 /**
- * Narrow an unknown caught value to a `QuillmarkError`, the error every
- * fallible method in this package throws: a real `Error` with a non-empty
- * `diagnostics` array attached (same entry shape as `RenderResult.warnings`).
- *
- * Structural by necessity AND by design: the WASM layer constructs a plain
- * `Error` and attaches the property (there is no error class to `instanceof`),
- * and a structural check narrows errors from any build or WASM instance in the
- * page. The deliberate exception to § "Handles from another copy": an error is
- * data, not a handle, so nothing is gained by refusing one that crossed.
- *
  * @param {unknown} e
  * @returns {e is Error & { diagnostics: import('../core/wasm.js').Diagnostic[] }}
  */
@@ -258,62 +158,35 @@ function quillmarkError(code, message, hint) {
 	return err;
 }
 
-// ── Handles from another copy: always a bug ─────────────────────────────────
-// A duplicate install is two `core` builds: two linear memories and two distinct
-// `Quill`/`Document` classes. No topology legitimately loads a multi-megabyte
-// WASM package twice AND needs handles to cross between the copies, so a
-// crossing is a consumer bug, and every seam taking a core handle says so.
-//
-// Crossing read-only handles as data is mechanically possible (`toJson` and
-// `toTree` serialize either way) and is not done: it leaves a package where some
-// verbs work and some throw, and it hides a cliff, since a crossed read is a
-// whole-document `toJson` + `fromJson` and a form reading fifty fields pays
-// fifty round trips.
-//
-// What the checks deliver is the ERROR, not the rejection. wasm-bindgen's glue
-// already rejects a foreign class wherever a method declares a reference
-// parameter, but its `_assertClass` throws a bare `Error` reading
-// `expected instance of Document` at a value that IS a `Document`, so
-// `isQuillmarkError` returns false and the failure leaves this package's error
-// contract. The checks front-run it with a `QuillmarkError` naming both cause
-// and cure, and cover the seams with no `_assertClass` to front-run: `Engine`
-// and `LiveSession.update` cross into backend memory as data, where a foreign
-// handle would silently work at the price of that round trip and a per-copy
-// split of the quill clone cache.
+// These checks deliver the ERROR, not the rejection, at the seams that cross
+// into backend memory as DATA — `Engine` and `LiveSession.update` — where a
+// foreign handle would otherwise work silently at the price of a whole-document
+// round trip and a per-copy split of the quill clone cache, and at the four
+// writer/reader binds, whose constructors hold both handles. A method declaring
+// a reference parameter needs none of this: wasm-bindgen's own `_assertClass`
+// refuses a foreign class there.
 
-/** Per class: the code and hint for "not one at all", and the from-another-copy probe. */
+/** Per class: the diagnostic for a value that is not one of THIS copy's handles. */
 const HANDLE_KINDS = {
 	Quill: {
 		code: 'runtime::not_a_quill',
-		probe: 'toTree',
-		hint: 'Pass a Quill built by Quill.fromTree.'
+		hint: 'Pass a Quill built by Quill.fromTree. A Quill from another copy of @quillmark/wasm is refused too — each copy is its own WASM linear memory and its own class — so run `npm ls @quillmark/wasm` and dedupe to one.'
 	},
 	Document: {
 		code: 'runtime::not_a_document',
-		probe: 'toJson',
-		hint: 'Pass a Document built by Document.fromMarkdown / fromJson or quill.seedDocument.'
+		hint: 'Pass a Document built by Document.fromMarkdown / fromStored or quill.seedDocument. A Document from another copy of @quillmark/wasm is refused too — each copy is its own WASM linear memory and its own class — so run `npm ls @quillmark/wasm` and dedupe to one.'
 	}
 };
 
 /**
- * The rejection for a value that is not one of this copy's handles. Two cures,
- * so two diagnostics: a value carrying the class's serializer is that class
- * from ANOTHER copy (dedupe the install), anything else is the wrong argument
- * (fix the call).
+ * The rejection for a value that is not one of this copy's handles.
  * @param {unknown} value
  * @param {string} method
  * @param {'Quill' | 'Document'} className
  * @returns {Error & { diagnostics: import('../core/wasm.js').Diagnostic[] }}
  */
 function notLocal(value, method, className) {
-	const { code, probe, hint } = HANDLE_KINDS[className];
-	if (value && typeof (/** @type {any} */ (value)[probe]) === 'function') {
-		return quillmarkError(
-			'runtime::foreign_handle',
-			`${method}: the ${className} belongs to a different copy of @quillmark/wasm. Handles never cross between copies: each copy is its own WASM linear memory and its own ${className} class.`,
-			'Two copies of @quillmark/wasm are installed. Run `npm ls @quillmark/wasm` and dedupe to one.'
-		);
-	}
+	const { code, hint } = HANDLE_KINDS[className];
 	return quillmarkError(
 		code,
 		`${method}: expected a ${className}, got ${value === null ? 'null' : typeof value}.`,
@@ -343,213 +216,26 @@ function requireLocalQuill(quill, method) {
 	throw notLocal(quill, method, 'Quill');
 }
 
-// Marker for the patches below. `Symbol.for`, not a module-local `Symbol()`:
-// re-evaluating THIS module (Vite HMR, a Vitest worker sharing a module graph)
-// against an already-patched (because cached) core build must see the existing
-// marker, or each pass wraps the previous wrapper.
-const HANDLE_CHECKED = Symbol.for('@quillmark/wasm:handle-checked');
-
-/**
- * Replace `proto[name]` with `wrap(original)`, once.
- * @param {object} proto
- * @param {string} name
- * @param {(original: Function) => Function} wrap
- */
-function patchHandleChecked(proto, name, wrap) {
-	const original = /** @type {any} */ (proto)[name];
-	if (typeof original !== 'function' || original[HANDLE_CHECKED]) return;
-	const patched = wrap(original);
-	/** @type {any} */ (patched)[HANDLE_CHECKED] = true;
-	// Keep the method's name so a stack trace still reads `Quill.validate`.
-	Object.defineProperty(patched, 'name', { value: name, configurable: true });
-	/** @type {any} */ (proto)[name] = patched;
-}
-
-// The core methods declaring a `&Document` parameter. Each already refuses a
-// foreign handle inside `_assertClass`; the patch makes the refusal legible.
-patchHandleChecked(Document.prototype, 'equals', (original) =>
-	function equals(/** @type {any} */ other) {
-		requireLocalDoc(other, 'Document.equals');
-		return original.call(this, other);
-	}
-);
-for (const name of /** @type {const} */ (['validate', 'resolve', 'conform'])) {
-	// Named once per patch, not per call: `validate` runs per keystroke.
-	const method = `Quill.${name}`;
-	patchHandleChecked(Quill.prototype, name, (original) =>
-		function (/** @type {any} */ doc) {
-			requireLocalDoc(doc, method);
-			return original.call(this, doc);
-		}
-	);
-}
-
-// The typed writer/reader primitives (`Document._commitField` and friends) take
-// the QUILL by reference, so they hit the same `_assertClass` from the other
-// direction. Checked at the four writer/reader classes below, not patched onto
-// `Document`: a foreign document carries its OWN prototype, so patching this
-// copy's would never run.
-
-// ── Open-set discriminant guards ────────────────────────────────────────────
-// `ContentIsland.type`, `ContentMark.type`, `ContentLine.kind`, and
-// `ContentContainer.container` are OPEN sets: each union carries a residual
-// `{ …: string; … }` arm, so a bare `x.type === 'table'` check never narrows the
-// payload, TS keeps the residual arm live (a `string` can be `'table'`),
-// leaving `props` / the mark payload / `level` opaque at every consumer. These
-// are the checked narrowing path: on the true branch the payload's pinned shape
-// is asserted. Only the payload-carrying arms get a guard: an island always
-// carries `props`, and a `link`/`anchor` mark, a `heading`/`code` line and a
-// `list_item` container each carry their payload in `attrs`; the payload-free
-// arms (`strong`/`emph`/`underline`/`strike`/`code` marks, `para`/`island`/
-// `rule` lines, `quote`) omit `attrs` and narrow to nothing. An unrecognized
-// discriminant fails every guard and carries the same `attrs` a known one
-// would.
-
-/**
- * @param {import('../core/wasm.js').ContentIsland} island
- * @returns {island is import('../core/wasm.js').ContentIsland & { type: 'table'; props: import('../core/wasm.js').TableProps }}
- */
-export function isTableIsland(island) {
-	return island.type === 'table';
-}
-
-/**
- * @param {import('../core/wasm.js').ContentIsland} island
- * @returns {island is import('../core/wasm.js').ContentIsland & { type: 'image'; props: import('../core/wasm.js').ImageProps }}
- */
-export function isImageIsland(island) {
-	return island.type === 'image';
-}
-
-/**
- * @param {import('../core/wasm.js').ContentMark} mark
- * @returns {mark is import('../core/wasm.js').ContentMark & { type: 'link'; attrs: { url: string } }}
- */
-export function isLinkMark(mark) {
-	return mark.type === 'link';
-}
-
-/**
- * @param {import('../core/wasm.js').ContentMark} mark
- * @returns {mark is import('../core/wasm.js').ContentMark & { type: 'anchor'; attrs: { id: string } }}
- */
-export function isAnchorMark(mark) {
-	return mark.type === 'anchor';
-}
-
-/**
- * @param {import('../core/wasm.js').ContentLine} line
- * @returns {line is import('../core/wasm.js').ContentLine & { kind: 'heading'; attrs: { level: number } }}
- */
-export function isHeadingLine(line) {
-	return line.kind === 'heading';
-}
-
-/**
- * @param {import('../core/wasm.js').ContentLine} line
- * @returns {line is import('../core/wasm.js').ContentLine & { kind: 'code'; attrs?: { lang?: string } }}
- */
-export function isCodeLine(line) {
-	return line.kind === 'code';
-}
-
-/**
- * @param {import('../core/wasm.js').ContentContainer} container
- * @returns {container is import('../core/wasm.js').ContentContainer & { container: 'list_item'; attrs: { ordered: boolean; start: number; ordinal: number }; instance?: number }}
- */
-export function isListItemContainer(container) {
-	return container.container === 'list_item';
-}
-
-// ── Open-set membership guards ──────────────────────────────────────────────
-// The guards above each answer "is this arm X". These four answer "is this a
-// value this build knows?", the question any read-modify-write consumer must
-// ask, since lowering an edit restates every line's kind and containers. A
-// predicate rather than an exported name list, because the tables below are
-// upstream's business: they are pinned against the Rust source by
-// `tests/known_names_drift.rs`, so adding a built-in means editing there, here,
-// and the TS unions in `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
-// it either way.
-
-const KNOWN_LINE_KINDS = new Set(['para', 'heading', 'code', 'island', 'rule']);
-const KNOWN_CONTAINERS = new Set(['list_item', 'quote']);
-const KNOWN_MARK_TYPES = new Set(['strong', 'emph', 'underline', 'strike', 'code', 'link', 'anchor']);
-const KNOWN_ISLAND_TYPES = new Set(['table', 'image']);
-
-/**
- * @param {import('../core/wasm.js').ContentLine} line
- * @returns {line is import('../core/wasm.js').ContentLine & { kind: string; attrs: unknown }}
- */
-export function isUnknownLine(line) {
-	return typeof line?.kind === 'string' && !KNOWN_LINE_KINDS.has(line.kind);
-}
-
-/**
- * @param {import('../core/wasm.js').ContentContainer} container
- * @returns {container is import('../core/wasm.js').ContentContainer & { container: string; attrs: unknown }}
- */
-export function isUnknownContainer(container) {
-	return typeof container?.container === 'string' && !KNOWN_CONTAINERS.has(container.container);
-}
-
-/**
- * @param {import('../core/wasm.js').ContentMark} mark
- * @returns {mark is import('../core/wasm.js').ContentMark & { type: string; attrs: unknown }}
- */
-export function isUnknownMark(mark) {
-	return typeof mark?.type === 'string' && !KNOWN_MARK_TYPES.has(mark.type);
-}
-
-/**
- * @param {import('../core/wasm.js').ContentIsland} island
- * @returns {island is import('../core/wasm.js').ContentIsland & { type: string; props: unknown }}
- */
-export function isUnknownIsland(island) {
-	return typeof island?.type === 'string' && !KNOWN_ISLAND_TYPES.has(island.type);
-}
-
-// ── Container run boundaries ────────────────────────────────────────────────
-// `ContentContainer.instance` is what keeps two adjacent runs of one shape
-// apart, and only a writer knows where a boundary is: the flat `containers`
-// form cannot tell a list ending beside another from one list of two items, so
-// an omitted discriminator welds them and nothing reports it.
-//
 // WELD_KEYS is the rule `Container::same_weld` owns upstream: which `attrs`
 // entries two adjacent runs must share for the markdown projection to read them
-// as one, and therefore for the canonical form to have to spend a
-// discriminator. `start` is not among them, since CommonMark reads only a
-// list's first number — a subset, which is why a built-in needs an entry rather
-// than the unknown branch's whole-bag compare. A table rather than a switch, so
-// `tests/known_names_drift.rs` can pin it against the Rust predicate.
+// as one. `start` is not among them, since CommonMark reads only a list's first
+// number — a subset, which is why every container needs its own entry. A table
+// rather than a switch, so `tests/known_names_drift.rs` can pin it against the
+// Rust predicate.
 
 const WELD_KEYS = { list_item: ['ordered'], quote: [] };
 
-function sameJson(a, b) {
-	if (a === b) return true;
-	if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false;
-	if (Array.isArray(a) !== Array.isArray(b)) return false;
-	const ka = Object.keys(a);
-	return (
-		ka.length === Object.keys(b).length &&
-		ka.every((k) => Object.hasOwn(b, k) && sameJson(a[k], b[k]))
-	);
-}
-
 /**
  * @param {import('../core/wasm.js').ContentContainer} a
  * @param {import('../core/wasm.js').ContentContainer} b
  * @returns {boolean}
  */
 function weldsWith(a, b) {
-	// A malformed value welds with nothing. The membership guards' posture:
-	// answer rather than throw.
+	// A malformed value welds with nothing: answer rather than throw.
 	if (typeof a?.container !== 'string' || a.container !== b?.container) return false;
-	// `hasOwn`, so a tag colliding with an `Object.prototype` member reaches the
-	// unknown branch rather than a function.
-	if (!Object.hasOwn(WELD_KEYS, a.container)) return sameJson(a.attrs, b.attrs);
+	// `hasOwn`, so a tag colliding with an `Object.prototype` member answers
+	// `false` rather than reaching a function.
+	if (!Object.hasOwn(WELD_KEYS, a.container)) return false;
 	return WELD_KEYS[a.container].every((k) => a.attrs?.[k] === b.attrs?.[k]);
 }
 
@@ -579,7 +265,7 @@ export function assignInstances(runs) {
  * generated entry's own `wasm !== undefined` guard only catches a call arriving
  * after one finished, not one already in flight.
  *
- * @param {string} id backend id, for the failure message
+ * @param {string} id the build's name, 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
@@ -598,108 +284,89 @@ function backendLoad(id, importThunk, wasmUrl) {
 			throw Object.assign(
 				quillmarkError(
 					'runtime::backend_load_failed',
-					`Engine: could not load the '${id}' backend: ${
+					`Engine: could not load the '${id}' build: ${
 						/** @type {any} */ (cause)?.message ?? cause
 					}`,
-					'The backend binary ships beside the package files; check the network tab for a 404 or an HTML response.'
+					'The build 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` dynamically imports and instantiates a backend's chunk, so
-// the binary is fetched only when something renders against it; `formats` and
-// `canvas` are the required static capability manifest, so the probes
-// (`supportedFormats` / `supportsCanvas`) answer without loading the binary or
-// cloning the quill. The manifest mirrors each backend's Rust `SUPPORTED_FORMATS`
-// (and `formats_support_canvas`: true iff the list includes `svg` or `png`),
-// pinned by a `runtime.test.js` drift guard that renders once and compares.
+// The render build is NEVER statically imported here: that would pull a
+// multi-MB binary into the eager graph and defeat lazy loading. Both built-in
+// backends ship in it, so they share one `load`; each `formats` manifest
+// mirrors that backend's Rust `SUPPORTED_FORMATS`, pinned by a
+// `runtime.test.js` drift guard that renders once and compares.
+const RENDER_BUILD = backendLoad(
+	'render',
+	() => import('../render/wasm.js'),
+	() => new URL('../render/wasm_bg.wasm', import.meta.url)
+);
 const DEFAULT_BACKENDS = {
 	typst: {
-		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
+		load: RENDER_BUILD,
+		formats: ['pdf', 'svg', 'png'] // crates/backends/typst/src/lib.rs SUPPORTED_FORMATS
 	},
-	pdfform: {
-		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
+	acroform: {
+		load: RENDER_BUILD,
+		formats: ['pdf'] // crates/backends/acroform/src/lib.rs SUPPORTED_FORMATS
 	}
 };
 
 /**
  * Validate a backend registry descriptor, naming the backend id on any
  * malformed entry. Failing at construction rather than deep inside a render is
- * what lets the capability probes answer from the manifest unconditionally.
+ * what lets `supportedFormats` answer from the manifest unconditionally.
  * @param {string} id
  * @param {unknown} entry
- * @returns {{ load: () => Promise<unknown>, formats: string[], canvas: boolean }}
+ * @returns {{ load: () => Promise<unknown>, formats: string[] }}
  */
 function validateBackend(id, entry) {
 	if (!entry || typeof entry !== 'object') {
-		throw new Error(
-			`Engine: backend '${id}' must be a descriptor { load, formats, canvas }.`
-		);
+		throw new Error(`Engine: backend '${id}' must be a descriptor { load, formats }.`);
 	}
-	const { load, formats, canvas } = /** @type {any} */ (entry);
+	const { load, formats } = /** @type {any} */ (entry);
 	if (typeof load !== 'function') {
 		throw new Error(`Engine: backend '${id}' descriptor needs a callable 'load'.`);
 	}
 	if (!Array.isArray(formats)) {
 		throw new Error(`Engine: backend '${id}' descriptor needs a 'formats' array.`);
 	}
-	if (typeof canvas !== 'boolean') {
-		throw new Error(`Engine: backend '${id}' descriptor needs a boolean 'canvas'.`);
-	}
-	return { load, formats, canvas };
+	return { load, formats };
 }
 
-/**
- * Render dispatcher over the canonical `Quill`/`Document`. One `Engine`
- * instance can drive every backend; it resolves the right backend build from
- * each quill's declared `backendId` and loads it lazily on first use.
- */
 export class Engine {
-	/** backendId → Promise<backend module>, memoized so each build loads once. */
+	/**
+	 * The three caches below key on a descriptor's `load` thunk, the build's
+	 * identity: two backend ids sharing one build (the built-ins) share one
+	 * module, one engine and one clone cache, and a consumer's override build
+	 * gets its own.
+	 */
+	/** load → Promise<build module>, memoized so each build loads once. */
 	#modules = new Map();
-	/** backendId → that backend's engine instance (the WASM backend registry). */
+	/** load → that build's engine instance (the WASM backend registry). */
 	#engines = new Map();
-	/** backendId → descriptor `{ load, formats, canvas }`. */
+	/** backendId → descriptor `{ load, formats }`. */
 	#loaders;
 	/**
-	 * backendId → WeakMap<canonical Quill, backend-memory clone>, caching the
+	 * load → WeakMap<canonical Quill, build-memory clone>, caching the
 	 * expensive materialization. WeakMap so dropping the canonical quill makes
 	 * its clone collectable, and wasm-bindgen weak-refs then free the handle.
-	 * @type {Map<string, WeakMap<object, any>>}
+	 * @type {Map<() => Promise<unknown>, WeakMap<object, any>>}
 	 */
 	#quillClones = new Map();
 
 	/**
-	 * @param {{ backends?: Record<string, { load: () => Promise<unknown>, formats: string[], canvas: boolean }> }} [options]
-	 *   Extra or overriding backend descriptors, merged over the built-ins. Each
-	 *   is `{ load, formats, canvas }` with the manifest REQUIRED, since that is
-	 *   what makes `supportedFormats` / `supportsCanvas` free; malformed entries
-	 *   throw here, at construction.
-	 *
-	 *   `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).
+	 * `load` must resolve to a READY module: a registrant shipping its own
+	 * `--target web` build instantiates inside the thunk, and more than one
+	 * `Engine` may call it, so memoize (the built-ins do, at module scope).
+	 * @param {{ backends?: Record<string, { load: () => Promise<unknown>, formats: string[] }> }} [options]
 	 */
 	constructor(options) {
 		const merged = { ...DEFAULT_BACKENDS, ...(options?.backends ?? {}) };
-		/** @type {Record<string, { load: () => Promise<unknown>, formats: string[], canvas: boolean }>} */
+		/** @type {Record<string, { load: () => Promise<unknown>, formats: string[] }>} */
 		const loaders = {};
 		for (const [id, entry] of Object.entries(merged)) {
 			loaders[id] = validateBackend(id, entry);
@@ -708,17 +375,19 @@ export class Engine {
 	}
 
 	/**
-	 * The registered descriptor for `backendId`, or the "no backend registered"
-	 * throw. Touches no binary.
+	 * The registered descriptor for `backendId`, or the
+	 * `engine::backend_not_found` throw core raises for the same condition.
+	 * Touches no binary.
 	 * @param {string} backendId
-	 * @returns {{ load: () => Promise<unknown>, formats: string[], canvas: boolean }}
+	 * @returns {{ load: () => Promise<unknown>, formats: string[] }}
 	 */
 	#descriptorFor(backendId) {
 		const descriptor = this.#loaders[backendId];
 		if (!descriptor) {
-			throw new Error(
-				`Engine: no backend registered for '${backendId}'. ` +
-					`Known backends: ${Object.keys(this.#loaders).join(', ') || '(none)'}.`
+			throw quillmarkError(
+				'engine::backend_not_found',
+				`Engine: backend '${backendId}' not registered or not enabled.`,
+				`Available backends: ${Object.keys(this.#loaders).join(', ') || '(none)'}`
 			);
 		}
 		return descriptor;
@@ -738,51 +407,52 @@ export class Engine {
 	}
 
 	/**
-	 * Resolve (and lazily load) the backend module + its engine for `backendId`.
+	 * Resolve (and lazily load) the build module + its engine for `backendId`.
 	 * @param {string} backendId
 	 * @returns {Promise<{ mod: any, engine: any }>}
 	 */
 	async #resolveBackend(backendId) {
-		const descriptor = this.#descriptorFor(backendId);
+		const { load } = this.#descriptorFor(backendId);
 
-		let modPromise = this.#modules.get(backendId);
+		let modPromise = this.#modules.get(load);
 		if (!modPromise) {
 			// Set the promise synchronously (before any await) so concurrent first
 			// renders share ONE import. Self-heal on failure so a transient load
 			// error doesn't poison every later attempt.
 			modPromise = Promise.resolve()
-				.then(descriptor.load)
+				.then(load)
 				.catch((err) => {
-					this.#modules.delete(backendId);
+					this.#modules.delete(load);
 					throw err;
 				});
-			this.#modules.set(backendId, modPromise);
+			this.#modules.set(load, modPromise);
 		}
 		const mod = await modPromise;
 
-		let engine = this.#engines.get(backendId);
+		let engine = this.#engines.get(load);
 		if (!engine) {
 			engine = new mod.Quillmark();
-			this.#engines.set(backendId, engine);
+			this.#engines.set(load, engine);
 		}
 		return { mod, engine };
 	}
 
 	/**
-	 * Get (or materialize-and-cache) the backend-memory `Quill` clone for `quill`
-	 * under `backendId`. On a miss the clone is built from `tree`, the caller's
-	 * pre-await snapshot, since the canonical handle may be freed by now.
-	 * @param {any} mod the backend build module
+	 * Get (or materialize-and-cache) the build-memory `Quill` clone for `quill`
+	 * under `backendId`'s build. On a miss the clone is built from `tree`, the
+	 * caller's pre-await snapshot, since the canonical handle may be freed by now.
+	 * @param {any} mod the build module
 	 * @param {string} backendId
 	 * @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
+	 * @returns {any} the build-memory quill clone
 	 */
 	#cachedQuillClone(mod, backendId, quill, tree) {
-		let perQuill = this.#quillClones.get(backendId);
+		const { load } = this.#descriptorFor(backendId);
+		let perQuill = this.#quillClones.get(load);
 		if (!perQuill) {
 			perQuill = new WeakMap();
-			this.#quillClones.set(backendId, perQuill);
+			this.#quillClones.set(load, perQuill);
 		}
 		let backendQuill = perQuill.get(quill);
 		if (!backendQuill) {
@@ -797,11 +467,15 @@ 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, 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").
+	 * OWNERSHIP WINDOW: both caller handles are snapshotted (`doc.toStored()` and
+	 * `doc.warnings`, and `quill.toTree()` on a clone-cache miss) BEFORE the first
+	 * await. The backend load below is a real suspension point, 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").
+	 *
+	 * `docWarnings` rides the context because the storage DTO does not carry
+	 * them: `fromStored` clears the load's warnings, so the backend clone knows
+	 * nothing of them and `render` splices the snapshot back in.
 	 *
 	 * Clone lifetimes differ by design: the `doc` clone is TRANSIENT, freed in
 	 * the `finally` of every call, while the `quill` clone is CACHED and is not
@@ -811,13 +485,16 @@ export class Engine {
 	 * @param {string} method the caller's name, for the rejection message
 	 * @param {Quill} quill
 	 * @param {Document} doc
-	 * @param {(ctx: { mod: any, engine: any, quill: any, doc: any }) => any} fn
+	 * @param {(ctx: { mod: any, engine: any, quill: any, doc: any, docWarnings: any[] }) => any} fn
 	 */
 	async #withClones(method, quill, doc, fn) {
 		const backendId = this.#backendOf(quill, method);
 		requireLocalDoc(doc, method);
-		const docJson = doc.toJson();
-		const quillTree = this.#quillClones.get(backendId)?.has(quill) ? null : quill.toTree();
+		const docJson = doc.toStored();
+		const docWarnings = doc.warnings;
+		const quillTree = this.#quillClones.get(this.#descriptorFor(backendId).load)?.has(quill)
+			? 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.
@@ -825,31 +502,33 @@ export class Engine {
 		const backendQuill = this.#cachedQuillClone(mod, backendId, quill, quillTree);
 		let backendDoc = null;
 		try {
-			backendDoc = mod.Document.fromJson(docJson);
-			return fn({ mod, engine, quill: backendQuill, doc: backendDoc });
+			backendDoc = mod.Document.fromStored(docJson);
+			return fn({ mod, engine, quill: backendQuill, doc: backendDoc, docWarnings });
 		} finally {
 			backendDoc?.free();
 		}
 	}
 
 	/**
-	 * Render `doc` against `quill` in one shot. Both handles are read
-	 * synchronously before the first await.
 	 * @param {Quill} quill
 	 * @param {Document} doc
-	 * @param {object} [options] render options (`{ format, ppi, pages, producer }`)
+	 * @param {object} [options] render options (`{ format, ppi, pages, regions }`)
 	 * @returns {Promise<import('./runtime.js').RenderResult>}
 	 */
 	async render(quill, doc, options) {
-		return this.#withClones('engine.render(quill, doc)', quill, doc, ({ engine, quill: q, doc: d }) =>
-			engine.render(q, d, options ?? undefined)
+		return this.#withClones(
+			'engine.render(quill, doc)',
+			quill,
+			doc,
+			({ engine, quill: q, doc: d, docWarnings }) => {
+				const result = engine.render(q, d, options ?? undefined);
+				result.warnings = docWarnings.concat(result.warnings);
+				return result;
+			}
 		);
 	}
 
 	/**
-	 * Open a live render session. It retains what `update` needs, so the
-	 * transient clones are freed before this returns; the caller owns the session
-	 * and must `.free()` it.
 	 * @param {Quill} quill
 	 * @param {Document} doc
 	 * @returns {Promise<LiveSession>}
@@ -864,8 +543,6 @@ export class Engine {
 	}
 
 	/**
-	 * The output formats `quill`'s backend can emit: an always-free probe over
-	 * the descriptor's manifest. `async` for API stability; it awaits nothing.
 	 * @param {Quill} quill
 	 * @returns {Promise<import('./runtime.js').OutputFormat[]>}
 	 */
@@ -874,29 +551,17 @@ export class Engine {
 		// Defensive copy so callers can't mutate the shared manifest.
 		return descriptor.formats.slice();
 	}
-
-	/**
-	 * Whether `quill`'s backend can paint to a canvas: a pre-session estimate over
-	 * the descriptor's manifest, so it can answer `true` where the resulting
-	 * `LiveSession.supportsCanvas` answers `false`.
-	 * @param {Quill} quill
-	 * @returns {Promise<boolean>}
-	 */
-	async supportsCanvas(quill) {
-		const descriptor = this.#descriptorFor(this.#backendOf(quill, 'engine.supportsCanvas(quill)'));
-		return descriptor.canvas;
-	}
 }
 
 /**
- * Thin wrapper over a backend's live render session; see `runtime.d.ts` for the
- * contract. The quill/document clones it was opened from have already been
- * freed: the session retains what `update` needs.
+ * Thin wrapper over a backend's live render session. The quill/document clones
+ * it was opened from have already been freed: the session retains what `update`
+ * needs.
  */
 export class LiveSession {
 	/**
-	 * @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
+	 * @param {object} inner the render build's LiveSession, whose members the delegations below name
+	 * @param {{ Document: { fromStored(json: string): any } }} mod the session's backend build, used to materialize `update` documents in its linear memory
 	 */
 	constructor(inner, mod) {
 		this.#inner = inner;
@@ -913,7 +578,7 @@ export class LiveSession {
 		requireLocalDoc(doc, 'session.update(doc)');
 		let backendDoc = null;
 		try {
-			backendDoc = this.#mod.Document.fromJson(doc.toJson());
+			backendDoc = this.#mod.Document.fromStored(doc.toStored());
 			return this.#inner.update(backendDoc);
 		} finally {
 			backendDoc?.free();
@@ -926,15 +591,6 @@ export class LiveSession {
 	get backendId() {
 		return this.#inner.backendId;
 	}
-	/**
-	 * `true` iff `paint`/`pageSize` will succeed for THIS compile: the
-	 * authoritative answer, which can be `false` where `Engine.supportsCanvas`
-	 * answered `true` for the same quill.
-	 * @returns {boolean}
-	 */
-	get supportsCanvas() {
-		return this.#inner.supportsCanvas;
-	}
 	get warnings() {
 		return this.#inner.warnings;
 	}
@@ -1009,28 +665,11 @@ export class LiveSession {
 	}
 }
 
-// ── 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 addressed `Document.storeField` verb.
+// These pure-JS classes bind a `quill` + `doc` pair once and delegate to the
+// `_commit*` / `_reader*` verbs, which take the quill per call. They hold JS
+// references to the caller's existing handles, so there is no WASM object of
+// their own, no `free()` burden, and no second owner of either handle.
 
-/**
- * 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;
@@ -1044,13 +683,10 @@ export class DocumentWriter {
 		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.
 	 * @param {string} name
 	 * @param {unknown} value
 	 * @returns {void}
@@ -1059,9 +695,6 @@ export class DocumentWriter {
 		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).
 	 * @param {Record<string, unknown>} fields
 	 * @returns {void}
 	 */
@@ -1069,8 +702,6 @@ export class DocumentWriter {
 		return this.#doc._commitFields(this.#quill, MAIN_CARD_ADDR, fields);
 	}
 	/**
-	 * Revise the main body from markdown; anchors rebase. A body carries no field
-	 * schema, so this is the content lane's `revise` reached through the writer.
 	 * @param {string} markdown
 	 * @returns {import('../core/wasm.js').Delta}
 	 */
@@ -1078,10 +709,6 @@ export class DocumentWriter {
 		return this.#doc.revise({}, markdown);
 	}
 	/**
-	 * Revise the content main-card field `name` from authored text: typed *and*
-	 * anchor-preserving. Anchors rebase, then the diffed result is
-	 * schema-conformed. The codec comes from the declared type: `richtext` diffs
-	 * markdown, `plaintext` the literal text.
 	 * @param {string} name
 	 * @param {string} text
 	 * @returns {import('../core/wasm.js').Delta}
@@ -1090,10 +717,6 @@ export class DocumentWriter {
 		return this.#doc._reviseField(this.#quill, name, text);
 	}
 	/**
-	 * Build a composable card of `kind`, typed-commit `fields` onto it, set its
-	 * body from optional markdown, and place it. Transactional: the card is
-	 * committed in full before it joins the document, so a rejected field, kind,
-	 * body, or position leaves the document untouched.
 	 * @param {string} kind
 	 * @param {Record<string, unknown>} [fields]
 	 * @param {string} [body]
@@ -1111,9 +734,6 @@ export class DocumentWriter {
 		return this.#doc.removeCard(index);
 	}
 	/**
-	 * A {@link CardWriter} bound to the composable card at `index`, checked
-	 * lazily at the write. It holds `index`, not the card, so a
-	 * `removeCard`/`addCard` between binding and writing silently retargets it.
 	 * @param {number} index
 	 * @returns {CardWriter}
 	 */
@@ -1122,11 +742,6 @@ export class DocumentWriter {
 	}
 }
 
-/**
- * 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;
@@ -1143,22 +758,16 @@ export class CardWriter {
 		this.#doc = doc;
 		this.#index = index;
 	}
-	/** The bound card index. */
 	get index() {
 		return this.#index;
 	}
 	/**
-	 * The bound card's `$kind`, empty string when it carries none. Throws
-	 * `IndexOutOfRange` for a bad bound index.
 	 * @returns {string}
 	 */
 	get kind() {
 		return this.#doc.card(this.#index).kind;
 	}
 	/**
-	 * Typed-commit one field on this card, addressed at `{ card, field }`. Throws
-	 * `UnknownField` for an undeclared name and `IndexOutOfRange` if the bound
-	 * index is out of range.
 	 * @param {string} name
 	 * @param {unknown} value
 	 * @returns {void}
@@ -1167,9 +776,6 @@ export class CardWriter {
 		return this.#doc._commitField(this.#quill, { card: this.#index, field: name }, value);
 	}
 	/**
-	 * Typed-commit several fields on this card atomically, addressed at
-	 * `{ card }`. 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}
 	 */
@@ -1177,7 +783,6 @@ export class CardWriter {
 		return this.#doc._commitFields(this.#quill, { card: this.#index }, fields);
 	}
 	/**
-	 * The card twin of {@link DocumentWriter.reviseBody}.
 	 * @param {string} markdown
 	 * @returns {import('../core/wasm.js').Delta}
 	 */
@@ -1185,8 +790,6 @@ export class CardWriter {
 		return this.#doc.revise({ card: this.#index }, markdown);
 	}
 	/**
-	 * The card twin of {@link DocumentWriter.reviseField}. Throws `UnknownField`
-	 * for an undeclared name and `IndexOutOfRange` for a bad bound index.
 	 * @param {string} name
 	 * @param {string} text
 	 * @returns {import('../core/wasm.js').Delta}
@@ -1196,13 +799,10 @@ export class CardWriter {
 	}
 }
 
-// ── `quill.writer(doc)`, the typed front door ──────────────────────────────
 // Patched onto the re-exported `Quill` prototype rather than wrapped, so
 // `Quill === CoreQuill` stays true: this only adds a method constructing the
 // pure-JS writer, which owns no WASM handle.
 /**
- * A {@link DocumentWriter} binding this quill's schema to `doc`. It holds both
- * handles by reference and owns neither: bind, write, discard.
  * @this {Quill}
  * @param {Document} doc the document to mutate, held by reference (not owned)
  * @returns {DocumentWriter}
@@ -1211,17 +811,10 @@ Quill.prototype.writer = function writer(doc) {
 	return new DocumentWriter(this, doc);
 };
 
-// ── Typed-reader sugar: the schema-plane read surface ─────────────────────────
 // The transport `Document.getStored` is schema-free, so an unknown field name
 // reads back `undefined` rather than as the typo it is. Binding the quill's
-// schema lets one `get` interpret by declared type and throw `UnknownField` on a
-// name the schema does not declare.
+// schema lets one `get` interpret by declared type and throw `UnknownField`.
 
-/**
- * A {@link Document} bound to its {@link Quill} for typed reads, the read
- * counterpart of {@link DocumentWriter}. Reads target the main card; use
- * {@link card} for a composable one. Owns neither handle.
- */
 export class DocumentReader {
 	#quill;
 	#doc;
@@ -1235,17 +828,10 @@ export class DocumentReader {
 		this.#quill = quill;
 		this.#doc = doc;
 	}
-	/** The bound document: the same instance passed in. */
 	get document() {
 		return this.#doc;
 	}
 	/**
-	 * Read the value at `addr`, interpreted by its declared type: a richtext field
-	 * 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, `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}
 	 */
@@ -1253,11 +839,6 @@ export class DocumentReader {
 		return this.#doc._readerGet(this.#quill, addr);
 	}
 	/**
-	 * Read the content field at `addr` as canonical `Content`: the twin of
-	 * {@link get}, which projects. 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, `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}
 	 */
@@ -1265,13 +846,6 @@ export class DocumentReader {
 		return this.#doc._readerGetContent(this.#quill, addr);
 	}
 	/**
-	 * Read the `Content` nested inside the composite field at `addr`, at `path`:
-	 * `[0]` an `array<richtext>` element, `["motto"]` an object's content property,
-	 * `[1, "notes"]` a leaf under both, `["controlled_by"]` a variant's cell. The
-	 * codec is the leaf's declared type's.
-	 * `undefined` for an absent field and for a path that names nothing stored;
-	 * throws `UnknownField`, `FieldNotContent` when `path` resolves to no content
-	 * leaf, `FieldDecode` anchored at the addressed path, and `IndexOutOfRange`.
 	 * @param {import('../core/wasm.js').Addr | string} addr
 	 * @param {import('../core/wasm.js').PathStep[]} path
 	 * @returns {import('../core/wasm.js').Content | undefined}
@@ -1280,16 +854,18 @@ export class DocumentReader {
 		return this.#doc._readerGetContentAt(this.#quill, addr, path);
 	}
 	/**
-	 * The main body's markdown: the quill-free body read. Equals `get({})`.
 	 * @returns {string}
 	 */
 	bodyMarkdown() {
 		return this.#doc._readerGet(this.#quill, {});
 	}
 	/**
-	 * A {@link CardReader} bound to the composable card at `index`, checked lazily
-	 * at the read. It holds `index`, not the card, so a `removeCard`/`addCard`
-	 * between binding and reading silently retargets it.
+	 * @returns {Resolved}
+	 */
+	resolve() {
+		return this.#quill._resolve(this.#doc);
+	}
+	/**
 	 * @param {number} index
 	 * @returns {CardReader}
 	 */
@@ -1298,11 +874,6 @@ export class DocumentReader {
 	}
 }
 
-/**
- * A single composable card bound to its {@link Quill} for typed reads, from
- * {@link DocumentReader.card}. Same `get` / `bodyMarkdown` verbs as
- * {@link DocumentReader}, reading the card at its bound index.
- */
 export class CardReader {
 	#quill;
 	#doc;
@@ -1319,22 +890,16 @@ export class CardReader {
 		this.#doc = doc;
 		this.#index = index;
 	}
-	/** The bound card index. */
 	get index() {
 		return this.#index;
 	}
 	/**
-	 * The bound card's `$kind` (empty string when it carries none), read through
-	 * the document. Throws `IndexOutOfRange` if the bound index is out of range.
 	 * @returns {string}
 	 */
 	get kind() {
 		return this.#doc.card(this.#index).kind;
 	}
 	/**
-	 * Read the field `name` on this card, interpreted by its declared type,
-	 * addressed at `{ card, field }`. `undefined` when absent; throws
-	 * `UnknownField` for an undeclared name and `IndexOutOfRange` for a bad index.
 	 * @param {string} name
 	 * @returns {unknown}
 	 */
@@ -1342,7 +907,6 @@ export class CardReader {
 		return this.#doc._readerGet(this.#quill, { card: this.#index, field: name });
 	}
 	/**
-	 * The card twin of {@link DocumentReader.getContent}.
 	 * @param {string} name
 	 * @returns {import('../core/wasm.js').Content | undefined}
 	 */
@@ -1350,7 +914,6 @@ export class CardReader {
 		return this.#doc._readerGetContent(this.#quill, { card: this.#index, field: name });
 	}
 	/**
-	 * The card twin of {@link DocumentReader.getContentAt}.
 	 * @param {string} name
 	 * @param {import('../core/wasm.js').PathStep[]} path
 	 * @returns {import('../core/wasm.js').Content | undefined}
@@ -1359,7 +922,6 @@ export class CardReader {
 		return this.#doc._readerGetContentAt(this.#quill, { card: this.#index, field: name }, path);
 	}
 	/**
-	 * The card twin of {@link DocumentReader.bodyMarkdown}.
 	 * @returns {string}
 	 */
 	bodyMarkdown() {
@@ -1367,11 +929,8 @@ export class CardReader {
 	}
 }
 
-// ── `quill.reader(doc)`: the schema-plane read front door ─────────────────────
 // Patched onto the same re-exported `Quill` prototype as `writer`.
 /**
- * A {@link DocumentReader} binding this quill's schema to `doc`. It holds both
- * handles by reference and owns neither: bind, read, discard.
  * @this {Quill}
  * @param {Document} doc the document to read, held by reference (not owned)
  * @returns {DocumentReader}