@quillmark/wasm 0.112.0 → 0.114.0

package/README.md

@@ -15,10 +15,10 @@ The package has one import surface: `@quillmark/wasm`, whose `init` resolves to
 `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
-memory, lazily loaded on the first render. The Engine clones a `Quill` /
-`Document` into the backend's memory as data and frees the clones: you never
+loaded until you render. The `Engine` hides everything else: the render build,
+carrying both backends (`typst`, `acroform`), is a private WASM binary with its
+own linear memory, lazily loaded on the first render. The Engine clones a
+`Quill` / `Document` into that memory as data and frees the clones: you never
 hold a backend object or cross a memory boundary yourself.
 
 ## Build
@@ -27,9 +27,9 @@ hold a backend object or cross a memory boundary yourself.
 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
+The script builds two variants, the core (no backend) and the render build
+(default features, both backends), each with `--target web` and `--weak-refs`
+enabled (see
 [Initialization](#initialization) and [Lifecycle](#lifecycle)). It then asserts
 none of them carries a `.wasm` ESM import or a top-level await.
 
@@ -119,18 +119,17 @@ A load failure surfaces as `runtime::init_failed`, whose hint names that line.
 Create the render dispatcher. Routes each quill to its backend by
 `quill.backendId`, lazily loads that backend binary, and renders: cloning the
 quill/document into the backend's memory and freeing the clones internally.
-`render`, `open`, `supportedFormats`, and `supportsCanvas` are **async** (the
-first call may load a backend). Pass `{ backends }` to register or override
-backend descriptors. Each entry is a descriptor
-(`{ [backendId]: { load, formats, canvas } }`) where `load` is the lazy thunk
-returning the backend module and `formats`/`canvas` are the **required** static
-capability manifest. A malformed descriptor throws at `new Engine(...)`, naming
-the backend id.
-
-**Capability probes are always free.** `supportedFormats` and `supportsCanvas`
-depend only on `quill.backendId`, and answer from the descriptor's required
-`formats`/`canvas` manifest: never loading the multi-MB backend binary and
-never cloning the quill. Use them as non-failing pre-render probes.
+`render`, `open`, and `supportedFormats` are **async** (the first call may load
+a backend). Pass `{ backends }` to register or override backend descriptors.
+Each entry is a descriptor (`{ [backendId]: { load, formats } }`) where `load`
+is the lazy thunk returning the backend module and `formats` is the
+**required** static capability manifest. A malformed descriptor throws at
+`new Engine(...)`, naming the backend id.
+
+**The format probe is always free.** `supportedFormats` depends only on
+`quill.backendId`, and answers from the descriptor's required `formats`
+manifest: never loading the multi-MB backend binary and never cloning the
+quill. Use it as a non-failing pre-render probe.
 
 ### The two doors: `Document.fromMarkdown` vs `quill.parse` / `quill.conform`
 
@@ -148,7 +147,7 @@ document was built. Parse warnings and the `conform::*` warnings both ride
 `doc.warnings`.
 
 `quill.conform(doc)` is the same walk in place on a document that arrived any
-other way (`fromJson`, a stored row), returning the `conform::*` `Diagnostic[]`
+other way (`fromStored`, a stored row), returning the `conform::*` `Diagnostic[]`
 (`[]` when everything rested). It is idempotent and a byte no-op on an
 already-canonical document, YAML comments included, so calling it on every load
 is safe. A `!must_fill` marker anywhere in a field's value skips that field; a
@@ -158,19 +157,22 @@ mutation.
 
 ```ts
 const doc = quill.parse(markdown);          // rests canonical
-const stale = Document.fromJson(row);
+const stale = Document.fromStored(row);
 const diags = quill.conform(stale);         // converges in place
 ```
 
 ### Storage compatibility across versions
 
-Persist `doc.toJson()`, not `doc.toMarkdown()`: the DTO wire format is frozen
+Persist `doc.toStored()`, not `doc.toMarkdown()`: the DTO wire format is frozen
 per `schema` version, whereas Markdown syntax evolves, and `toMarkdown` output
-is normalised rather than byte-equal to the source. `Document.tryFromJson`
-discriminates the two formats without exceptions as control flow:
+is normalised rather than byte-equal to the source. `Document.storageVersionOf`
+discriminates the two formats without exceptions as control flow: it answers
+`undefined` for anything that is not a storage DTO.
 
 ```ts
-const doc = Document.tryFromJson(content) ?? Document.fromMarkdown(content);
+const doc = Document.storageVersionOf(content)
+  ? Document.fromStored(content)
+  : Document.fromMarkdown(content);
 ```
 
 The `schema` value (`quillmark/document@0.112.0`) is the **model version**,
@@ -178,13 +180,16 @@ not the running crate version. It is a hand-set constant, bumped only when
 the `Document` model itself changes, so every `0.112.x` patch release reads
 and writes that same value.
 
-- **Upgrading is safe.** A newer build always reads documents written by an
-  older one. Each schema version's wire format is frozen and never changes;
-  when the model does change, the new build ships a migration that converts
-  old payloads on `fromJson`. A document you commit as your canonical
-  on-disk format keeps loading across crate upgrades: there is no need to
-  pin old wasm to read old data.
-- **Downgrading is not.** `fromJson` rejects an *unknown* (i.e. newer)
+- **Upgrading is safe.** A newer build reads documents an older build's
+  *writer* produced. Each schema version's wire format is frozen and never
+  changes; when the model does change, the new build ships a migration that
+  converts old payloads on `fromStored`. A document you commit as your
+  canonical on-disk format keeps loading across crate upgrades: there is no
+  need to pin old wasm to read old data. The exception is a row a host
+  authored a content construct of its own into — a line `kind`, container,
+  mark `type`, island `type` or `loss` outside the vocabulary. Those are
+  refused from 0.113 on; see that release's migration guide.
+- **Downgrading is not.** `fromStored` rejects an *unknown* (i.e. newer)
   `schema` version rather than guessing at a format it predates. Don't feed
   documents written by a newer build back into an older one.
 
@@ -200,9 +205,9 @@ if (v && v !== Document.currentStorageVersion()) {
 `storageVersionOf` does not validate the payload: it only reads the
 `schema` field, returning `undefined` for non-JSON, non-objects, or
 payloads that don't carry one. Use it to distinguish "wrong version" from
-"corrupt" when `fromJson` throws.
+"corrupt" when `fromStored` throws.
 
-In short: persist the `toJson` string, upgrade freely, never downgrade. The
+In short: persist the `toStored` string, upgrade freely, never downgrade. The
 full design (including how migrations are added) is in
 `prose/canon/DOCUMENT_STORAGE.md`.
 
@@ -220,9 +225,12 @@ accepts directly:
 
 ```ts
 doc.insertCard(quill.seedCard("note"));                 // seed → append
-doc.insertCard(Document.makeCard("note", { x: 1 }));    // build from a flat map
 doc.insertCard({ kind: "note", body: "Plain **markdown**." });  // bare inline
 doc.insertCard({ kind: "note" }, 0);                    // insert at index 0
+doc.insertCard({                                        // fields → payload items
+  kind: "note",
+  payloadItems: [{ type: "field", key: "x", value: 1 }],
+});
 ```
 
 Reads and writes are two aligned shapes. A read `Card` always has `body:
@@ -230,9 +238,9 @@ Content` (canonical content, never a raw string): no narrowing, no guessing
 whether the body was normalized. The write shape `CardInput` widens `body` to
 `Content | string` (a markdown string imports to the content) and makes every
 field but `kind` optional. Every `Card` is a valid `CardInput`, so `insertCard`
-still takes exactly what `cards` / `removeCard` / `seedCard` return.
-Build a fresh card from a flat field map with
-`Document.makeCard(kind, fields?, body?)`.
+still takes exactly what `cards` / `removeCard` / `seedCard` return. A fresh
+card is an object literal: one `{ type: "field", key, value }` per field in
+`payloadItems`, in the order they should appear.
 
 **One address for the whole surface.** Reads and writes navigate by an `Addr`:
 `{ card?, field? }`, absent `card` = main, absent `field` = body, and a bare
@@ -243,10 +251,11 @@ an absent field; only an out-of-range card throws); field writes throw on a body
 address. `getStored` is the verbatim transport read, distinct from the interpreted
 `quill.reader(doc).get`; `bodyMarkdown` is the body markdown read (a `CardAddr`; a field's
 markdown is read through `quill.reader(doc).get(field)`). A content field's stored
-form follows how the document was built (a canonical content object when the
-typed writer committed it, the authored string when a markdown parse produced
-it), so for the `Content` either way read `quill.reader(doc).getContent(addr)`, which
-decodes through the codec the field's declared type names. Card-scoped verbs take a
+form rests per its declared codec through the bound door (a `richtext` field as
+the content object, a `plaintext` field as its literal string), and as authored
+through the transport door. For the `Content` either way read
+`quill.reader(doc).getContent(addr)`, which decodes through the codec the
+field's declared type names. Card-scoped verbs take a
 `CardAddr` (`{ card? }`) first: `doc.getExt({ card: 2 })`, and the batch below.
 
 Batch mutation: `doc.storeFields({}, {...})` / `doc.storeFields({ card: index }, {...})`
@@ -255,7 +264,7 @@ the thrown error carries one diagnostic per offending field (`path` = field
 name). The address is first (never shape-overloaded, since `card` is a legal
 field name), and parses strictly: a stray key throws rather than silently
 reading as `{}`. The main card is `{}`, or **`MAIN_CARD_ADDR`** (from
-`@quillmark/wasm/runtime`), a frozen alias that spells the intent:
+`@quillmark/wasm`), a frozen alias that spells the intent:
 `doc.storeFields(MAIN_CARD_ADDR, {...})`.
 
 ### Typed writes: `commit*` is the default, `store*` is the quill-free primitive
@@ -317,34 +326,43 @@ write.
 
 ```ts
 const v = quill.reader(doc);
-v.get("subject");                                   // by declared type: richtext → markdown, plaintext → literal text
+v.get("subject");                                   // the values form: every content leaf as its codec's text, else as stored
 v.getContent("subject");                            // the same read as a `Content`, whichever lane stored it
 v.bodyMarkdown();                                   // the main body markdown (quill-free)
 v.card(0).get("body");                              // a card field, resolved by its $kind
+v.resolve();                                        // the render view: blank-filled, coerced, each field tagged with its rung
 ```
 
 `get` projects and `getContent` returns the `Content`; both decode through the codec
 the field's **declared type** names, which is why they bind the quill and the
 verbatim `doc.getStored` does not. An undeclared name throws `UnknownField`, a
 type that is not a content leaf throws `FieldNotContent`, and an undecodable
-value throws `FieldDecode`; an absent field reads back `undefined`.
+value throws `FieldDecode`; an absent field reads back `undefined` and a
+present-null `null`. A read never coerces a scalar (`qty: "3"` reads `"3"`);
+`resolve()` is the coerced view.
 
 ### `engine.render(quill, parsed, opts?)` vs. `engine.open(quill, parsed)`
 
 Use **`engine.render`** for one-shot exports (PDF/SVG/PNG): compiles, emits
 artifacts, done. Use **`LiveSession`** (returned by `engine.open`) for
 reactive previews: the session is a persistent compiler. `paint` / `render` /
-`regions` / `fieldAt` read its current compile without recompiling, and `apply(doc)`
+`regions` / `fieldAt` read its current compile without recompiling, and `update(doc)`
 recompiles in place on each edit, returning a `ChangeSet` whose `dirtyPages`
-tells you which pages to repaint (`dirty ∩ visible`). Apply is transactional:
+tells you which pages to repaint (`dirty ∩ visible`). `update` is transactional:
 on throw, every read keeps serving the last-good compile. Don't open a session
-per export, and don't re-open per edit: `apply` instead.
+per export, and don't re-open per edit: `update` instead.
 
 A document that compiles to zero pages still produces a valid session
 (`pageCount === 0`); `paint(ctx, 0)` and `pageSize(0)` then throw. Branch on
 `pageCount === 0` to render a "no pages to preview" UI rather than relying on
 the throw.
 
+Their `warnings` differ in reach. `engine.render` returns one list for the
+whole pipeline: `doc.warnings` (parse, `conform::*`,
+`plate::unsupported_construct`) ahead of the compile's own. A session outlives
+the document it opened from, so `session.render` and `session.warnings` carry
+the compile half alone — read `doc.warnings` beside them.
+
 ### Canvas Preview
 
 `session.paint(ctx, page, opts?)` rasterizes a page directly into a
@@ -378,14 +396,16 @@ canvas.style.height = `${result.layoutHeight}px`;
   a page's canvas alive while it stays near the viewport: an idle canvas retains
   its pixels for free, whereas pooling one canvas across pages re-renders on
   every scroll.
-- `pageCount` and `pageSize(page)` are stable for the session's lifetime: cache
-  them.
+- `pageCount` and `pageSize(page)` read the current compile, not the session:
+  cache them between committed `update`s only. After one, the count is
+  `ChangeSet.pageCount`, and every page in `ChangeSet.dirtyPages` needs its
+  `pageSize` re-read.
 - In a Worker, pass an `OffscreenCanvasRenderingContext2D`; the layout
   dimensions are informational there. Loading the WASM module inside the Worker
   is the host's responsibility.
-- Backend support is gated by `supportsCanvas`. Probe upfront with
-  `engine.supportsCanvas(quill)`; the throw on `paint` / `pageSize` remains the
-  enforcement contract and names the resolved `backendId`.
+- `paint` / `pageSize` throw on a page the compile does not have, a zero-page
+  compile included, naming the index and the `pageCount` that excludes it. That
+  throw is the whole contract: open the session and handle it.
 
 ### Schema model
 
@@ -430,9 +450,9 @@ 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
+three `Engine` verbs (`render`, `open`, `supportedFormats`), 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.
 
@@ -447,21 +467,26 @@ applies to every throw site:
 
 - `Document.fromMarkdown`: parse errors (missing root `$quill` metadata, YAML
   errors, `parse::input_too_large` for inputs > 10 MiB).
-- `Document` mutators (`storeField`, the writer's `set`, etc.): mutator
-  failures carry a namespaced `edit::*` `code` on `diagnostics[0]`
-  (`edit::invalid_field_name`, `edit::unknown_field`, `edit::index_out_of_range`,
-  `edit::field_coercion_failed`, …). Route on `diagnostics[0].code`, never on message
-  text.
+- `Document` mutators (`storeField`, `insertCard`, the writer's
+  `set`, etc.): mutator failures carry a namespaced `edit::*` `code` on
+  `diagnostics[0]` (`edit::invalid_field_name`, `edit::unknown_field`,
+  `edit::index_out_of_range`, `edit::field_coercion_failed`, …). Route on
+  `diagnostics[0].code`, never on message text.
 - `engine.render` / `session.render`: backend compilation failures and
   validation errors.
 - `engine.render(quill, parsed)` against a quill whose *name* differs
   (`quill::name_mismatch`) or whose *version* falls outside the document's
   selector (`quill::version_mismatch`): a throw, never a warning.
-- Any method taking a `Quill` or `Document`: a handle from a *second* copy of
-  `@quillmark/wasm` is refused with `runtime::foreign_handle`, hinting `npm ls
-  @quillmark/wasm`. Two copies are two WASM memories and two `Quill`/`Document`
-  classes; dedupe to one. A value that is not a handle at all keeps its own
-  `runtime::not_a_document` / `runtime::not_a_quill`.
+- The four `Engine` verbs against a quill whose declared `backend:` is not in
+  the registry: `engine::backend_not_found`, the code core raises for the same
+  condition, hinting the registered ids.
+- The `Engine` verbs, `session.update`, and the writer/reader binds against a
+  value that is not one of *this* copy's handles — the wrong type, or the right
+  class from a second copy of `@quillmark/wasm`: `runtime::not_a_quill` /
+  `runtime::not_a_document`, hinting `npm ls @quillmark/wasm` for the second
+  case. Two copies are two WASM memories and two `Quill`/`Document` classes;
+  dedupe to one. Elsewhere a foreign handle meets wasm-bindgen's own
+  `expected instance of …`, which is not a `QuillmarkError`.
 
 ### Lifecycle