@quillmark/wasm 0.88.0 → 0.90.0

package/CHANGELOG.md

@@ -1,5 +1,132 @@
 # Changelog
 
+## v0.90.0 - 2026-06-10
+
+
+
+## v0.89.1 - 2026-06-10
+
+- chore(release): v0.89.1-rc.1 (#714)
+- feat(wasm)!: 0.90 canonical API — engine-free Quill, single root export, typed errors; Python parity (#713)
+- Proposal: WASM bindings split (core + render) via backend-decoupled Quill (#710)
+- Add version selector matching and mismatch warnings (#708)
+- docs: density-optimization pass on user-facing docs (#703)
+- Remove role annotation from root block metadata header (#707)
+- canon: audit and correct all prose/canon/ docs (#704)
+- Fix makeCard fields/body typed as required in WASM .d.ts (#702)
+- Update CLAUDE.md
+
+
+## v0.89.1-rc.1 - 2026-06-10
+
+- feat(wasm)!: 0.90 canonical API — engine-free Quill, single root export, typed errors; Python parity (#713)
+- Proposal: WASM bindings split (core + render) via backend-decoupled Quill (#710)
+- Add version selector matching and mismatch warnings (#708)
+- docs: density-optimization pass on user-facing docs (#703)
+- Remove role annotation from root block metadata header (#707)
+- canon: audit and correct all prose/canon/ docs (#704)
+- Fix makeCard fields/body typed as required in WASM .d.ts (#702)
+- Update CLAUDE.md
+
+
+## Unreleased
+
+- **Breaking (Rust API + bindings):** `Quill` is now engine-free, validated
+  data. It no longer holds a backend; the `Quillmark` engine becomes a backend
+  registry + render dispatcher. Rendering and capability move onto the engine:
+  `render` / `open` / `supported_formats` / `supports_canvas` take `&quill`
+  (JS: `engine.render(quill, doc)` etc.). The `engine.quill` / `quill_from_path`
+  factory is removed — construct with `Quill::from_tree` (JS `Quill.fromTree`)
+  or `quillmark::quill_from_path`. The backend-existence
+  check moves from load time to render time (`UnsupportedBackend` now surfaces
+  from the first engine call). `supportedFormats` leaves `Quill.metadata` (now
+  pure config) for `engine.supportedFormats(quill)`. `Backend` gains a
+  `supports_canvas()` capability method (default `false`; Typst `true`),
+  retiring the `backend_id == "typst"` magic string. See
+  [migration guide](docs/migrations/0.89-to-0.90.md).
+- **Breaking (WASM/JS types):** `QuillMetadata` drops its `[key: string]: unknown`
+  index signature. Code reading removed or unknown metadata properties (e.g.
+  `quill.metadata.supportedFormats`) now fails at compile time with "Property
+  does not exist" instead of silently returning `undefined` at runtime. Cast to
+  `Record<string, unknown>` to reach extra `quill:` YAML keys if needed.
+- **Breaking (Python API):** the Python binding adopts the engine-free shape.
+  Render and capability move onto the `Quillmark` engine, taking a quill:
+  `engine.render(quill, doc)` / `engine.open(quill, doc)` /
+  `engine.supported_formats(quill)` / `engine.supports_canvas(quill)` (were
+  `quill.render(doc)` etc.). `Quill.from_path(path)` replaces
+  `Quillmark.quill_from_path(path)` — the engine is no longer a loader, and the
+  loaded `Quill` is engine-free. `quill.metadata` no longer contains
+  `supportedFormats` (read `engine.supported_formats(quill)`) and is now a pure,
+  infallible config read. Backend resolution moves from load to render time:
+  `UnsupportedBackend` surfaces from the first engine call, not from `from_path`.
+  See the [migration guide](docs/migrations/0.89-to-0.90.md#python).
+- **Breaking (Rust API):** `QuillSource` and the orchestration `Quill` collapse
+  into one core type, `quillmark_core::Quill` (held by value; the vestigial
+  `Arc` is dropped). `Backend::open` now takes `&Quill`; the consumer methods
+  and the `seed` module move into core; `quill.source()` is gone
+  (`quill.config()` is direct). Bindings already hid `QuillSource`, so JS/Python
+  consumers are unaffected by the rename.
+- **WASM packaging (single root export):** the root `@quillmark/wasm` import is
+  now a hand-written **canonical layer** (`pkg/runtime/`) — it re-exports the
+  Typst-less core's `Quill` / `Document` **verbatim** (same classes, no wrappers)
+  and adds an async **`Engine`** (`render` / `open` / `supportedFormats` /
+  `supportsCanvas`) as the canonical render API. The package `exports` map has
+  exactly **one** public entry point, `.` (the canonical layer); the old
+  `./render` and `./core` subpath exports are both **removed**. Engine-free
+  editor/validation code (`Quill.fromTree`, `Document.fromMarkdown`) still loads
+  only the small internal core binary (~0.66 MB gzip) — no backend is loaded
+  until you render. The Typst backend binary is **private**
+  (`pkg/backends/typst/`, not in the `exports` map): the `Engine`
+  lazy-`import()`s it on first render, clones the quill/document into its memory as
+  data (`Quill.toTree` → `fromTree`, `doc.toJson` → `fromJson`), and manages
+  those clones internally (the validated quill clone is cached per instance;
+  per-render document clones are freed) — consumers never import the backend or
+  cross a WASM memory boundary themselves. `Quill.toTree()` is added to core for that crossing. A release-time
+  size budget still guards the core artifact against Typst regressions.
+- **WASM `Engine` (descriptor-only backend registry):** `new Engine({ backends })`
+  takes backend entries in **descriptor form only** — `{ load, formats, canvas }`
+  with `formats` and `canvas` **required**. The constructor validates each entry
+  and throws (naming the backend id) at construction. The capability probes
+  `supportedFormats` / `supportsCanvas` answer from this required manifest
+  **unconditionally**, never loading a backend binary or cloning the quill. The
+  bare-thunk loader form and its load+clone fallback path are removed.
+- **WASM `Engine` (no invalidation API):** the unreleased
+  `Engine.invalidate(quill)` / `invalidateAll()` methods are removed before
+  release. The backend-clone cache is keyed on the canonical `Quill` instance in
+  a `WeakMap`; a quill's contents never change after construction, so the only
+  invalidation semantic is to drop/replace the instance (the clone is freed with
+  it via the `WeakMap` + wasm-bindgen weak-refs). An explicit invalidation API
+  will ship with its first real consumer. The load-bearing invariant — a
+  canonical ref is immutable content within a runtime's lifespan — is now
+  recorded in `prose/canon/VERSIONING.md` (Ref Immutability).
+- **WASM `Engine` (session/canvas surface marked experimental):** `Engine.open`,
+  `RenderSession`, `paint`, `PaintOptions`, `PaintResult`, `PageSize`, and the
+  `supportsCanvas` probe are tagged `@experimental` in the shipped types and
+  README: they ship ahead of their first production consumer (the designed
+  canvas live-preview path) and may change shape in any 0.x release.
+  `Engine.render` and `supportedFormats` are the stable surface.
+- **WASM (typed error contract):** the root exports `QuillmarkError` — a
+  structural interface (`Error & { diagnostics: Diagnostic[] }`) naming the
+  shape every fallible method already throws — and an `isQuillmarkError(e)`
+  guard to narrow caught `unknown`s. No runtime behavior change: the WASM
+  layer still throws a plain `Error` with `diagnostics` attached (there is
+  deliberately no error class — a structural check works across builds and
+  WASM instances). Consumers can delete their hand-rolled
+  `.diagnostics`-extraction casts.
+- **Breaking (Rust API + bindings):** a document's `$quill` reference is now
+  **enforced** against the loaded quill. Rendering with a quill whose *name*
+  differs (`quill::name_mismatch`) or whose *version* falls outside the selector
+  (`quill::version_mismatch`) is a hard error via the new
+  `RenderError::QuillMismatch`, in both `render` and `dry_run`. Previously a name
+  mismatch was only the `quill::ref_mismatch` warning and the version selector
+  was unchecked. See [migration guide](docs/migrations/0.88-to-0.89.md).
+- **Fix (WASM bindings):** `Document.makeCard`'s generated TypeScript now marks
+  `fields` (and `body`) as optional (`fields?: Record<string, unknown>`,
+  `body?: string`), matching the doc comment and runtime behavior. They were
+  typed as required because `unchecked_param_type` drops the `?` marker; the
+  bindings now use `unchecked_optional_param_type`. Callers can build a bare
+  card with `Document.makeCard('kind')`.
+
 ## v0.88.0 - 2026-06-05
 
 - **Breaking (bindings + Rust API):** a single canonical **`Card` wire shape** now

package/README.md

@@ -8,6 +8,20 @@ Maintained by [TTQ](https://tonguetoquill.com).
 
 Use Quillmark in browsers/Node.js with explicit in-memory trees (`Map<string, Uint8Array>` / `Record<string, Uint8Array>`).
 
+The package exposes **one import surface**:
+
+- `@quillmark/wasm` (the root) — the **canonical API**: `Quill`, `Document`, and
+  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`,
+`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.
+
 ## Build
 
 ```bash
@@ -29,10 +43,10 @@ npm test
 ## Usage
 
 ```ts
-import { Document, Quillmark } from "@quillmark-test/wasm";
+import { Document, Quill, Engine } from "@quillmark/wasm";
 
-const engine = new Quillmark();
-const quill = engine.quill(tree);
+const quill = Quill.fromTree(tree);   // engine-free: build + validate
+const engine = new Engine();          // loads a backend lazily on first render
 
 const markdown = `~~~
 $quill: my_quill
@@ -43,16 +57,31 @@ title: My Document
 # Hello`;
 
 const parsed = Document.fromMarkdown(markdown);
-const result = quill.render(parsed, { format: "pdf" });
+const result = await engine.render(quill, parsed, { format: "pdf" });
 ```
 
 ## API
 
-### `new Quillmark()`
-Create engine.
-
-### `engine.quill(tree)`
-Build + validate + attach backend. Returns a render-ready `Quill`.
+### `new Engine(options?)`
+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.
+
+### `Quill.fromTree(tree)`
+Build + validate a `Quill` from an in-memory tree. Pure — the declared backend
+is resolved at render time, not here. Loads no backend binary.
 
 ### `Document.fromMarkdown(markdown)`
 Parse markdown to a parsed document. Throws a JS `Error` (with `.diagnostics`
@@ -206,18 +235,25 @@ 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?)`.
 
-### `quill.render(parsed, opts?)` vs. `quill.open(parsed)`
+### `engine.render(quill, parsed, opts?)` vs. `engine.open(quill, parsed)`
+
+> **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.
 
-Use **`Quill.render`** for one-shot exports (PDF/SVG/PNG) — compiles, emits
-artifacts, done. Use **`RenderSession`** (returned by `Quill.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.
+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.
 
-### `quill.render(parsed, opts?)`
-Render with a pre-parsed `Document`.
+### `engine.render(quill, parsed, opts?)`
+Render a pre-parsed `Document` against `quill`. Throws `UnsupportedBackend` if
+no registered backend matches the quill's declared backend.
 
-### `quill.open(parsed)` + `session.render(opts?)`
+### `engine.open(quill, parsed)` + `session.render(opts?)`
 Open once, render all or selected pages (`opts.pages`).
 
 The session also exposes `pageCount`, `backendId`, `supportsCanvas`,
@@ -273,8 +309,8 @@ canvas.style.height = `${result.layoutHeight}px`;
   `densityScale`. Loading the WASM module inside a Worker is the host's
   responsibility.
 - Backend support: gated by `supportsCanvas`. Probe upfront with
-  `quill.supportsCanvas` (or `session.supportsCanvas`) before mounting a
-  canvas-based UI; the throw on `paint` / `pageSize` remains the
+  `engine.supportsCanvas(quill)` (or `session.supportsCanvas`) before mounting
+  a canvas-based UI; the throw on `paint` / `pageSize` remains the
   enforcement contract and includes the resolved `backendId` for
   debugging.
 
@@ -287,7 +323,7 @@ A field's *cell* is inferred from whether its schema declares a `default:`:
   (`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; `quill.render(doc)` only throws for malformed input.
+  first-class; `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.
@@ -299,12 +335,28 @@ code covers unreplaced sentinels.
 
 ### Errors
 
-Every method that can fail throws a JS `Error` with `.diagnostics` attached:
+Every method that can fail throws a **`QuillmarkError`** — a JS `Error` with
+`.diagnostics` attached. The type and a guard are exported from the root:
 
 ```ts
-{ message: string, diagnostics: Diagnostic[] }
+import { isQuillmarkError, type QuillmarkError } from "@quillmark/wasm";
+
+try {
+  const result = await engine.render(quill, doc);
+} catch (e) {
+  if (isQuillmarkError(e)) {
+    for (const d of e.diagnostics) console.error(d.severity, d.message);
+  } else {
+    throw e; // not a quillmark failure — programming error, re-throw
+  }
+}
 ```
 
+`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
+errors from any build or WASM instance in the page).
+
 `diagnostics` is always non-empty — length 1 for most failures, length N for
 backend compilation errors. `message` is derived from `diagnostics`
 (`diagnostics[0].message` for single-diagnostic errors; an aggregate
@@ -319,7 +371,7 @@ compilation failures. The same shape applies to every throw site:
   variants (`InvalidFieldName`, `InvalidKindName`, `ReservedKind`,
   `IndexOutOfRange`) appear in `diagnostics[0].message` with the
   `[EditError::<Variant>]` prefix.
-- `quill.render` / `session.render` — backend compilation failures and
+- `engine.render` / `session.render` — backend compilation failures and
   validation errors.
 
 ### Lifecycle
@@ -338,7 +390,7 @@ For environments where `using` (the [explicit resource management][erm]
 proposal) hasn't landed, use an explicit `try` / `finally`:
 
 ```ts
-const session = quill.open(doc);
+const session = engine.open(quill, doc);
 try {
   for (let p = 0; p < session.pageCount; p++) {
     session.paint(ctx, p);
@@ -356,8 +408,8 @@ try {
   the legacy `~~~card-yaml` opener is still accepted but non-canonical)
   with a `$quill` system-metadata line. Empty input surfaces a dedicated
   "Empty markdown input cannot be parsed" message.
-- QUILL mismatch during `quill.render(parsed)` is a warning (`quill::ref_mismatch`), not an error.
-- Output schema APIs are no longer engine-level in WASM.
+- 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.
+- Output schema APIs live on `Quill`, not the engine.
 
 ## Changelog
 

package/{bundler → backends/typst}/wasm.d.ts

@@ -164,8 +164,9 @@ export interface QuillSchema {
 
 /**
  * Identity snapshot mirroring the `quill:` section of `Quill.yaml`.
- * The schema lives on `Quill.schema`.
- * Extra `quill:` keys appear as `unknown`.
+ * The schema lives on `Quill.schema`; the backend's output formats are a
+ * resolved-backend capability read from the engine (`Quillmark.supportedFormats`),
+ * not part of this pure-config snapshot.
  */
 export interface QuillMetadata {
     name: string;
@@ -173,8 +174,6 @@ export interface QuillMetadata {
     backend: string;
     author: string;
     description: string;
-    supportedFormats: OutputFormat[];
-    [key: string]: unknown;
 }
 
 
@@ -282,7 +281,7 @@ export class Document {
      * insertion order); `body` defaults to `""`. Kind validity is checked by
      * `pushCard` / `insertCard`, not here.
      */
-    static makeCard(kind: string, fields: Record<string, unknown>, body?: string | null): Card;
+    static makeCard(kind: string, fields?: Record<string, unknown>, body?: string): Card;
     /**
      * Move the card at `from` to position `to`. `from == to` is a no-op.
      */
@@ -445,8 +444,16 @@ export class Quill {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
-    open(doc: Document): RenderSession;
-    render(doc: Document, opts?: RenderOptions | null): RenderResult;
+    /**
+     * Build a quill from a file tree. Pure — no backend, no engine; the
+     * declared backend is resolved later, at render time.
+     *
+     * Accepts either a `Map<string, Uint8Array>` or a plain object
+     * (`Record<string, Uint8Array>`). Plain objects are walked via
+     * `Object.entries` at the boundary; the Rust side sees a single
+     * canonical shape.
+     */
+    static fromTree(tree: Map<string, Uint8Array>): Quill;
     /**
      * Seed a starter composable `Card` of the given kind (carries `$kind`),
      * committing its fields' `example:` values and leaving every other field
@@ -471,6 +478,19 @@ export class Quill {
      * `Card` shape as the `Document.main` getter.
      */
     seedMain(): Card;
+    /**
+     * Flatten this quill back into its canonical file tree — the inverse of
+     * [`fromTree`](Self::from_tree). Round-trips: `Quill.fromTree(q.toTree())`
+     * reproduces an equivalent quill.
+     *
+     * This is how a quill crosses a WASM linear-memory boundary as data: a
+     * `Quill` built in one build (e.g. the Typst-less `@quillmark/wasm/core`)
+     * cannot be passed to an engine in another (separate linear memories), so
+     * `@quillmark/wasm/runtime` re-feeds this tree to the backend build's
+     * `Quill.fromTree` on demand. Keys are `"/"`-joined relative paths,
+     * matching what `fromTree` accepts.
+     */
+    toTree(): Map<string, Uint8Array>;
     /**
      * Validate `doc` against this quill's schema, returning every diagnostic
      * (an empty array when the document is valid).
@@ -484,13 +504,17 @@ export class Quill {
      */
     validate(doc: Document): Diagnostic[];
     /**
-     * The resolved backend identifier (e.g. `"typst"`).
+     * The *declared* backend identifier (`config.backend`, e.g. `"typst"`).
+     * Intent, not a resolved capability — capability (`supportedFormats` /
+     * `supportsCanvas`) is read from the engine.
      */
     readonly backendId: string;
     readonly blueprint: string;
     /**
-     * Identity snapshot of the `quill:` section of `Quill.yaml`, plus
-     * `supportedFormats` and any extra `quill:` keys.
+     * Identity snapshot of the `quill:` section of `Quill.yaml` plus any extra
+     * `quill:` keys. Pure config — the backend's output formats are a
+     * resolved-backend capability read from the engine
+     * (`Quillmark.supportedFormats`), not part of this snapshot.
      */
     readonly metadata: QuillMetadata;
     /**
@@ -500,27 +524,38 @@ export class Quill {
      * `QuillSchema` shape.
      */
     readonly schema: QuillSchema;
-    /**
-     * `true` iff `RenderSession.paint` and `RenderSession.pageSize` will
-     * succeed for sessions opened by this quill. Use as a precondition
-     * probe before mounting a canvas-based preview UI.
-     */
-    readonly supportsCanvas: boolean;
 }
 
+/**
+ * Render engine: a backend registry and render dispatcher. Render build only —
+ * the core build constructs and validates quills without it.
+ */
 export class Quillmark {
     free(): void;
     [Symbol.dispose](): void;
     constructor();
     /**
-     * Load a quill from a file tree and attach the appropriate backend.
-     *
-     * Accepts either a `Map<string, Uint8Array>` or a plain object
-     * (`Record<string, Uint8Array>`). Plain objects are walked via
-     * `Object.entries` at the boundary; the Rust side sees a single
-     * canonical shape.
+     * Open an iterative render session for `doc` against `quill`'s backend.
+     */
+    open(quill: Quill, doc: Document): RenderSession;
+    /**
+     * Render `doc` against `quill` in one shot. Convenience over `open` +
+     * `RenderSession.render`: an unset `output_format` falls back to the
+     * backend's first supported format.
+     */
+    render(quill: Quill, doc: Document, opts?: RenderOptions | null): RenderResult;
+    /**
+     * The output formats `quill`'s backend can emit. Static capability —
+     * resolves the backend but compiles nothing. Throws `UnsupportedBackend`
+     * if no registered backend matches the quill's declared backend.
+     */
+    supportedFormats(quill: Quill): OutputFormat[];
+    /**
+     * `true` iff `quill`'s backend can paint sessions to a canvas. Asked of
+     * the real backend; `false` when the backend is unsupported or non-canvas.
+     * Use as a precondition probe before mounting a canvas-based preview UI.
      */
-    quill(tree: Map<string, Uint8Array>): Quill;
+    supportsCanvas(quill: Quill): boolean;
 }
 
 /**
@@ -558,7 +593,8 @@ export class RenderSession {
     readonly backendId: string;
     readonly pageCount: number;
     /**
-     * `true` iff `paint` and `pageSize` will succeed for this session.
+     * `true` iff `paint` and `pageSize` will succeed for this session. The
+     * backend's canvas capability, captured at open time.
      */
     readonly supportsCanvas: boolean;
     /**