@quillmark/wasm 0.102.0 → 0.104.0

package/backends/typst/wasm.d.ts

@@ -181,6 +181,11 @@ export type ContentIsland = {
  * (`doc.storeField("qty", 3)`, `doc.revise("intro", md)`) the one coercion
  * rule. A bare number is *not* an addr (`{ card: 2 }` is the self-documenting
  * spelling), so no third navigation idiom re-fragments the surface.
+ *
+ * `doc.pathFor(addr)` mints the address as its canonical `DocPath` string, the
+ * anchor `Diagnostic.path` carries and `session.locate` / `session.fieldBoxes`
+ * take: a card path is kind-qualified, so building one by hand needs the card's
+ * `$kind`, and a wrong-kind path matches nothing silently.
  */
 export interface Addr {
     card?: number;
@@ -479,12 +484,32 @@ export interface QuillCardUi {
     groups?: Record<string, QuillGroupUi>;
 }
 
+/** A block construct a body can hold. `paragraph` is absent on purpose: it is
+ * the floor and cannot be declined. */
+export type QuillBlockConstruct =
+| "heading"
+| "rule"
+| "code"
+| "list"
+| "quote"
+| "table"
+| "image";
+
 /** Body namespace for a card (main or named card kind). */
 export interface QuillCardBody {
     /** When false, consumers must not accept or store body content for this card kind. Defaults to true. */
     enabled?: boolean;
     /** Example body content embedded verbatim in the blueprint body region. Fallback is "Write <card> body here." */
     example?: string;
+    /** Block constructs this quill's plate does not typeset in this body.
+     *
+     * Absent or empty means it declines nothing, which is the default. An
+     * editor reads this to decline a gesture before the author makes it; a body
+     * that holds one anyway draws a non-fatal `plate::unsupported_construct`
+     * warning carrying the construct and a count. It is the quill's claim about
+     * its own plate, and nothing verifies it: a construct absent from this list
+     * is not a promise that the plate typesets it. */
+    unsupported?: QuillBlockConstruct[];
 }
 
 /** Schema entry for a single field declared in a quill's `Quill.yaml`.
@@ -501,11 +526,8 @@ export interface QuillFieldSchema {
     description?: string;
     default?: unknown;
     example?: unknown;
-    /** Closed value domain. On `type: "enum"` declared as `values`; the
-     *  deprecated `enum` modifier on `type: "string"` is accepted for one
-     *  release. Both round-trip through this field. */
-    enum?: string[];
-    /** Required on `type: "enum"`: the closed set of allowed string values. */
+    /** Required on `type: "enum"`, and valid nowhere else: the closed set of
+     *  allowed string values. */
     values?: string[];
     ui?: QuillFieldUi;
     properties?: Record<string, QuillFieldSchema>;
@@ -752,7 +774,7 @@ export interface Location {
 }
 
 /**
- * What a committed `LiveSession.apply` changed. `dirtyPages` lists the pages
+ * What a committed `LiveSession.update` changed. `dirtyPages` lists the pages
  * whose rendered content differs from the previous compile, including pages
  * the edit added; removed pages are implied by `pageCount`. A preview
  * repaints `dirty ∩ visible` and nothing else.
@@ -812,6 +834,13 @@ export class Document {
      * verbs.
      */
     card(index: number): Card;
+    /**
+     * The composable card's own path, `cards.<kind>[index]`: the whole-card
+     * root [`pathFor`](Self::path_for) extends, for a consumer anchoring the
+     * card rather than one of its fields. Total on the index axis for the same
+     * reason, out of range renders `cards[index]`.
+     */
+    cardPath(index: number): string;
     clone(): Document;
     /**
      * Storage version this build writes via [`toJson`](Document::to_json).
@@ -959,6 +988,29 @@ export class Document {
      * not a canonical content object.
      */
     overwrite(addr: Addr | string, rt: Content): void;
+    /**
+     * `addr`'s canonical `DocPath` string, the anchor `Diagnostic.path`
+     * carries: `pathFor()` is `main.body`, `pathFor("intro")` `main.intro`,
+     * `pathFor({card: 2})` `cards.<kind>[2].body`. A consumer holding an
+     * `Addr` mints one without restating the kind lookup, the `Addr` defaults
+     * or the range guard.
+     *
+     * The kind is the card's stored `$kind` verbatim, the quill-free rule the
+     * addressed mutators anchor with and the geometry translation uses, not
+     * `validate`'s declared-kind filter: a `Document` holds a `$quill`
+     * reference and no schema. That is the one edge where this path and a
+     * `validate` diagnostic path differ for the same card.
+     *
+     * **Total on the index axis**, unlike the `Addr` reads (`getStored`,
+     * `isFill`, `bodyMarkdown`), which throw there: a path is an anchor, not
+     * a read. An out-of-range `{card: 7, field: "from"}` extends the
+     * unknown-kind root `edit::index_out_of_range` anchors at, rendering
+     * `cards[7].from`, which parses back and resolves to nothing rather than
+     * mis-targeting. So a per-keystroke call needs no `try`; a caller wanting
+     * a drop-it guard has [`cardCount`](Self::card_count). Only a malformed
+     * address throws.
+     */
+    pathFor(addr: Addr | string): string;
     /**
      * The canonical `$quill` reference grammar as author-facing text. Core is
      * the single source of truth: drive schema `describe` and validation
@@ -1513,6 +1565,7 @@ export interface InitOutput {
     readonly document_bodyMarkdown: (a: number, b: number, c: number) => void;
     readonly document_card: (a: number, b: number, c: number) => void;
     readonly document_cardCount: (a: number) => number;
+    readonly document_cardPath: (a: number, b: number, c: number) => void;
     readonly document_cards: (a: number, b: number) => void;
     readonly document_clone: (a: number) => number;
     readonly document_currentStorageVersion: (a: number) => void;
@@ -1532,6 +1585,7 @@ export interface InitOutput {
     readonly document_moveCard: (a: number, b: number, c: number, d: number) => void;
     readonly document_new: (a: number, b: number, c: number) => void;
     readonly document_overwrite: (a: number, b: number, c: number, d: number) => void;
+    readonly document_pathFor: (a: number, b: number, c: number) => void;
     readonly document_quillRef: (a: number, b: number) => void;
     readonly document_quillRefHint: (a: number) => void;
     readonly document_removeCard: (a: number, b: number, c: number) => void;

package/backends/typst/wasm.js

@@ -368,6 +368,30 @@ export class Document {
         const ret = wasm.document_cardCount(this.__wbg_ptr);
         return ret >>> 0;
     }
+    /**
+     * The composable card's own path, `cards.<kind>[index]`: the whole-card
+     * root [`pathFor`](Self::path_for) extends, for a consumer anchoring the
+     * card rather than one of its fields. Total on the index axis for the same
+     * reason, out of range renders `cards[index]`.
+     * @param {number} index
+     * @returns {string}
+     */
+    cardPath(index) {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.document_cardPath(retptr, this.__wbg_ptr, index);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            deferred1_0 = r0;
+            deferred1_1 = r1;
+            return getStringFromWasm0(r0, r1);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+            wasm.__wbindgen_export4(deferred1_0, deferred1_1, 1);
+        }
+    }
     /**
      * @returns {Card[]}
      */
@@ -815,6 +839,54 @@ export class Document {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
+    /**
+     * `addr`'s canonical `DocPath` string, the anchor `Diagnostic.path`
+     * carries: `pathFor()` is `main.body`, `pathFor("intro")` `main.intro`,
+     * `pathFor({card: 2})` `cards.<kind>[2].body`. A consumer holding an
+     * `Addr` mints one without restating the kind lookup, the `Addr` defaults
+     * or the range guard.
+     *
+     * The kind is the card's stored `$kind` verbatim, the quill-free rule the
+     * addressed mutators anchor with and the geometry translation uses, not
+     * `validate`'s declared-kind filter: a `Document` holds a `$quill`
+     * reference and no schema. That is the one edge where this path and a
+     * `validate` diagnostic path differ for the same card.
+     *
+     * **Total on the index axis**, unlike the `Addr` reads (`getStored`,
+     * `isFill`, `bodyMarkdown`), which throw there: a path is an anchor, not
+     * a read. An out-of-range `{card: 7, field: "from"}` extends the
+     * unknown-kind root `edit::index_out_of_range` anchors at, rendering
+     * `cards[7].from`, which parses back and resolves to nothing rather than
+     * mis-targeting. So a per-keystroke call needs no `try`; a caller wanting
+     * a drop-it guard has [`cardCount`](Self::card_count). Only a malformed
+     * address throws.
+     * @param {Addr | string} addr
+     * @returns {string}
+     */
+    pathFor(addr) {
+        let deferred2_0;
+        let deferred2_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.document_pathFor(retptr, this.__wbg_ptr, addHeapObject(addr));
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+            var ptr1 = r0;
+            var len1 = r1;
+            if (r3) {
+                ptr1 = 0; len1 = 0;
+                throw takeObject(r2);
+            }
+            deferred2_0 = ptr1;
+            deferred2_1 = len1;
+            return getStringFromWasm0(ptr1, len1);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+            wasm.__wbindgen_export4(deferred2_0, deferred2_1, 1);
+        }
+    }
     /**
      * @returns {string}
      */
@@ -2909,8 +2981,7 @@ if (!('encodeInto' in cachedTextEncoder)) {
 
 let WASM_VECTOR_LEN = 0;
 
-import { uninitSentinel, UNINIT } from "../../runtime/uninit.js";
-let wasmModule, wasm = uninitSentinel("@quillmark/wasm internal error: the 'typst' backend was used before instantiation.", "This is a bug in @quillmark/wasm, not in your code. Please report it.");
+let wasmModule, wasm;
 function __wbg_finalize_init(instance, module) {
     wasm = instance.exports;
     wasmModule = module;
@@ -2957,7 +3028,7 @@ async function __wbg_load(module, imports) {
 }
 
 function initSync(module) {
-    if (wasm !== undefined && !wasm[UNINIT]) return wasm;
+    if (wasm !== undefined) return wasm;
 
 
     if (module !== undefined) {
@@ -2977,7 +3048,7 @@ function initSync(module) {
 }
 
 async function __wbg_init(module_or_path) {
-    if (wasm !== undefined && !wasm[UNINIT]) return wasm;
+    if (wasm !== undefined) return wasm;
 
 
     if (module_or_path !== undefined) {

package/backends/typst/wasm_bg.wasm.d.ts

@@ -16,6 +16,7 @@ export const document_blueprintInstruction: (a: number, b: number, c: number) =>
 export const document_bodyMarkdown: (a: number, b: number, c: number) => void;
 export const document_card: (a: number, b: number, c: number) => void;
 export const document_cardCount: (a: number) => number;
+export const document_cardPath: (a: number, b: number, c: number) => void;
 export const document_cards: (a: number, b: number) => void;
 export const document_clone: (a: number) => number;
 export const document_currentStorageVersion: (a: number) => void;
@@ -35,6 +36,7 @@ export const document_makeCard: (a: number, b: number, c: number, d: number, e:
 export const document_moveCard: (a: number, b: number, c: number, d: number) => void;
 export const document_new: (a: number, b: number, c: number) => void;
 export const document_overwrite: (a: number, b: number, c: number, d: number) => void;
+export const document_pathFor: (a: number, b: number, c: number) => void;
 export const document_quillRef: (a: number, b: number) => void;
 export const document_quillRefHint: (a: number) => void;
 export const document_removeCard: (a: number, b: number, c: number) => void;

package/core/wasm.d.ts

@@ -181,6 +181,11 @@ export type ContentIsland = {
  * (`doc.storeField("qty", 3)`, `doc.revise("intro", md)`) the one coercion
  * rule. A bare number is *not* an addr (`{ card: 2 }` is the self-documenting
  * spelling), so no third navigation idiom re-fragments the surface.
+ *
+ * `doc.pathFor(addr)` mints the address as its canonical `DocPath` string, the
+ * anchor `Diagnostic.path` carries and `session.locate` / `session.fieldBoxes`
+ * take: a card path is kind-qualified, so building one by hand needs the card's
+ * `$kind`, and a wrong-kind path matches nothing silently.
  */
 export interface Addr {
     card?: number;
@@ -394,12 +399,32 @@ export interface QuillCardUi {
     groups?: Record<string, QuillGroupUi>;
 }
 
+/** A block construct a body can hold. `paragraph` is absent on purpose: it is
+ * the floor and cannot be declined. */
+export type QuillBlockConstruct =
+| "heading"
+| "rule"
+| "code"
+| "list"
+| "quote"
+| "table"
+| "image";
+
 /** Body namespace for a card (main or named card kind). */
 export interface QuillCardBody {
     /** When false, consumers must not accept or store body content for this card kind. Defaults to true. */
     enabled?: boolean;
     /** Example body content embedded verbatim in the blueprint body region. Fallback is "Write <card> body here." */
     example?: string;
+    /** Block constructs this quill's plate does not typeset in this body.
+     *
+     * Absent or empty means it declines nothing, which is the default. An
+     * editor reads this to decline a gesture before the author makes it; a body
+     * that holds one anyway draws a non-fatal `plate::unsupported_construct`
+     * warning carrying the construct and a count. It is the quill's claim about
+     * its own plate, and nothing verifies it: a construct absent from this list
+     * is not a promise that the plate typesets it. */
+    unsupported?: QuillBlockConstruct[];
 }
 
 /** Schema entry for a single field declared in a quill's `Quill.yaml`.
@@ -416,11 +441,8 @@ export interface QuillFieldSchema {
     description?: string;
     default?: unknown;
     example?: unknown;
-    /** Closed value domain. On `type: "enum"` declared as `values`; the
-     *  deprecated `enum` modifier on `type: "string"` is accepted for one
-     *  release. Both round-trip through this field. */
-    enum?: string[];
-    /** Required on `type: "enum"`: the closed set of allowed string values. */
+    /** Required on `type: "enum"`, and valid nowhere else: the closed set of
+     *  allowed string values. */
     values?: string[];
     ui?: QuillFieldUi;
     properties?: Record<string, QuillFieldSchema>;
@@ -560,6 +582,13 @@ export class Document {
      * verbs.
      */
     card(index: number): Card;
+    /**
+     * The composable card's own path, `cards.<kind>[index]`: the whole-card
+     * root [`pathFor`](Self::path_for) extends, for a consumer anchoring the
+     * card rather than one of its fields. Total on the index axis for the same
+     * reason, out of range renders `cards[index]`.
+     */
+    cardPath(index: number): string;
     clone(): Document;
     /**
      * Storage version this build writes via [`toJson`](Document::to_json).
@@ -707,6 +736,29 @@ export class Document {
      * not a canonical content object.
      */
     overwrite(addr: Addr | string, rt: Content): void;
+    /**
+     * `addr`'s canonical `DocPath` string, the anchor `Diagnostic.path`
+     * carries: `pathFor()` is `main.body`, `pathFor("intro")` `main.intro`,
+     * `pathFor({card: 2})` `cards.<kind>[2].body`. A consumer holding an
+     * `Addr` mints one without restating the kind lookup, the `Addr` defaults
+     * or the range guard.
+     *
+     * The kind is the card's stored `$kind` verbatim, the quill-free rule the
+     * addressed mutators anchor with and the geometry translation uses, not
+     * `validate`'s declared-kind filter: a `Document` holds a `$quill`
+     * reference and no schema. That is the one edge where this path and a
+     * `validate` diagnostic path differ for the same card.
+     *
+     * **Total on the index axis**, unlike the `Addr` reads (`getStored`,
+     * `isFill`, `bodyMarkdown`), which throw there: a path is an anchor, not
+     * a read. An out-of-range `{card: 7, field: "from"}` extends the
+     * unknown-kind root `edit::index_out_of_range` anchors at, rendering
+     * `cards[7].from`, which parses back and resolves to nothing rather than
+     * mis-targeting. So a per-keystroke call needs no `try`; a caller wanting
+     * a drop-it guard has [`cardCount`](Self::card_count). Only a malformed
+     * address throws.
+     */
+    pathFor(addr: Addr | string): string;
     /**
      * The canonical `$quill` reference grammar as author-facing text. Core is
      * the single source of truth: drive schema `describe` and validation
@@ -1097,6 +1149,7 @@ export interface InitOutput {
     readonly document_bodyMarkdown: (a: number, b: number, c: number) => void;
     readonly document_card: (a: number, b: number, c: number) => void;
     readonly document_cardCount: (a: number) => number;
+    readonly document_cardPath: (a: number, b: number, c: number) => void;
     readonly document_cards: (a: number, b: number) => void;
     readonly document_clone: (a: number) => number;
     readonly document_currentStorageVersion: (a: number) => void;
@@ -1116,6 +1169,7 @@ export interface InitOutput {
     readonly document_moveCard: (a: number, b: number, c: number, d: number) => void;
     readonly document_new: (a: number, b: number, c: number) => void;
     readonly document_overwrite: (a: number, b: number, c: number, d: number) => void;
+    readonly document_pathFor: (a: number, b: number, c: number) => void;
     readonly document_quillRef: (a: number, b: number) => void;
     readonly document_quillRefHint: (a: number) => void;
     readonly document_removeCard: (a: number, b: number, c: number) => void;

package/core/wasm.js

@@ -368,6 +368,30 @@ export class Document {
         const ret = wasm.document_cardCount(this.__wbg_ptr);
         return ret >>> 0;
     }
+    /**
+     * The composable card's own path, `cards.<kind>[index]`: the whole-card
+     * root [`pathFor`](Self::path_for) extends, for a consumer anchoring the
+     * card rather than one of its fields. Total on the index axis for the same
+     * reason, out of range renders `cards[index]`.
+     * @param {number} index
+     * @returns {string}
+     */
+    cardPath(index) {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.document_cardPath(retptr, this.__wbg_ptr, index);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            deferred1_0 = r0;
+            deferred1_1 = r1;
+            return getStringFromWasm0(r0, r1);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+            wasm.__wbindgen_export4(deferred1_0, deferred1_1, 1);
+        }
+    }
     /**
      * @returns {Card[]}
      */
@@ -815,6 +839,54 @@ export class Document {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
+    /**
+     * `addr`'s canonical `DocPath` string, the anchor `Diagnostic.path`
+     * carries: `pathFor()` is `main.body`, `pathFor("intro")` `main.intro`,
+     * `pathFor({card: 2})` `cards.<kind>[2].body`. A consumer holding an
+     * `Addr` mints one without restating the kind lookup, the `Addr` defaults
+     * or the range guard.
+     *
+     * The kind is the card's stored `$kind` verbatim, the quill-free rule the
+     * addressed mutators anchor with and the geometry translation uses, not
+     * `validate`'s declared-kind filter: a `Document` holds a `$quill`
+     * reference and no schema. That is the one edge where this path and a
+     * `validate` diagnostic path differ for the same card.
+     *
+     * **Total on the index axis**, unlike the `Addr` reads (`getStored`,
+     * `isFill`, `bodyMarkdown`), which throw there: a path is an anchor, not
+     * a read. An out-of-range `{card: 7, field: "from"}` extends the
+     * unknown-kind root `edit::index_out_of_range` anchors at, rendering
+     * `cards[7].from`, which parses back and resolves to nothing rather than
+     * mis-targeting. So a per-keystroke call needs no `try`; a caller wanting
+     * a drop-it guard has [`cardCount`](Self::card_count). Only a malformed
+     * address throws.
+     * @param {Addr | string} addr
+     * @returns {string}
+     */
+    pathFor(addr) {
+        let deferred2_0;
+        let deferred2_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.document_pathFor(retptr, this.__wbg_ptr, addHeapObject(addr));
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+            var ptr1 = r0;
+            var len1 = r1;
+            if (r3) {
+                ptr1 = 0; len1 = 0;
+                throw takeObject(r2);
+            }
+            deferred2_0 = ptr1;
+            deferred2_1 = len1;
+            return getStringFromWasm0(ptr1, len1);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+            wasm.__wbindgen_export4(deferred2_0, deferred2_1, 1);
+        }
+    }
     /**
      * @returns {string}
      */
@@ -2377,8 +2449,7 @@ if (!('encodeInto' in cachedTextEncoder)) {
 
 let WASM_VECTOR_LEN = 0;
 
-import { uninitSentinel, UNINIT } from "../runtime/uninit.js";
-let wasmModule, wasm = uninitSentinel("@quillmark/wasm is not initialized. Call 'await init()' once at startup, before Quill, Document, Engine, or any other export is used.", "Add: import { init } from '@quillmark/wasm'; await init(); once, anywhere before first use. Extra calls are free.");
+let wasmModule, wasm;
 function __wbg_finalize_init(instance, module) {
     wasm = instance.exports;
     wasmModule = module;
@@ -2424,7 +2495,7 @@ async function __wbg_load(module, imports) {
 }
 
 function initSync(module) {
-    if (wasm !== undefined && !wasm[UNINIT]) return wasm;
+    if (wasm !== undefined) return wasm;
 
 
     if (module !== undefined) {
@@ -2444,7 +2515,7 @@ function initSync(module) {
 }
 
 async function __wbg_init(module_or_path) {
-    if (wasm !== undefined && !wasm[UNINIT]) return wasm;
+    if (wasm !== undefined) return wasm;
 
 
     if (module_or_path !== undefined) {

package/core/wasm_bg.wasm.d.ts

@@ -14,6 +14,7 @@ export const document_blueprintInstruction: (a: number, b: number, c: number) =>
 export const document_bodyMarkdown: (a: number, b: number, c: number) => void;
 export const document_card: (a: number, b: number, c: number) => void;
 export const document_cardCount: (a: number) => number;
+export const document_cardPath: (a: number, b: number, c: number) => void;
 export const document_cards: (a: number, b: number) => void;
 export const document_clone: (a: number) => number;
 export const document_currentStorageVersion: (a: number) => void;
@@ -33,6 +34,7 @@ export const document_makeCard: (a: number, b: number, c: number, d: number, e:
 export const document_moveCard: (a: number, b: number, c: number, d: number) => void;
 export const document_new: (a: number, b: number, c: number) => void;
 export const document_overwrite: (a: number, b: number, c: number, d: number) => void;
+export const document_pathFor: (a: number, b: number, c: number) => void;
 export const document_quillRef: (a: number, b: number) => void;
 export const document_quillRefHint: (a: number) => void;
 export const document_removeCard: (a: number, b: number, c: number) => void;

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@quillmark/wasm",
-  "version": "0.102.0",
+  "version": "0.104.0",
   "description": "WebAssembly bindings for Quillmark, a schema-driven document engine",
   "type": "module",
   "license": "Apache-2.0",
   "engines": {
-    "node": ">=22"
+    "node": ">=24"
   },
   "repository": {
     "type": "git",

package/runtime/runtime.d.ts

@@ -1,46 +1,82 @@
 // @quillmark/wasm/runtime: canonical consumer API.
 //
-// `Quill`/`Document` are re-exported verbatim from the core build (their full
-// surface, no drift). Render-side types (`RenderResult`, `RenderOptions`,
-// `Artifact`, `OutputFormat`, `PageSize`, `PaintOptions`, `PaintResult`) are
-// defined HERE as the canonical, backend-neutral render contract: NOT sourced
-// from any one private backend build. A type-level drift guard
-// (`runtime.types.test-d.ts`, via `npm run typecheck`) asserts they stay
-// mutually assignable with the Typst backend's generated declarations. `Engine`
-// is the render dispatcher that hides the cross-WASM-memory seam.
-
-// CANONICAL INVARIANT: the root re-exports the core build's `Quill`/`Document`
-// verbatim; they are the SAME classes, never wrappers. There is exactly one
-// public entry point, so this is a structural fact. Replacing the re-export
-// with a wrapper is a breaking design change, not a refactor. See runtime.js.
+// Render-side types (`RenderResult`, `RenderOptions`, `Artifact`,
+// `OutputFormat`, `PageSize`, `PaintOptions`, `PaintResult`) are defined HERE as
+// the canonical, backend-neutral render contract: NOT sourced from any one
+// private backend build. A type-level drift guard (`runtime.types.test-d.ts`,
+// via `npm run typecheck`) asserts they stay mutually assignable with the Typst
+// backend's generated declarations. `Engine` is the render dispatcher that hides
+// the cross-WASM-memory seam.
+
+// CANONICAL INVARIANT: the `Quill`/`Document` `init` resolves to ARE the core
+// build's classes, their full surface, never wrappers. There is exactly one
+// public entry point, so this is a structural fact. Handing out a wrapper is a
+// breaking design change, not a refactor. See runtime.js.
 //
 // ONE COPY PER PROCESS: two copies of this package are two WASM linear memories
 // and two `Quill`/`Document` classes. Every method taking a handle refuses one
 // belonging to another copy, with a `QuillmarkError` naming `npm ls
 // @quillmark/wasm`. Errors are the exception: `isQuillmarkError` is structural.
-export { Quill, Document } from '../core/wasm.js';
 
-import type { InitInput } from '../core/wasm.js';
+// The instance types, so an annotation (`let q: Quill`) needs no await. Their
+// values are `CoreSurface`'s.
+export type { Quill, Document } from '../core/wasm.js';
+
+import type {
+	InitInput,
+	Quill as CoreQuill,
+	Document as CoreDocument,
+	importMarkdown,
+	exportMarkdown,
+	rebase,
+	mapPos,
+	parseDocPath,
+	formatDocPath
+} from '../core/wasm.js';
 
 /**
- * Instantiate the core WASM build. Call once at startup, before any other
- * export is used; extra calls are free.
+ * The core build's surface: what its WASM instance stands behind, and therefore
+ * what `init` resolves to. Exported nowhere statically, so awaiting is the only
+ * way to hold one.
  *
- * ```js
- * import { init, Quill, Engine } from '@quillmark/wasm';
- * await init();
+ * `Quill` and `Document` here are the classes, statics included
+ * (`Quill.fromTree`, `Document.fromMarkdown`), not the instance types above.
+ * Each member carries the core build's own declaration, docs and all.
+ */
+export interface CoreSurface {
+	Quill: typeof CoreQuill;
+	Document: typeof CoreDocument;
+	importMarkdown: typeof importMarkdown;
+	exportMarkdown: typeof exportMarkdown;
+	rebase: typeof rebase;
+	mapPos: typeof mapPos;
+	parseDocPath: typeof parseDocPath;
+	formatDocPath: typeof formatDocPath;
+}
+
+/**
+ * Instantiate the core WASM build and resolve to its surface.
+ *
+ * ```ts
+ * import { init } from '@quillmark/wasm';
+ * const { Quill, Document } = await init();
  * ```
  *
  * The builds are `--target web`: classes export synchronously, the instance
  * behind them arrives here. Identical in every environment: the binary is
  * fetched and streamed in a browser, read off disk under Node, and the call
- * site is the same line. Reaching a class before this resolves throws
- * `runtime::not_initialized` naming the fix.
+ * site is the same line.
+ *
+ * THE ONLY DOOR to `Quill`, `Document` and the free functions, 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 and concurrency-safe, so every await after the first is free. A
+ * failed init clears the memo, so a retry is possible. Per realm: a Worker
+ * loads and initializes its own copy.
  *
- * Idempotent and concurrency-safe: every call returns the same promise, so
- * `await init()` at several entry points costs one instantiation. A failed init
- * clears the memo, so a retry is possible. Per realm: a Worker loads and
- * initializes its own copy.
+ * Both failure codes REJECT, so one `catch` covers the gate. Delivery follows
+ * the function kind across this surface: a sync verb throws, a
+ * promise-returning verb rejects, and nothing does both.
  *
  * Backends are NOT initialized here. `Engine` instantiates a backend inside its
  * lazy load, on first render against it.
@@ -48,15 +84,10 @@ import type { InitInput } from '../core/wasm.js';
  * @param 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
+ *   different source rejects with `runtime::init_conflict` rather than silently
  *   ignoring it. Passing the same value again is fine.
  */
-export declare function init(source?: InitInput): Promise<void>;
-// The document-free content codec, re-exported from the core build.
-export { importMarkdown, exportMarkdown, rebase, mapPos } from '../core/wasm.js';
-// The document-model path parser/serializer: route on `Diagnostic.path`
-// segments instead of regexing the string.
-export { parseDocPath, formatDocPath } from '../core/wasm.js';
+export declare function init(source?: InitInput): Promise<CoreSurface>;
 
 import type { CardAddr } from '../core/wasm.js';
 
@@ -367,7 +398,10 @@ export interface FieldRegion {
 	 * The field's canonical `DocPath` address (`parseDocPath`-routable), not a
 	 * backend widget name: `main.signature_block` for a main field,
 	 * `cards.<kind>[<i>].signature_block` for a card field (`cards[<i>].…` when the
-	 * card's kind is unknown).
+	 * card's kind is unknown). Nested addresses spell out in full, an array
+	 * element bracketed and a key dotted — `main.references[0]`,
+	 * `cards.<kind>[<i>].addr.city` — the same spelling `Diagnostic.path` uses,
+	 * so the two join on string equality.
 	 */
 	field: string;
 	/** 0-based page index. */