@quillmark/wasm 0.100.0 → 0.102.0

package/CHANGELOG.md

@@ -1,5 +1,129 @@
 # Changelog
 
+## 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
+- docs(core): state the conform gate's codes instead of linking a private item
+- refactor(core): bind a live session to its quill so apply takes a Document
+- feat(quillmark): the facade names what the read and preview flows return
+- docs(content,wasm): density pass over the island channel's prose
+- feat(content,core,wasm)!: reach islands through the op vocabulary
+- refactor(core)!: `Payload` becomes a read view
+- refactor(core)!: collapse the schema-free field projection
+- refactor(core)!: fold `Quill`'s file queries into `FileTreeNode`
+- fix(core): repoint the doc references the `from_yaml` removal orphaned
+- refactor(quillmark): move the facade gate off the front page, and stop tests reaching past it
+- docs: migration guide for the 0.101 surface removals
+- refactor(core)!: drop the lossy `QuillConfig::from_yaml`
+- refactor(core)!: `Document::from_main_and_cards` becomes crate-internal
+- feat(quillmark): the facade covers authoring, and the examples enter through the bound door
+
+
 ## v0.100.0 - 2026-08-03
 
 A content field gets one resting form, and the last reserved `$` key with no

package/README.md

@@ -30,8 +30,10 @@ 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 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.
 
 ## Test
 
@@ -45,7 +47,9 @@ npm test
 ## Usage
 
 ```ts
-import { Document, Quill, Engine } from "@quillmark/wasm";
+import { init, Document, Quill, Engine } from "@quillmark/wasm";
+
+await init();                         // once at startup; 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 +66,52 @@ const parsed = Document.fromMarkdown(markdown);
 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.
+
+```js
+import { init, Quill, Engine } from "@quillmark/wasm";
+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 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.
+
+**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
+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.
+
+**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.
+
+**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 +157,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 +249,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 +335,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 +359,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 +412,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)`
 
@@ -515,7 +565,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 +577,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