@quillmark/wasm 0.92.1 → 0.94.0

package/README.md

@@ -14,13 +14,13 @@ The package exposes **one import surface**:
   an `Engine` that renders them.
 
 `Quill` and `Document` are re-exported verbatim from the internal Typst-less
-core build, so engine-free editor/validation code (`Quill.fromTree`,
+core build, 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
-today) 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 hold a backend object
-or cross a memory boundary yourself.
+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
+hold a backend object or cross a memory boundary yourself.
 
 ## Build
 
@@ -28,9 +28,10 @@ or cross a memory boundary yourself.
 bash scripts/build-wasm.sh
 ```
 
-The script builds two feature variants — the core (no Typst) and the default
-(Typst backend) — both with `--target bundler` and `--weak-refs` enabled
-(see [Lifecycle](#lifecycle)).
+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 bundler` and `--weak-refs` enabled (see
+[Lifecycle](#lifecycle)).
 
 ## Test
 
@@ -46,7 +47,7 @@ npm test
 ```ts
 import { Document, Quill, Engine } from "@quillmark/wasm";
 
-const quill = Quill.fromTree(tree);   // engine-free: build + validate
+const quill = Quill.fromTree(tree);   // no engine needed: build + validate
 const engine = new Engine();          // loads a backend lazily on first render
 
 const markdown = `~~~
@@ -84,6 +85,14 @@ never cloning the quill. Use them as non-failing pre-render probes.
 Build + validate a `Quill` from an in-memory tree. Pure — the declared backend
 is resolved at render time, not here. Loads no backend binary.
 
+### `new Document(quillRef)`
+A blank document: a main card carrying only `$quill`, an empty body, and no
+composable cards — the programmatic blank canvas. Absent fields resolve at
+render time (schema `default`, else type-empty zero), so nothing the caller
+did not set reaches the output. Build it up with `setFields` / `pushCard`.
+For an example-filled starter use `quill.seedDocument()`. Throws on an
+invalid quill reference.
+
 ### `Document.fromMarkdown(markdown)`
 Parse markdown to a parsed document. Throws a JS `Error` (with `.diagnostics`
 attached, see [Errors](#errors)) on any parse failure, including a missing
@@ -145,9 +154,9 @@ genuinely malformed Markdown.
 
 ### Storage compatibility across versions
 
-The `schema` value (`quillmark/document@0.82.0`) is the **model version**,
+The `schema` value (`quillmark/document@0.93.0`) is the **model version**,
 not the running crate version. It is a hand-set constant, bumped only when
-the `Document` model itself changes — so every `0.82.x` patch release reads
+the `Document` model itself changes — so every `0.93.x` patch release reads
 and writes that same value.
 
 - **Upgrading is safe.** A newer build always reads documents written by an
@@ -188,15 +197,15 @@ and compare instead of re-parsing on every keystroke.
 ### `doc.cardCount`
 O(1) getter for the number of composable cards (excluding the main card).
 Use this to validate indices before calling card mutators (`removeCard`,
-`updateCardField`, etc.) without allocating the full `cards` array.
+`setCardField`, etc.) without allocating the full `cards` array.
 
 ### `quill.validate(doc)`
 
 Returns `Diagnostic[]` — the document validated against the quill schema,
 without invoking the backend. An empty array means the document is valid.
 Each diagnostic carries the canonical `validation::*` `code`, `path`, and
-`hint`. Includes the non-fatal `validation::field_absent` completeness
-signal that `render` demotes (an absent Unendorsed field zero-fills rather
+`hint`. Includes the non-fatal `validation::must_fill` warning for each
+`!must_fill` marker left in the document (render zero-fills these rather
 than failing), so filter by `severity`/`code` for blockers vs. hints:
 
 ```ts
@@ -204,9 +213,9 @@ const diagnostics = quill.validate(Document.fromMarkdown(markdown));
 const errors = diagnostics.filter(d => d.severity === "error");
 ```
 
-To render a form editor, read field definitions from `quill.schema` (sort
-fields by each field's `ui.order`) and the authored values from the
-`Document` payload — there is no separate form-view projection.
+To render a form editor, read field definitions from `quill.schema` (walk
+`fields` in key order — declaration order is display order) and the authored
+values from the `Document` payload — there is no separate form-view projection.
 
 ### `quill.seedDocument()`
 
@@ -223,51 +232,112 @@ const markdown = doc.toMarkdown();
 
 For per-card seeding, `quill.seedMain()` returns just the `$kind: main` card
 and `quill.seedCard(kind)` returns a starter composable card (or `undefined`
-if the kind is not declared). Both return the same `Card` shape as
+if the kind is not declared). Both return the read `Card` shape of
 `doc.main` / `doc.cards`, which `doc.pushCard` / `doc.insertCard` accept
 directly:
 
 ```ts
 doc.pushCard(quill.seedCard("note"));                 // seed → push
 doc.pushCard(Document.makeCard("note", { x: 1 }));    // build from a flat map
+doc.pushCard({ kind: "note", body: "Plain **markdown**." });  // bare inline
 ```
 
-There is one `Card` shape in both directions — `pushCard` / `insertCard` take
-exactly what `cards` / `removeCard` / `seedCard` return. Build a fresh card
-from a flat field map with `Document.makeCard(kind, fields?, body?)`.
+Reads and writes are two aligned shapes. A read `Card` always has `body:
+RichText` (canonical corpus, never a raw string) — no narrowing, no guessing
+whether the body was normalized. The write shape `CardInput` widens `body` to
+`RichText | string` (a markdown string imports to the corpus) and makes every
+field but `kind` optional. Every `Card` is a valid `CardInput`, so `pushCard` /
+`insertCard` still take exactly what `cards` / `removeCard` / `seedCard` return.
+Build a fresh card from a flat field map with
+`Document.makeCard(kind, fields?, body?)`.
+
+Batch mutation: `doc.setFields({...})` / `doc.setCardFields(index, {...})`
+apply a whole object atomically — on any invalid field nothing is applied and
+the thrown error carries one diagnostic per offending field (`path` = field
+name).
+
+### Typed writes: `commit*` is the default, `set*` is the quill-free primitive
+
+A `Document` holds only a `$quill` *reference*, not the resolved schema, so it
+mutates through two layers:
+
+- **`commit*` — the schema-bound default whenever a quill is in hand.**
+  `doc.commitField(quill, name, value)` / `doc.commitFields(quill, {...})` (and
+  the `commitCard*` twins) resolve each field's schema `type`, coerce the value
+  to its canonical form (`"3"` → `3`, a markdown string → a richtext corpus),
+  and **fail now** on a mismatch instead of at render. 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, not a fallback. The batch form is
+  all-or-nothing: an undeclared name aborts the whole write and its per-field
+  diagnostics name every offending field, so a whole-form submit surfaces every
+  typo `setFields` would silently absorb.
+
+- **`set*` — the deliberate quill-free primitive.** `doc.setField(name, value)`
+  / `doc.setFields({...})` (and the `setCard*` twins) validate only the field
+  name/depth/kind and store the value verbatim, no quill required. Reach for it
+  on purpose when you *want* the opaque store: quill-agnostic storage/migration
+  infra that has no bundle and must write regardless of a drifted schema;
+  store-now-validate-later editors holding in-progress input that `commit`
+  would reject; or verbatim passthrough of fields the schema doesn't own. It is
+  the lower layer, not a lighter `commit` — a typo'd field name stores silently
+  and only surfaces at `quill.validate` / render.
+
+Per-keystroke cost is the same either way (both mutate the in-memory `Document`
+in place; no seam is crossed), so steering to `commit*` buys the type check for
+free.
+
+#### `DocumentWriter` / `CardWriter` — bind the quill once
+
+The `commit*` verbs take the `quill` handle per call (the document carries no
+schema). When you hold both a quill and a document — a form editor, an MCP
+writer — bind them once with the writer sugar and issue bare verbs:
 
-### `engine.render(quill, parsed, opts?)` vs. `engine.open(quill, parsed)`
+```ts
+import { DocumentWriter } from "@quillmark/wasm";
+
+const ed = new DocumentWriter(quill, doc);          // JS twin of Rust `quill.writer(doc)`
+ed.set("subject", "Q3 results");                    // strict-committed to the schema type
+ed.setAll({ qty: "3", subject: "Q3" });             // all-or-nothing batch
+ed.set("titel", "x");                               // throws UnknownField — a typo, not a fallback
+ed.card(2).set("body", "**note**");                 // composable card, resolved by its $kind
+```
+
+`DocumentWriter` / `CardWriter` are pure JS holding references to your existing
+`quill` and `doc` — no WASM handle of their own, nothing to `free()`. `card(i)`
+is lazy: it never throws; an out-of-range index throws `IndexOutOfRange` at the
+write.
 
-> **Experimental:** the entire session surface — `engine.open`,
-> `RenderSession`, `paint`, `PaintOptions`, `PaintResult`, `PageSize`, and the
-> `supportsCanvas` probe — ships ahead of its first production consumer and
-> may change shape in any 0.x release. `engine.render` is the stable path.
+### `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 **`RenderSession`** (returned by `engine.open`) for
-reactive previews where
-you'll paint or re-emit pages multiple times: the session retains the compiled
-snapshot so subsequent `paint` / `render` calls skip recompilation. Don't open
-a session per export.
+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)`
+recompiles in place on each edit, returning a `ChangeSet` whose `dirtyPages`
+tells you which pages to repaint (`dirty ∩ visible`). Apply 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.
 
 ### `engine.render(quill, parsed, opts?)`
-Render a pre-parsed `Document` against `quill`. Throws `UnsupportedBackend` if
-no registered backend matches the quill's declared backend.
+Render a pre-parsed `Document` against `quill`. Throws an
+`engine::backend_not_found` error if no registered backend matches the quill's
+declared backend.
 
 ### `engine.open(quill, parsed)` + `session.render(opts?)`
 Open once, render all or selected pages (`opts.pages`).
 
 The session also exposes `pageCount`, `backendId`, `supportsCanvas`,
-`warnings` (snapshot of session-level diagnostics attached at `open` time),
-`pageSize(page)`, and `paint(ctx, page, opts?)` for canvas previews. See
-below.
+`warnings` (non-fatal diagnostics of the current compile — set at `open`,
+refreshed by each committed `apply`),
+`apply(doc)` for in-place recompiles, `pageSize(page)`, and
+`paint(ctx, page, opts?)` for canvas previews. See below.
 
 A document that compiles to zero pages still produces a valid session
 (`pageCount === 0`); `paint(ctx, 0)` and `pageSize(0)` then throw
 `page index 0 out of range (pageCount=0)`. Branch on `pageCount === 0` to
 render a "no pages to preview" UI without relying on the throw.
 
-### Canvas Preview (Typst only)
+### Canvas Preview
 
 `session.paint(ctx, page, opts?)` rasterizes a page directly into a
 `CanvasRenderingContext2D` (main thread) or
@@ -281,7 +351,7 @@ sets them) and read `layoutWidth` / `layoutHeight` from the returned
 
 ```ts
 const result = session.paint(canvas.getContext("2d"), 0, {
-  layoutScale: 1,                            // layout px per Typst pt
+  layoutScale: 1,                            // layout px per pt (page geometry unit)
   densityScale: window.devicePixelRatio,     // backing-store density
 });
 
@@ -291,17 +361,26 @@ canvas.style.height = `${result.layoutHeight}px`;
 
 - `layoutScale` (default 1) sets the canvas's display-box size:
   `layoutWidth = widthPt * layoutScale`. For on-screen canvases this is
-  CSS pixels per Typst point. Defaults to 1 (one CSS pixel per pt).
+  CSS pixels per point. Defaults to 1 (one CSS pixel per pt).
 - `densityScale` (default 1) is the backing-store density multiplier.
   Fold `window.devicePixelRatio`, in-app zoom, and `visualViewport.scale`
   (pinch-zoom) into a single value here. Pass `devicePixelRatio` for
   crisp output on high-DPI displays.
 - The effective rasterization scale is `layoutScale * densityScale`. If
   that would exceed the safe maximum (16384 px per side), `densityScale`
-  is clamped proportionally; compare `result.pixelWidth` against
-  `Math.round(result.layoutWidth * densityScale)` to detect.
+  is clamped proportionally; `result.clamped` reports it and
+  `result.effectiveDensityScale` is the density actually applied. A
+  clamped page renders soft at the same `canvas.style` size.
+- `paint` writes the whole backing store with `putImageData`, which
+  ignores the 2D context transform, `globalAlpha`, and clip. Give each
+  visible page its own `` element — you cannot composite two pages,
+  a sub-rect, or a context transform through `paint`.
 - `paint` is always a full repaint — setting the backing-store width /
-  height clears it. No `clearRect` required.
+  height clears it. No `clearRect` required. Each call re-rasterizes from
+  scratch (no per-page raster cache), so keep a page's canvas alive while
+  it stays near the viewport rather than pooling one canvas across pages:
+  an idle canvas retains its pixels for free, whereas reusing a canvas on
+  scroll re-runs a full render.
 - `pageCount` and `pageSize(page)` are stable for the session's
   lifetime (immutable snapshot) — cache them.
 - Worker support: pass an `OffscreenCanvasRenderingContext2D` and the
@@ -319,19 +398,19 @@ canvas.style.height = `${result.layoutHeight}px`;
 
 A field's *cell* is inferred from whether its schema declares a `default:`:
 
-- **Unendorsed** (no `default:`) — `quill.blueprint` renders `<must-fill>`
-  in the value cell. An absent Unendorsed field is a non-fatal signal
-  (`validation::field_absent`) — the render path zero-fills it
-  silently. A surviving `<must-fill>` sentinel is fatal
-  (`validation::must_fill_sentinel`). Partial documents are
-  first-class; `engine.render(quill, doc)` only throws for malformed input.
+- **Unendorsed** (no `default:`) — `quill.blueprint` renders the
+  `!must_fill` marker in the value cell (carrying the field's `example` as a
+  suggested value when one exists). An absent Unendorsed field zero-fills
+  silently. A `!must_fill` marker left in the document is non-fatal: it emits
+  the `validation::must_fill` warning and still renders. Partial documents
+  are accepted; `engine.render(quill, doc)` only throws for malformed
+  input.
 - **Endorsed** (with `default:`) — `quill.blueprint` renders the
-  default value followed by a `; delete-ok` annotation, and the default
-  is used when the document omits the field.
+  default value with a type-only `# <type>` annotation (shippable as-is),
+  and the default is used when the document omits the field.
 
-`QuillFieldSchema` has no `required` axis. Absent Unendorsed fields emit
-`validation::field_absent`; a surviving `<must-fill>` sentinel emits
-`validation::must_fill_sentinel`.
+`QuillFieldSchema` has no `required` axis. A `!must_fill` marker left in the
+document emits the non-fatal `validation::must_fill` warning.
 
 ### Errors
 
@@ -367,20 +446,26 @@ compilation failures. The same shape applies to every throw site:
 
 - `Document.fromMarkdown` — parse errors (missing root `$quill` metadata, YAML
   errors, `parse::input_too_large` for inputs > 10 MB).
-- `Document` mutators (`setField`, `updateCardField`, etc.) — `EditError`
+- `Document` mutators (`setField`, `setCardField`, etc.) — `EditError`
   variants (`InvalidFieldName`, `InvalidKindName`, `ReservedKind`,
-  `IndexOutOfRange`) appear in `diagnostics[0].message` with the
-  `[EditError::<Variant>]` prefix.
+  `IndexOutOfRange`, `ValueTooDeep`) appear in `diagnostics[0].message` with
+  the `[EditError::<Variant>]` prefix.
 - `engine.render` / `session.render` — backend compilation failures and
   validation errors.
 
 ### Lifecycle
 
 The wasm bindings are built with `--weak-refs`, so dropped `Document`,
-`Quill`, and `RenderSession` handles are reclaimed by `FinalizationRegistry`
+`Quill`, and `LiveSession` handles are reclaimed by `FinalizationRegistry`
 without manual `.free()` discipline. `.free()` is still emitted as an eager
 teardown hook for callers that want deterministic release.
 
+`engine.render` and `engine.open` read the `quill` and `doc` handles
+synchronously, before their first await, so freeing a handle as soon as the
+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
 evergreen browsers; `--weak-refs` itself only needs Node 14.6+. The `using`
 sugar shown below ([explicit resource management][erm]) needs Node 24, but is
@@ -390,7 +475,7 @@ For environments where `using` (the [explicit resource management][erm]
 proposal) hasn't landed, use an explicit `try` / `finally`:
 
 ```ts
-const session = engine.open(quill, doc);
+const session = await engine.open(quill, doc);
 try {
   for (let p = 0; p < session.pageCount; p++) {
     session.paint(ctx, p);
@@ -405,7 +490,7 @@ try {
 ## Notes
 
 - Parsed markdown requires a root `~~~` block (a bare three-tilde fence;
-  the legacy `~~~card-yaml` opener is still accepted but non-canonical)
+  `~~~card-yaml` is also accepted as a non-canonical alias)
   with a `$quill` system-metadata line. Empty input surfaces a dedicated
   "Empty markdown input cannot be parsed" message.
 - A `$quill` mismatch during `engine.render(quill, parsed)` is a thrown error, not a warning: rendering with a quill whose *name* differs (`quill::name_mismatch`) or whose *version* falls outside the selector (`quill::version_mismatch`) is rejected.
@@ -413,8 +498,8 @@ try {
 
 ## Changelog
 
-See the [changelog](https://github.com/quillmark-org/quillmark/blob/main/CHANGELOG.md)
-and the [GitHub Releases](https://github.com/quillmark-org/quillmark/releases) page for
+See the [changelog](https://github.com/borb-sh/quillmark/blob/main/CHANGELOG.md)
+and the [GitHub Releases](https://github.com/borb-sh/quillmark/releases) page for
 release notes and version history.
 
 ## License