@quillmark/wasm 0.101.0 → 0.103.0

package/CHANGELOG.md

@@ -1,5 +1,186 @@
 # Changelog
 
+## 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`
+
+<!-- seed: commits since v0.102.0, confirm the entries above cover them, then delete this comment
+- ci: tag the merge commit, and serialize a release against itself
+- ci: drop the tagger GitHub App from the release workflows
+- Cut SECURITY.md, and operations.md down to what only it can say
+- Drop the audit gate; keep the reachability finding in ci.yml's note
+- Fix two wrong claims, a dead property, and the stdout bug the review found
+- dense-prose pass over the added prose, and read the fixture once
+- Close four production-readiness gaps: audit gate, ops docs, CLI tests, PDF fuzzing
+- Drop the README's claim about the deleted sentinel patch
+- dense-prose pass: cut the restatement the change introduced
+- docs: the 0.102 → 0.103 step, and correct the surface it describes
+- The gate is the only door to the core surface
+- docs(migration): a span guide for 0.92 → 0.102
+- Cut over-specified style rules; author preference wins
+- dense-prose: remove the em-dash ban
+- dense-prose: drop the line-budget clause
+- dense-prose: wrong is worse than missing; relax em-dash ban
+- docs: dense-prose pass over the conform-scope and date-grammar prose
+- docs: migration guides are era-stamped, not immutable
+- docs(migrations): give the datetime split its corpus audit step
+- docs: scope conform to content fields, state the date corpus precondition
+- Tighten the failure-delivery prose
+- Deliver init's conflict as a rejection, not a synchronous throw
+-->
+
+
+## v0.102.0 - 2026-08-04
+
+The pre-1.0 vocabulary reset. Verbs, diagnostic codes, and two words that meant
+different things at different altitudes. Documents and stored blobs are
+untouched: no document reparses, no blob remigrates, and the storage wire format
+is byte-identical, but nearly every consumer touches at least one renamed verb.
+The diagnostic codes are the part that could not wait, since consumers route on
+them and 1.0 freezes them. All breaking changes are covered by
+`docs/migrations/0.101-to-0.102.md`. Only two behaviors change, both called out
+below. Separately, `@quillmark/wasm` ships `--target web`, which makes
+`await init()` mandatory and the bundler plugins the package used to demand
+unnecessary.
+
+- refactor(core,wasm,python)!: the verb vocabulary is reset to say what the code
+  does. `install_body` / `install_field` / `doc.install` become `overwrite_*` /
+  `doc.overwrite`: the content lane is a ladder sorted by the fate of the
+  identity anchors already on the value (overwrite destroys, revise rebases,
+  apply preserves), and only the first keeps nothing, which grouping the three as
+  "identity-aware" hid. `LiveSession::apply` becomes `update`, taking the trait
+  seam, the feature-gated raw-plate seam, and `backend::apply_unsupported` →
+  `backend::update_unsupported` with it, so the content lane's `applyChange`
+  splice is no longer a homograph of a whole-document recompile.
+  `apply_field_richtext_change` becomes `apply_field_change`, matching its
+  schema-blind neighbour `revise_field`, which never carried the codec in its
+  name. `store_seed_namespace` / `remove_seed_namespace` become
+  `store_seed_overlay` / `remove_seed_overlay`, closing the asymmetry with the
+  `seedOverlay` read and the `SeedOverlay` type that already shipped: `$seed` is
+  keyed by a validated card-kind, `$ext` by a free-form consumer namespace.
+  `getMarkdown` and reader `get_body` become `bodyMarkdown` / `body_markdown`,
+  the name core already used, so one projection has one name on every surface
+  (#1186). See `docs/migrations/0.101-to-0.102.md`
+- refactor(core,wasm,python)!: the mutator and validation diagnostic codes are
+  corrected, and the content-field failures carry the codec that ran.
+  `edit::field_richtext_decode` becomes `edit::field_decode` and
+  `edit::field_richtext_not_inline` becomes `edit::field_not_inline`, each
+  gaining a `codec` arg (`"richtext"` or `"plaintext"`): both were raised for
+  plaintext failures under a richtext name, and `plaintext(inline)` fell through
+  to the generic code. `edit::field_conform` becomes
+  `edit::field_coercion_failed`, killing the `conform::field_conform` stutter and
+  landing the variant beside its real twin `validation::coercion_failed`, minted
+  from the same `CoercionError`. `richtext::not_inline` and
+  `plaintext::not_plain` become `validation::not_inline` / `validation::not_plain`,
+  stage-namespaced like every other code. The `conform::*` twins rename in
+  lockstep. Route on the code and read `codec` for the lane (#1186). See
+  `docs/migrations/0.101-to-0.102.md`
+- fix(core)!: a splice against an absent field is no longer a decode error. The
+  writer `set_body` / `setBody` becomes `revise_body` / `reviseBody` and returns
+  the text `Delta` it was already computing (a body carries no field schema, so a
+  typed-lane verb had nothing to type); Python discards the receipt, as on
+  `revise_field`. `apply_field_change` on an absent field splices against the
+  empty content, as `revise_field` diffs against it, instead of reporting
+  `FieldRichtextDecode { message: "field is absent" }`: the one place in the API
+  where a missing field was not simply `None`. No error is lost. A bundle that
+  expected content still fails, and now reports the condition it hit, since the
+  text delta declares the base length it was computed against, so a stale splice
+  lands as `edit::content_apply`. Route a vanished-field check on that code, or
+  check presence before splicing. These are the release's only behavior changes
+  (#1186). See `docs/migrations/0.101-to-0.102.md`
+- refactor(core)!: `EditError::variant_name` is removed and the typed primitives
+  leave the documented surface. The bare variant name was a second discriminator
+  kept in lockstep with `code()` that nothing routed on: both binding error
+  mappers stamp `code()` onto the `Diagnostic` they raise, and `ERROR.md` has
+  said identity is the code since the `edit::*` family landed. Assert on `code()`
+  or match the enum, which is `#[non_exhaustive]` either way. `Card::commit_field`
+  and `Card::revise_field_checked` become `#[doc(hidden)]`: a resolved
+  `FieldSchema` argument was the only thing telling them from their opaque and
+  schema-blind neighbours, and disambiguating by argument is a third mechanism
+  beside the receiver and the verb. `quill.writer(&mut doc)` is the typed door on
+  every surface now, core included; the primitives stay callable on the same
+  terms as the other hidden items (#1186). See `docs/migrations/0.101-to-0.102.md`
+- docs(content,core)!: restoring a deleted island re-lands its original id, and
+  the island channel states two contracts it had left to the implementation. The
+  never-ambient minting rule (continue the field's positional `isl-{n}` sequence,
+  never a UUID or a clock reading) covers a *new* island; a delete frees its id
+  and the id travels back with the island, so an editor that mints fresh on undo
+  renames it, moving the content hash of a document the user believes they
+  restored. A pasted copy of a live island is new and mints fresh. Alongside it:
+  an island op's `at` is *sequenced*, counting the text the delta and this
+  bundle's earlier island ops left rather than the shared post-delta frame; and a
+  producer's whole-field diff that carries an island slot must split into the
+  slot-free `delta` plus one `Insert` per slot, since a slot in an insert string
+  orphans. Neither is a behavior change, and a producer that guessed wrong got a
+  wrong document rather than an error (#1185)
+- feat(wasm)!: the package ships `--target web` and the runtime owns
+  instantiation, so `await init()` once at startup is required before any export
+  is used. `--target bundler` emitted `import * as wasm from "./wasm_bg.wasm"`,
+  which no browser and no bundler resolves natively; the plugin that fixed it
+  rewrote the import into a top-level await, and because the runtime statically
+  re-exports core, that await landed on the static module graph of everything
+  importing `@quillmark/wasm`: a permanent constraint on consumer architecture
+  and a blank SvelteKit route in Safari's dev server that neither Chrome nor
+  `vite build` showed. In exchange, `vite-plugin-wasm` and
+  `vite-plugin-top-level-await` are no longer needed, a static import is safe
+  anywhere including SSR, and plain Node can import the package at all (the ESM
+  `.wasm` import needed `--experimental-wasm-modules`). Only
+  `optimizeDeps: { exclude: ['@quillmark/wasm'] }` stays, for Vite's dev server.
+  `init` memoizes its promise, so several entry points share one instantiation
+  and a failed attempt clears the memo for a retry; backends are not the
+  consumer's to initialize, since `Engine` instantiates one inside its lazy load.
+  Reaching the surface early throws `runtime::not_initialized` naming the fix,
+  and `build-wasm.sh` asserts both the guard's anchors and that no artifact
+  carries a `.wasm` import or a top-level await. `initSync` is not exported: the
+  capability remains through `init(source)`, which takes bytes, a `Response`, a
+  `WebAssembly.Module`, or a URL (#1189). See `docs/migrations/0.101-to-0.102.md`
+
 ## v0.101.0 - 2026-08-03
 
 - refactor(core): gate the raw-plate seam behind a feature, and fixes from review

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
@@ -30,8 +30,9 @@ 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 bundler` and `--weak-refs` enabled (see
-[Lifecycle](#lifecycle)).
+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.
 
 ## Test
 
@@ -45,7 +46,9 @@ npm test
 ## Usage
 
 ```ts
-import { Document, Quill, Engine } from "@quillmark/wasm";
+import { init, Engine } from "@quillmark/wasm";
+
+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
@@ -62,6 +65,58 @@ const parsed = Document.fromMarkdown(markdown);
 const result = await engine.render(quill, parsed, { format: "pdf" });
 ```
 
+## Initialization
+
+`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, Engine } from "@quillmark/wasm";
+const { Quill, Document } = await init();
+```
+
+The same line works everywhere: the binary streams from a URL in a browser and
+is read off disk under Node, chosen by the package's `#quillmark-env` subpath
+import rather than a runtime environment check. No bundler plugin is required:
+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 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.
+
+**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
+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.
+
+**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:
+
+```js
+// vite.config.js
+export default { optimizeDeps: { exclude: ["@quillmark/wasm"] } };
+```
+
+A load failure surfaces as `runtime::init_failed`, whose hint names that line.
+
 ## API
 
 ### `new Engine(options?)`
@@ -107,7 +162,7 @@ The **bound door**, and the primary ingestion path. `quill.parse` is
 `Document.fromMarkdown` followed by `conform`: the returned document's declared
 content fields rest at one form per codec (a `richtext` field as the canonical
 content object, a `plaintext` field as its literal string), so `getStored`
-answers "corpus or string?" by the field's declared codec rather than by how the
+answers "content object or string?" by the field's declared codec rather than by how the
 document was built. Parse warnings and the `conform::*` warnings both ride
 `doc.warnings`.
 
@@ -199,13 +254,13 @@ and writes that same value.
 To detect a version mismatch before parsing, use the static accessors:
 
 ```ts
-const v = Document.schemaVersionOf(blob); // undefined | string
-if (v && v !== Document.currentSchemaVersion()) {
+const v = Document.storageVersionOf(blob); // undefined | string
+if (v && v !== Document.currentStorageVersion()) {
   // payload is from a build with a different model version
 }
 ```
 
-`schemaVersionOf` does not validate the payload: it only reads the
+`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.
@@ -285,11 +340,11 @@ main card's `qty`, `doc.storeField({ card: 2, field: "qty" }, 3)` a composable
 card's. Reads are total over the field axis (`getStored` → `undefined`, `isFill` → `false` for
 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`; `getMarkdown` is the body markdown read (a `CardAddr`; a field's
+`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 corpus either way read `quill.reader(doc).getContent(addr)`, which
+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
 `CardAddr` (`{ card? }`) first: `doc.getExt({ card: 2 })`, and the batch below.
 
@@ -309,7 +364,7 @@ writes go through the schema-bound writer while the quill-free opaque store sits
 on `Document` itself (**store** = verbatim, **set** = typed):
 
 - **`quill.writer(doc)`: the typed door whenever a quill is in hand.** Bind the
-  schema once and issue bare `set` / `setAll` / `setBody` / `reviseField` /
+  schema once and issue bare `set` / `setAll` / `reviseBody` / `reviseField` /
   `addCard` / `card(i)`. Each resolves the field's schema `type`, coerces the
   value to its canonical form (`"3"` → `3`, a markdown string → a richtext
   content), and **fails now** on a mismatch instead of at render. A name the schema
@@ -362,16 +417,16 @@ write.
 ```ts
 const v = quill.reader(doc);
 v.get("subject");                                   // by declared type: richtext → markdown, plaintext → literal text
-v.getContent("subject");                            // the same read as a Content corpus, whichever lane stored it
-v.getBody();                                        // the main body markdown (quill-free)
+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
 ```
 
-`get` projects and `getContent` returns the corpus; both decode through the codec
+`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 `FieldRichtextDecode`; an absent field reads back `undefined`.
+value throws `FieldDecode`; an absent field reads back `undefined`.
 
 ### `engine.render(quill, parsed, opts?)` vs. `engine.open(quill, parsed)`
 
@@ -497,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
@@ -515,7 +578,7 @@ compilation failures. The same shape applies to every throw site:
 - `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_conform`, …). Route on `diagnostics[0].code`, never on message
+  `edit::field_coercion_failed`, …). Route on `diagnostics[0].code`, never on message
   text.
 - `engine.render` / `session.render`: backend compilation failures and
   validation errors.
@@ -527,6 +590,9 @@ compilation failures. The same shape applies to every throw site:
 
 ### Lifecycle
 
+Handles begin at [`init`](#initialization), which instantiates the core build;
+`Engine` instantiates a backend on the first render against it.
+
 The wasm bindings are built with `--weak-refs`, so dropped `Document`,
 `Quill`, and `LiveSession` handles are reclaimed by `FinalizationRegistry`
 without manual `.free()` discipline. `.free()` is still emitted as an eager