@quillmark/wasm 0.102.0 → 0.104.0

package/CHANGELOG.md

@@ -1,5 +1,175 @@
 # Changelog
 
+## v0.104.0 - 2026-08-13
+
+- feat(core,wasm): a quill declares, per body, the block constructs its plate
+  does not typeset (`main.body.unsupported`, `card_kinds.<k>.body.unsupported`;
+  names from `heading`, `rule`, `code`, `list`, `quote`, `table`, `image`).
+  A body holding one anyway draws the non-fatal `plate::unsupported_construct`,
+  a fifth warning family, on the pre-render walk `Quill::parse` runs beside
+  `conform`: one diagnostic per (body, construct) carrying the count in `args`
+  and the body's path, so occurrences collapse rather than scatter. The
+  declaration also rides `QuillConfig::schema()` to the editor, which is the
+  half a render-time warning could not serve: it answers before the gesture.
+  Nothing verifies a declaration — a plate that drops an undeclared construct
+  stays as silent as before. `usaf_memo` declares `rule`; empty everywhere
+  else, so no existing quill's schema or warnings change.
+- fix(fixtures): `usaf_memo`'s `render-body` drained its heading buffer in the
+  three shapes that used to discard it. A heading with nothing after it (the
+  buffer died with the loop, taking a list item's bullet with it), a heading
+  whose next element opened a *different* list item (its text was delivered
+  into that item), and a heading following a heading (the assignment overwrote
+  the earlier one) each lost their text with nothing in the render to say so.
+  The run-in style is unchanged where it was right: a heading joins the next
+  block of its own item, or the next paragraph at top level.
+- fix(content)!: `to_markdown` writes `***` for a thematic break, not `---`.
+  `- ` + `---` is four dashes separated by spaces, which re-imports as a
+  top-level break, so a rule as a bullet item's first block lost its item on
+  every markdown round-trip. The canonical spelling is now the one with the
+  fewest other readings (`---` is also a setext underline and the root-block
+  front-matter opener). Exported markdown changes for documents holding a
+  rule; the content model, wire data and rendered output do not.
+- refactor(core,pdfform,cli,wasm)!: the `enum:` modifier on `type: string`
+  retires. `type: enum` with a `values:` list is the one spelling of a finite
+  string domain; `enum:` on any type is now `quill::field_parse_error`, whose
+  message names the replacement — it is the only diagnostic a quill written
+  against the modifier ever received, since the deprecation shipped in 0.94
+  with no warning code behind it. `QuillConfig::schema()` re-emits every
+  domain as `values:`, so a consumer reading `enum:` off the schema echo (the
+  wasm `QuillFieldSchema.enum`, dropped here) reads `values:` instead. The
+  `usaf_memo` and `sample_form` fixtures migrate; wire data and rendered
+  output are unchanged, the projections being domain-keyed already.
+- fix(core): `build_transform_schema` keys a field's finite domain on the
+  domain itself rather than the `Enum` token, joining the render floor, the
+  pdfform widget kind and the blueprint annotation. Under the retired
+  spelling every `usaf_memo` enum — `classification`, `format`, `action` —
+  projected as a bare `{"type":"string"}`, so a consumer building a
+  JSON-Schema validator from the transform schema accepted
+  `classification: "banana"` while pdfform drew the six-option dropdown for
+  the same field and `QuillConfig` rejected the value at coercion (#1237)
+- fix(core)!: geometry addresses parse segment-wise, so `locate` and
+  `fieldBoxes` answer for an address deeper than one segment. The translation
+  boundary folded a plate address's whole tail into one `Field`, so
+  `references.0` minted `main.references.0` — a string that reparses as a field
+  literally named `0`, and that the reverse direction refused outright. Both
+  spellings returned `None`, leaving caret placement and whole-field highlight
+  dead for **every** `array<richtext>` element (the flagship memo's
+  `references` among them) and for every nested key a pdfform widget binds
+  (`address.city`). `region.rs` now reads and renders a plate tail one segment
+  at a time: an all-digit segment is an array index, `$body` the body terminal,
+  anything else a field or map key.
+- change(wasm, python)!: `RenderedRegion.field`, `FieldRegion.field` and
+  `ContentHit.field` spell an array element bracketed — `main.references.0`
+  becomes `main.references[0]` — on `regions()`, `fieldAt`, `positionAt` and
+  `RenderResult.regions`. This is the spelling schema validation already emits,
+  so a `Diagnostic.path` and the geometry address for one place are now the same
+  string. A consumer finding an address's children by prefix (`startsWith(`${field}.`)`)
+  needs the `[` opener too, and any heuristic reading a trailing all-digit field
+  name as a lost index is dead.
+- feat(wasm): `doc.pathFor(addr)` mints an `Addr` as the canonical `DocPath`
+  string `Diagnostic.path` carries and `session.locate` / `session.fieldBoxes`
+  take; `doc.cardPath(i)` is the card's own root. `Document` computed the
+  kind-qualified root for every addressed write and did not hand it out, so a
+  consumer building a path restated the kind lookup, the `Addr` defaults and the
+  range guard — and a wrong-kind path is compared as a string, matching nothing
+  and drawing no highlight without throwing. Both are quill-free (the stored
+  `$kind` verbatim) and total on the index axis: a path is an anchor, not a
+  read, so a per-keystroke call needs no `try` (#1225)
+- change(wasm)!: `@quillmark/wasm` declares `engines: { node: ">=24" }`, the
+  tier CI builds and tests the bindings on and the one both devcontainers hand a
+  contributor. Nothing in the package requires it at runtime, so a Node 22
+  install fails `engines` checking without failing at import.
+- docs: `docs/migrations/0.103-to-0.104.md` carries the four breaks — the
+  retired `enum:` modifier, the bracketed index spelling, the `***` thematic
+  break and the Node floor — with the prefix-match, trailing-digit and stored
+  -markdown shapes a consumer has to fix, and the two additive surfaces
+  (`pathFor` / `cardPath`, and the `plate::unsupported_construct` family a
+  code-routing consumer gains an arm for).
+- test(core): three characterization tests pin the render floor's two
+  type-domain edges (a defaultless enum, top-level and nested in a typed
+  dictionary) and an authored empty `date` beside an empty `string`, so the
+  coercion difference between the two is one test's diff. Every shipped quill
+  declares a `default:` on every enum and none authors an empty `date`, so the
+  fixture suite reached neither path. A fourth carries a `!must_fill` tag on two
+  example-seeded cells through seed → store → load → conform. Refs #1234
+
+<!-- seed: commits since v0.103.0, confirm the entries above cover them, then delete this comment
+- Carry the thematic-break and unsupported-construct work into the guide
+- Dense-prose pass over the new comments and docs
+- Let a quill declare the constructs its plate does not typeset
+- Drain the memo's heading buffer instead of dropping it
+- Canonicalize a thematic break to `***`
+- Close the 0.104 release gaps: the migration guide, and four changelog entries
+- Retire the enum: modifier; project a field's domain by capability
+- Pin the render floor's two type-domain edges and the seeded fill tag
+- Raise the Node floor to 24
+- dense-prose pass over the added prose
+- docs: dense-prose pass on the text-type sections
+- docs: give the text-type choice a decision procedure
+- docs: state the backend seam's scope and reserve its namespaces
+- docs: drop the private intra-doc link from pathFor
+- fix(core): state the unspellable-tail conditions instead of linking a private fn
+- chore(wasm): density pass, and gate a core-build dead function
+- docs: dense-prose pass over the geometry-address translation
+- docs: dense-prose pass over the pathFor / cardPath prose
+- test(wasm): execute the static-export exemption instead of listing it
+- feat(wasm): mint a DocPath from an Addr (#1225)
+- fix(core)!: parse geometry addresses segment-wise (#1223)
+- docs: carry the 0.103 CLI break, and the init gate into the quickstart (#1222)
+- SCHEMAS.md: a declared type change rewrites stored values (#1221)
+-->
+
+
+## v0.103.0 - 2026-08-09
+
+- docs: `docs/integration/operations.md`, carrying what the other integration
+  pages leave unsaid: that **render is not bounded** — no deadline, no
+  cancellation, and the parse limits do not carry through — with the
+  worker-termination recipe that is the only abort a browser has; that
+  `Quillmark`, `Quill` and `Document` are `Send + Sync`, pinned by a test rather
+  than asserted; `comemo` eviction as what a long-lived process's memory tracks;
+  the no-network, no-ambient-filesystem isolation properties; and that a panic
+  is terminal on every surface.
+- docs: `parse::input_too_large` carries four of the five §8 caps, separable
+  only by its `max` arg, which `error-handling.md` now says where it names the
+  code.
+- test(cli): `quillmark-cli` gets its first tests. The bin carries
+  `test = false`, so twelve cases drive the built executable instead — every
+  subcommand, `-o` and `--stdout`, PDF and SVG output, and the error paths,
+  which must exit 1 rather than panic. The crate had no `[dev-dependencies]`
+  and no workflow invoked it (#1068).
+- fix(cli)!: `render --verbose` writes its progress lines to stderr, as the
+  warning printer already did. Under `--stdout` they went to stdout ahead of and
+  after the artifact, so `quillmark render q --stdout --verbose > out.pdf`
+  produced a PDF with `Loading quill from: …` before its header and
+  `Rendering completed successfully` past its trailer. A script that parses
+  `--verbose` output from stdout reads it from stderr now.
+- test(fuzz): `pdf_fuzz` covers the AcroForm stamp spine's byte-level reads,
+  the one hand-rolled parser with no fuzz target. Arbitrary bytes, and a real
+  form truncated, single-byte-corrupted, or spliced, all through
+  `page_media_boxes` / `PdfUpdate::begin` / `stamp`. The oracle is no panic:
+  nothing in the workspace catches unwind, so a panic there kills the CLI and
+  the Python extension and poisons the WASM module. No failures found.
+- fix(core): `MAX_FIELD_COUNT`'s rustdoc said "per document"; the check is per
+  card-yaml block, counted after `$`-key extraction.
+- refactor(wasm)!: `init()` resolves to the core surface, and it is the only way
+  to reach one. `Quill`, `Document`, `importMarkdown`, `exportMarkdown`,
+  `rebase`, `mapPos`, `parseDocPath` and `formatDocPath` leave the static
+  exports of `@quillmark/wasm`: `const { Quill, Document } = await init()`
+  replaces the value import. The precondition was carried entirely by
+  `init`'s signature, and a floating promise is an ESLint rule rather than a
+  `tsc` diagnostic, so a call site that skipped the await type-checked and then
+  passed or failed by load order. It now has no name to call. `Engine`,
+  `MAIN_CARD_ADDR`, `isQuillmarkError`, the open-set guards and the
+  writer/reader classes are unchanged, needing no instance or gated by their
+  arguments; the `Quill` / `Document` **type** exports are unchanged, so
+  annotations and `import type` compile as before. Class identity is untouched:
+  the gate hands out the core build's classes verbatim, and `instanceof` stays
+  the whole membership test. `runtime::not_initialized` and the build-time
+  sentinel that raised it retire with the door they guarded. Rust, Python,
+  documents and stored blobs are unaffected. See
+  `docs/migrations/0.102-to-0.103.md`
+
 ## v0.102.0 - 2026-08-04
 
 The pre-1.0 vocabulary reset. Verbs, diagnostic codes, and two words that meant

package/README.md

@@ -10,11 +10,11 @@ Use Quillmark in browsers/Node.js with explicit in-memory trees (`Map<string, Ui
 
 The package exposes **one import surface**:
 
-- `@quillmark/wasm` (the root), the **canonical API**: `Quill`, `Document`, and
-  an `Engine` that renders them.
+- `@quillmark/wasm` (the root), the **canonical API**: `init`, resolving to
+  `Quill` and `Document`, and an `Engine` that renders them.
 
-`Quill` and `Document` are re-exported verbatim from the internal Typst-less
-core build, so editor/validation code (`Quill.fromTree`,
+`Quill` and `Document` are the internal Typst-less core build's own classes,
+handed out verbatim by `init`, so editor/validation code (`Quill.fromTree`,
 `Document.fromMarkdown`) loads only that small core binary: no backend is
 loaded until you render. The `Engine` hides everything else: each backend
 (`typst`, `pdfform`) is a separate, private WASM binary with its own linear
@@ -31,9 +31,8 @@ bash scripts/build-wasm.sh
 The script builds three variants: the core (no backend), the Typst backend
 (default features), and the Typst-free pdfform backend (`pdfform` feature):
 each with `--target web` and `--weak-refs` enabled (see
-[Initialization](#initialization) and [Lifecycle](#lifecycle)). It then patches
-each generated build with the pre-init sentinel (`runtime/uninit.js`) and
-asserts none of them carries a `.wasm` ESM import or a top-level await.
+[Initialization](#initialization) and [Lifecycle](#lifecycle)). It then asserts
+none of them carries a `.wasm` ESM import or a top-level await.
 
 ## Test
 
@@ -47,9 +46,9 @@ npm test
 ## Usage
 
 ```ts
-import { init, Document, Quill, Engine } from "@quillmark/wasm";
+import { init, Engine } from "@quillmark/wasm";
 
-await init();                         // once at startup; see Initialization
+const { Quill, Document } = await init(); // see Initialization
 
 const quill = Quill.fromTree(tree);   // no engine needed: build + validate
 const engine = new Engine();          // loads a backend lazily on first render
@@ -68,12 +67,13 @@ const result = await engine.render(quill, parsed, { format: "pdf" });
 
 ## Initialization
 
-`await init()` once, at startup, before any other export is used. Everything
-after it is the synchronous surface the rest of this README describes.
+`init` resolves to the core surface: `Quill`, `Document`, and the free
+functions. Everything after the await is the synchronous surface the rest of
+this README describes.
 
 ```js
-import { init, Quill, Engine } from "@quillmark/wasm";
-await init();
+import { init, Engine } from "@quillmark/wasm";
+const { Quill, Document } = await init();
 ```
 
 The same line works everywhere: the binary streams from a URL in a browser and
@@ -83,10 +83,11 @@ the builds are `--target web`, so nothing in the package graph imports a `.wasm`
 module or carries a top-level await, and a static `import` of this package is
 safe anywhere, SSR included.
 
-`init` is idempotent and concurrency-safe: every call returns the same promise,
-so several entry points may each `await init()` for one instantiation. A failed
-init clears the memo, so a retry works. Each realm initializes its own copy; a
-Worker calls `init()` too.
+`init` is idempotent and concurrency-safe: every non-conflicting call returns
+the same promise, so several entry points may each `await init()` for one
+instantiation. Destructure at **every** entry point (route loader, hydration
+path, worker) rather than threading one result around. A failed init clears the
+memo, so a retry works. Each realm initializes its own copy, a Worker included.
 
 **Backends need nothing.** `Engine` instantiates a backend inside its lazy load,
 on the first render against it.
@@ -94,13 +95,17 @@ on the first render against it.
 **Overriding the source.** `init(source)` accepts bytes, a `Response`, a
 `WebAssembly.Module`, or 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.
+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.
 
-**If you forget.** Reaching the surface early throws a `QuillmarkError` coded
-`runtime::not_initialized` that names the fix, rather than a `TypeError` from
-inside generated code.
+**Both failures reject.** `runtime::init_conflict` and `runtime::init_failed`
+alike ride the returned promise, so one `catch` around `await init(...)` covers
+the gate. See [Errors](#errors) for the rule this follows.
+
+**You cannot forget.** The core surface has no static export, so a call site
+that skips the await has no name to call. The precondition is structural rather
+than a convention: no load order can make one entry point pass and another fail.
 
 **Vite's dev server** pre-bundles dependencies, which moves the package away
 from its binary. Exclude it:
@@ -547,6 +552,14 @@ try {
 }
 ```
 
+**Delivery follows the function, not the failure.** A synchronous method throws;
+a promise-returning one rejects. The promise-returning surface is `init` and the
+four `Engine` verbs (`render`, `open`, `supportedFormats`, `supportsCanvas`), so
+a programming error reached through one of them (a foreign handle, an
+unregistered backend) rejects like any other failure. Nothing here both returns
+a promise and throws, so a `.catch` on a promise-returning call is a whole
+guard.
+
 `QuillmarkError` is a **structural interface, not a class**: the WASM layer
 throws a real `Error` and attaches the property, so there is no constructor to
 `instanceof` against; narrow with `isQuillmarkError` (which also works on
@@ -591,11 +604,11 @@ call returns: `try { return engine.render(quill, doc); } finally
 { doc.free(); }`: is safe even on the first render, while the backend
 binary is still loading.
 
-The package floor is Node 22+ (`engines: { node: ">=22" }`) and current
+The package floor is Node 24+ (`engines: { node: ">=24" }`) and current
 evergreen browsers; `--weak-refs` itself only needs Node 14.6+. The `using`
-sugar ([explicit resource management][erm]) needs Node 24 and is optional.
-Where it hasn't landed, an explicit `try` / `finally` runs on the Node 22
-floor:
+sugar ([explicit resource management][erm]) is on that floor and optional;
+an explicit `try` / `finally` is the equivalent, and the form that also runs
+in a browser that hasn't shipped it:
 
 ```ts
 const session = await engine.open(quill, doc);

package/backends/pdfform/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/pdfform/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}
      */
@@ -2885,8 +2957,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 'pdfform' 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;
@@ -2933,7 +3004,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) {
@@ -2953,7 +3024,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/pdfform/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;