@quillmark/wasm 0.102.0 → 0.103.0

package/CHANGELOG.md

@@ -1,5 +1,81 @@
 # 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

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
@@ -31,9 +31,8 @@ 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
-[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.
+[Initialization](#initialization) and [Lifecycle](#lifecycle)). It then asserts
+none of them carries a `.wasm` ESM import or a top-level await.
 
 ## Test
 
@@ -47,9 +46,9 @@ npm test
 ## Usage
 
 ```ts
-import { init, Document, Quill, Engine } from "@quillmark/wasm";
+import { init, Engine } from "@quillmark/wasm";
 
-await init();                         // once at startup; see Initialization
+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
@@ -68,12 +67,13 @@ 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.
+`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, Quill, Engine } from "@quillmark/wasm";
-await init();
+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
@@ -83,10 +83,11 @@ 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.
+`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.
@@ -94,13 +95,17 @@ 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.
+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.
 
-**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.
+**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:
@@ -547,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

package/backends/pdfform/wasm.js

@@ -2885,8 +2885,7 @@ if (!('encodeInto' in cachedTextEncoder)) {
 
 let WASM_VECTOR_LEN = 0;
 
-import { uninitSentinel, UNINIT } from "../../runtime/uninit.js";
-let wasmModule, wasm = uninitSentinel("@quillmark/wasm internal error: the 'pdfform' backend was used before instantiation.", "This is a bug in @quillmark/wasm, not in your code. Please report it.");
+let wasmModule, wasm;
 function __wbg_finalize_init(instance, module) {
     wasm = instance.exports;
     wasmModule = module;
@@ -2933,7 +2932,7 @@ async function __wbg_load(module, imports) {
 }
 
 function initSync(module) {
-    if (wasm !== undefined && !wasm[UNINIT]) return wasm;
+    if (wasm !== undefined) return wasm;
 
 
     if (module !== undefined) {
@@ -2953,7 +2952,7 @@ function initSync(module) {
 }
 
 async function __wbg_init(module_or_path) {
-    if (wasm !== undefined && !wasm[UNINIT]) return wasm;
+    if (wasm !== undefined) return wasm;
 
 
     if (module_or_path !== undefined) {

package/backends/typst/wasm.js

@@ -2909,8 +2909,7 @@ if (!('encodeInto' in cachedTextEncoder)) {
 
 let WASM_VECTOR_LEN = 0;
 
-import { uninitSentinel, UNINIT } from "../../runtime/uninit.js";
-let wasmModule, wasm = uninitSentinel("@quillmark/wasm internal error: the 'typst' backend was used before instantiation.", "This is a bug in @quillmark/wasm, not in your code. Please report it.");
+let wasmModule, wasm;
 function __wbg_finalize_init(instance, module) {
     wasm = instance.exports;
     wasmModule = module;
@@ -2957,7 +2956,7 @@ async function __wbg_load(module, imports) {
 }
 
 function initSync(module) {
-    if (wasm !== undefined && !wasm[UNINIT]) return wasm;
+    if (wasm !== undefined) return wasm;
 
 
     if (module !== undefined) {
@@ -2977,7 +2976,7 @@ function initSync(module) {
 }
 
 async function __wbg_init(module_or_path) {
-    if (wasm !== undefined && !wasm[UNINIT]) return wasm;
+    if (wasm !== undefined) return wasm;
 
 
     if (module_or_path !== undefined) {

package/core/wasm.js

@@ -2377,8 +2377,7 @@ if (!('encodeInto' in cachedTextEncoder)) {
 
 let WASM_VECTOR_LEN = 0;
 
-import { uninitSentinel, UNINIT } from "../runtime/uninit.js";
-let wasmModule, wasm = uninitSentinel("@quillmark/wasm is not initialized. Call 'await init()' once at startup, before Quill, Document, Engine, or any other export is used.", "Add: import { init } from '@quillmark/wasm'; await init(); once, anywhere before first use. Extra calls are free.");
+let wasmModule, wasm;
 function __wbg_finalize_init(instance, module) {
     wasm = instance.exports;
     wasmModule = module;
@@ -2424,7 +2423,7 @@ async function __wbg_load(module, imports) {
 }
 
 function initSync(module) {
-    if (wasm !== undefined && !wasm[UNINIT]) return wasm;
+    if (wasm !== undefined) return wasm;
 
 
     if (module !== undefined) {
@@ -2444,7 +2443,7 @@ function initSync(module) {
 }
 
 async function __wbg_init(module_or_path) {
-    if (wasm !== undefined && !wasm[UNINIT]) return wasm;
+    if (wasm !== undefined) return wasm;
 
 
     if (module_or_path !== undefined) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quillmark/wasm",
-  "version": "0.102.0",
+  "version": "0.103.0",
   "description": "WebAssembly bindings for Quillmark, a schema-driven document engine",
   "type": "module",
   "license": "Apache-2.0",

package/runtime/runtime.d.ts

@@ -1,46 +1,82 @@
 // @quillmark/wasm/runtime: canonical consumer API.
 //
-// `Quill`/`Document` are re-exported verbatim from the core build (their full
-// surface, no drift). Render-side types (`RenderResult`, `RenderOptions`,
-// `Artifact`, `OutputFormat`, `PageSize`, `PaintOptions`, `PaintResult`) are
-// defined HERE as the canonical, backend-neutral render contract: NOT sourced
-// from any one private backend build. A type-level drift guard
-// (`runtime.types.test-d.ts`, via `npm run typecheck`) asserts they stay
-// mutually assignable with the Typst backend's generated declarations. `Engine`
-// is the render dispatcher that hides the cross-WASM-memory seam.
-
-// CANONICAL INVARIANT: the root re-exports the core build's `Quill`/`Document`
-// verbatim; they are the SAME classes, never wrappers. There is exactly one
-// public entry point, so this is a structural fact. Replacing the re-export
-// with a wrapper is a breaking design change, not a refactor. See runtime.js.
+// Render-side types (`RenderResult`, `RenderOptions`, `Artifact`,
+// `OutputFormat`, `PageSize`, `PaintOptions`, `PaintResult`) are defined HERE as
+// the canonical, backend-neutral render contract: NOT sourced from any one
+// private backend build. A type-level drift guard (`runtime.types.test-d.ts`,
+// via `npm run typecheck`) asserts they stay mutually assignable with the Typst
+// backend's generated declarations. `Engine` is the render dispatcher that hides
+// the cross-WASM-memory seam.
+
+// CANONICAL INVARIANT: the `Quill`/`Document` `init` resolves to ARE the core
+// build's classes, their full surface, never wrappers. There is exactly one
+// public entry point, so this is a structural fact. Handing out a wrapper is a
+// breaking design change, not a refactor. See runtime.js.
 //
 // ONE COPY PER PROCESS: two copies of this package are two WASM linear memories
 // and two `Quill`/`Document` classes. Every method taking a handle refuses one
 // belonging to another copy, with a `QuillmarkError` naming `npm ls
 // @quillmark/wasm`. Errors are the exception: `isQuillmarkError` is structural.
-export { Quill, Document } from '../core/wasm.js';
 
-import type { InitInput } from '../core/wasm.js';
+// The instance types, so an annotation (`let q: Quill`) needs no await. Their
+// values are `CoreSurface`'s.
+export type { Quill, Document } from '../core/wasm.js';
+
+import type {
+	InitInput,
+	Quill as CoreQuill,
+	Document as CoreDocument,
+	importMarkdown,
+	exportMarkdown,
+	rebase,
+	mapPos,
+	parseDocPath,
+	formatDocPath
+} from '../core/wasm.js';
 
 /**
- * Instantiate the core WASM build. Call once at startup, before any other
- * export is used; extra calls are free.
+ * The core build's surface: what its WASM instance stands behind, and therefore
+ * what `init` resolves to. Exported nowhere statically, so awaiting is the only
+ * way to hold one.
  *
- * ```js
- * import { init, Quill, Engine } from '@quillmark/wasm';
- * await init();
+ * `Quill` and `Document` here are the classes, statics included
+ * (`Quill.fromTree`, `Document.fromMarkdown`), not the instance types above.
+ * Each member carries the core build's own declaration, docs and all.
+ */
+export interface CoreSurface {
+	Quill: typeof CoreQuill;
+	Document: typeof CoreDocument;
+	importMarkdown: typeof importMarkdown;
+	exportMarkdown: typeof exportMarkdown;
+	rebase: typeof rebase;
+	mapPos: typeof mapPos;
+	parseDocPath: typeof parseDocPath;
+	formatDocPath: typeof formatDocPath;
+}
+
+/**
+ * Instantiate the core WASM build and resolve to its surface.
+ *
+ * ```ts
+ * import { init } from '@quillmark/wasm';
+ * const { Quill, Document } = await init();
  * ```
  *
  * The builds are `--target web`: classes export synchronously, the instance
  * behind them arrives here. Identical in every environment: the binary is
  * fetched and streamed in a browser, read off disk under Node, and the call
- * site is the same line. Reaching a class before this resolves throws
- * `runtime::not_initialized` naming the fix.
+ * site is the same line.
+ *
+ * THE ONLY DOOR to `Quill`, `Document` and the free functions, so the pre-init
+ * mistake is not expressible. Destructure at each entry point (route loader,
+ * hydration path, worker) rather than threading one result around: the gate is
+ * memoized and concurrency-safe, so every await after the first is free. A
+ * failed init clears the memo, so a retry is possible. Per realm: a Worker
+ * loads and initializes its own copy.
  *
- * Idempotent and concurrency-safe: every call returns the same promise, so
- * `await init()` at several entry points costs one instantiation. A failed init
- * clears the memo, so a retry is possible. Per realm: a Worker loads and
- * initializes its own copy.
+ * Both failure codes REJECT, so one `catch` covers the gate. Delivery follows
+ * the function kind across this surface: a sync verb throws, a
+ * promise-returning verb rejects, and nothing does both.
  *
  * Backends are NOT initialized here. `Engine` instantiates a backend inside its
  * lazy load, on first render against it.
@@ -48,15 +84,10 @@ import type { InitInput } from '../core/wasm.js';
  * @param source override the binary's source (bytes, a `Response`, a
  *   `WebAssembly.Module`, 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
+ *   different source rejects with `runtime::init_conflict` rather than silently
  *   ignoring it. Passing the same value again is fine.
  */
-export declare function init(source?: InitInput): Promise<void>;
-// The document-free content codec, re-exported from the core build.
-export { importMarkdown, exportMarkdown, rebase, mapPos } from '../core/wasm.js';
-// The document-model path parser/serializer: route on `Diagnostic.path`
-// segments instead of regexing the string.
-export { parseDocPath, formatDocPath } from '../core/wasm.js';
+export declare function init(source?: InitInput): Promise<CoreSurface>;
 
 import type { CardAddr } from '../core/wasm.js';
 

package/runtime/runtime.js

@@ -2,15 +2,17 @@
 //
 // @quillmark/wasm/runtime: the canonical consumer API.
 //
-// Consumers import `Quill`, `Document`, and `Engine` from here and never touch
-// the build-specific subpaths. The package ships multiple WASM binaries with
-// SEPARATE linear memories: a Typst-less `core` build (small, eager) that is
-// the canonical home of `Quill`/`Document`, and one private backend binary per
-// backend (`backends/typst/` today; more later) that carries an engine. A
-// handle from one memory cannot be used by another. This module hides that seam
-// and is exposed at the package root (`@quillmark/wasm`):
+// Consumers reach `Quill` and `Document` through `await init()` and `Engine`
+// as a static export, and never touch the build-specific subpaths. The package
+// ships multiple WASM binaries with SEPARATE linear memories: a Typst-less
+// `core` build (small, eager) that is the canonical home of `Quill`/`Document`,
+// and one private backend binary per backend (`backends/typst/` today; more
+// later) that carries an engine. A handle from one memory cannot be used by
+// another. This module hides that seam and is exposed at the package root
+// (`@quillmark/wasm`):
 //
-//   - `Quill` and `Document` ARE the core build's classes, re-exported. They
+//   - `Quill` and `Document` ARE the core build's classes, handed out by the
+//     gate (§ "Initialization"). They
 //     hold the canonical data and the full sync surface (schema / validate /
 //     seed / mutate / toJson / toTree). No backend is loaded to use them, so
 //     the editor/validation path never pays for a multi-MB backend binary.
@@ -38,51 +40,42 @@
 // The cross-memory crossing is therefore invisible: a consumer hands canonical
 // `Quill`/`Document` to `engine.render(...)` and gets a `RenderResult` back.
 
-// ── CANONICAL INVARIANT: re-export the core build, never wrap ───────────────
-// The root re-exports the core build's `Quill`/`Document` classes verbatim,
-// NOT subclasses or wrappers. There is exactly ONE public entry point (this
-// module), so this identity is a structural fact: `Quill`/`Document` ARE the
-// core classes, and the only boundary that needs crossing is core→backend (a
-// separate WASM memory), which `Engine` does internally as data
-// (`toTree`/`toJson`).
+// ── CANONICAL INVARIANT: hand out the core build's classes, never wrap ──────
+// The `Quill`/`Document` a consumer holds ARE the core build's classes, NOT
+// subclasses or wrappers. `init` resolves to them (§ "Initialization"); which
+// door they come through changes nothing about the identity. The only boundary
+// that needs crossing is core→backend (a separate WASM memory), which `Engine`
+// does internally as data (`toTree`/`toJson`).
 //
-// Do NOT replace this with a wrapper class: that breaks the identity and turns
-// a structural fact into a converted type (a breaking design change, not a
-// refactor). The `runtime.test.js` "re-exports the internal core build classes
-// verbatim" case (`Quill === CoreQuill`) is the executable guard for this
-// invariant.
-//
-// It is also why the pre-init guard sits inside the generated builds instead
-// of here: nothing may stand between a consumer and these classes
-// (runtime/uninit.js).
+// Do NOT hand out a wrapper: that breaks the identity and turns a structural
+// fact into a converted type (a breaking design change, not a refactor). The
+// `runtime.test.js` "hands out the internal core build classes verbatim" case
+// (`Quill === CoreQuill`) is the executable guard for this invariant.
 //
 // The identity is what makes `instanceof` the whole membership test: a handle
 // either belongs to this copy's classes or it belongs to another copy, and the
 // second is always a consumer bug. `Engine` is NOT duck-typed on its inputs; it
 // checks them. See § "Handles from another copy" below.
 //
-// Imported (not bare re-exported) so `Quill` is a local binding this module can
-// augment: `quill.writer(doc)` is patched onto its prototype below. The
-// re-export keeps the identity: the exported `Quill` IS the core class.
+// Local bindings, so this module can augment them: `quill.writer(doc)` is
+// patched onto the prototype below, and `instanceof` reads them directly.
 //
 // The default import is the core build's generated instantiation entry
 // (`--target web`); `init` below is the only thing that calls it.
 import initCore, { Quill, Document } from '../core/wasm.js';
-export { Quill, Document };
 // The wasm byte source, resolved per environment by package.json's `imports`
 // map: a pass-through in a browser (the glue fetches and streams the URL
 // itself), a `node:fs` read under Node, whose `fetch` rejects `file:` URLs.
 // Resolution-time, so `node:fs` never enters a browser graph.
 import { toModuleSource } from '#quillmark-env';
-// The document-free content codec: re-exported verbatim from the core build so
-// the runtime subpath exposes `exportMarkdown(body)` (the on-demand markdown
-// projection), `importMarkdown`, and the position-mapping pair (`rebase`,
-// `mapPos`).
-export { importMarkdown, exportMarkdown, rebase, mapPos } from '../core/wasm.js';
+// The document-free content codec: `exportMarkdown(body)` (the on-demand
+// markdown projection), `importMarkdown`, and the position-mapping pair
+// (`rebase`, `mapPos`).
+import { importMarkdown, exportMarkdown, rebase, mapPos } from '../core/wasm.js';
 // The document-model path parser/serializer: `parseDocPath(str) => DocPathSeg[]`
 // and its inverse `formatDocPath`, so a consumer routes on `Diagnostic.path`
 // segments instead of reverse-engineering the grammar.
-export { parseDocPath, formatDocPath } from '../core/wasm.js';
+import { parseDocPath, formatDocPath } from '../core/wasm.js';
 
 // ── Initialization ──────────────────────────────────────────────────────────
 // The builds are `--target web`: they export their classes synchronously but
@@ -90,64 +83,129 @@ export { parseDocPath, formatDocPath } from '../core/wasm.js';
 // that for core, behind one awaited gate; `Engine` owns it for the backends,
 // inside their lazy load, so a consumer never initializes a backend by hand.
 //
+// THE GATE IS THE ONLY DOOR. `init` resolves to the core surface, and this
+// module exports none of it statically, so a handle is unobtainable without
+// having awaited: the precondition is structural rather than a convention the
+// caller has to know. package.json's `exports` map carries exactly one entry,
+// so there is no subpath around the gate either.
+//
 // The gate is the shape the lazy-backend idiom (§ DEFAULT_BACKENDS) takes when
 // the surface it guards cannot be async: `Quill.fromTree` and `seedDocument`
 // are sync and static, so there is nowhere to hide an await except in front.
 //
-// Reaching core before the gate resolves is not a silent wrong answer: the
-// build is patched to throw `runtime::not_initialized` naming the fix
-// (runtime/uninit.js).
+// WHAT STAYS STATIC is what needs no instance. `MAIN_CARD_ADDR`, the open-set
+// guards and `isQuillmarkError` are pure JS over plain objects; gating them
+// would cost a consumer of one an await it has no use for.
+//
+// The classes stay static too, and are gated by their ARGUMENTS. Every `Engine`
+// verb takes a `Quill` first (`#backendOf` is the single reader), and the
+// writer/reader constructors take both handles, so a caller who has not awaited
+// cannot produce an argument to call them with. `new Engine()` alone touches no
+// wasm: it validates a descriptor map. Holding them out of the gate keeps them
+// tree-shakable, so the editor path drops the dispatcher it never calls.
+//
+// FAILURE DELIVERY follows the FUNCTION kind, not the failure kind: a sync verb
+// throws, a promise-returning verb rejects, and nothing does both. A
+// programming error reached through a promise-returning verb
+// (`runtime::foreign_handle` inside `Engine.render`) rejects like any other.
+// `init` is the one promise-returning export not declared `async`, because the
+// memo is returned by identity; its conflict guard rejects explicitly to hold
+// the rule, which the return type cannot declare and a `.catch` would not see.
 
-/** The in-flight or settled core instantiation. The memo is the PROMISE, not a
- * boolean, so concurrent callers share one instantiation instead of racing. */
+/**
+ * The gated surface: the core build's values, which are exactly the ones its
+ * instance stands behind. Frozen and built at module scope, because the classes
+ * and functions themselves resolve synchronously (only the instance behind them
+ * is late), so there is nothing to defer and no per-call allocation.
+ *
+ * Membership is derived, not chosen: it is the core build's exports minus its
+ * instantiation machinery (`default`, `initSync`, and the start-section
+ * `start`), which `init` owns and no consumer calls. `init.test.js` § "the
+ * gated surface" computes that set and pins it, so a new core export that never
+ * reaches here fails there rather than going missing.
+ * @type {import('./runtime.js').CoreSurface}
+ */
+const CORE_SURFACE = Object.freeze({
+	Quill,
+	Document,
+	importMarkdown,
+	exportMarkdown,
+	rebase,
+	mapPos,
+	parseDocPath,
+	formatDocPath
+});
+
+/** The in-flight or settled core instantiation, resolving to `CORE_SURFACE`.
+ * The memo is the PROMISE, not a boolean, so concurrent callers share one
+ * instantiation instead of racing.
+ * @type {Promise<import('./runtime.js').CoreSurface> | undefined} */
 let coreInit;
 /** The source `init` was first called with; the conflict check reads it. */
 let coreInitSource;
 
 /**
- * Instantiate the core WASM build. Call once at startup, before any other
- * export is used; extra calls are free.
+ * Instantiate the core WASM build and resolve to its surface.
  *
  * ```js
- * import { init, Quill, Engine } from '@quillmark/wasm';
- * await init();
+ * import { init } from '@quillmark/wasm';
+ * const { Quill, Document } = await init();
  * ```
  *
+ * The classes and the free functions come from here and nowhere else, so the
+ * pre-init mistake is not expressible. Destructure at each entry point (route
+ * loader, hydration path, worker) rather than threading one result around: the
+ * gate is memoized, so every await after the first is free.
+ *
  * Identical in every environment: in a browser the binary is fetched and
  * streamed, under Node it is read off disk, and the call site is the same line.
  *
- * Idempotent and concurrency-safe: every call returns the same promise, so
- * `await init()` at each of several entry points costs one instantiation. A
- * failed init clears the memo, so a retry is possible.
+ * Idempotent and concurrency-safe: every non-conflicting call returns the same
+ * promise, so several entry points cost one instantiation. A failed init clears
+ * the memo, so a retry is possible.
+ *
+ * Both failures reject (§ "Initialization", FAILURE DELIVERY): one `catch`
+ * around `await init(...)` covers `runtime::init_conflict` and
+ * `runtime::init_failed` alike.
  *
  * @param {import('../core/wasm.js').InitInput} [source] override the binary's
  *   source (bytes, a `Response`, a `WebAssembly.Module`, 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.
- * @returns {Promise<void>} resolves when the sync surface is usable
+ *   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.
+ * @returns {Promise<import('./runtime.js').CoreSurface>} the core surface, once
+ *   its instance is live
  */
 export function init(source) {
 	if (coreInit) {
 		if (source !== undefined && source !== coreInitSource) {
-			throw quillmarkError(
-				'runtime::init_conflict',
-				'init(source): core is already initializing or initialized from a different source.',
-				'Pass a source on the first call only, or pass the same value every time.'
+			// A rejection, not a throw: this is the one failure on the
+			// promise-returning surface that could land on the caller's stack, where
+			// `init(BYTES).catch(…)` would not see it.
+			return Promise.reject(
+				quillmarkError(
+					'runtime::init_conflict',
+					'init(source): core is already initializing or initialized from a different source.',
+					'Pass a source on the first call only, or pass the same value every time.'
+				)
 			);
 		}
 		return coreInit;
 	}
 	coreInitSource = source;
 	// Assign before the first await so a synchronous second call sees the memo.
-	coreInit = instantiateCore(source).catch((err) => {
-		// Self-heal, as `#resolveBackend` does: one transient failure (a 404, an
-		// offline fetch) must not poison every later attempt.
-		coreInit = undefined;
-		coreInitSource = undefined;
-		throw err;
-	});
+	coreInit = instantiateCore(source).then(
+		() => CORE_SURFACE,
+		(err) => {
+			// Self-heal, as `#resolveBackend` does: one transient failure (a 404, an
+			// offline fetch) must not poison every later attempt.
+			coreInit = undefined;
+			coreInitSource = undefined;
+			throw err;
+		}
+	);
 	return coreInit;
 }
 

package/runtime/uninit.js

@@ -1,57 +0,0 @@
-// The pre-initialization sentinel.
-//
-// wasm-bindgen's `--target web` glue holds its instance exports in one
-// module-level binding (`let wasmModule, wasm;`) that every generated path
-// reads through: constructors, statics, methods, free functions. Until
-// instantiation assigns it, that binding is `undefined`, so a consumer who
-// skipped `await init()` gets `Cannot read properties of undefined (reading
-// 'quill_fromTree')` from inside generated code.
-//
-// `scripts/build-wasm.sh` (`guard_wasm_js`) patches the binding to start as
-// this sentinel, so the same access throws a `QuillmarkError` naming the cause
-// and the fix. The patch is three line edits per variant, shape-asserted before
-// it applies; the logic lives here rather than inside the awk program.
-//
-// It sits in the generated build, not in the runtime layer, because the
-// canonical invariant (`runtime.js` § "CANONICAL INVARIANT") requires the root
-// to re-export `Quill`/`Document` VERBATIM: no wrapper, subclass, or proxy may
-// stand between a consumer and those classes. Prototype patching preserves
-// identity but cannot cover a public constructor (`new Document(...)`) without
-// wrapping the class. The binding they all read through is the one place that
-// covers every path and touches no class.
-
-/**
- * A stand-in for a wasm build's exports that throws on use. Every property read
- * throws except the marker the patched init guards test, and `then`,
- * `constructor`, and symbols, which return `undefined`: an incidental `await`
- * or `util.inspect` reports nothing rather than throwing somewhere unrelated to
- * the cause.
- *
- * @param {string} message what a consumer sees when they reach a build early
- * @param {string} hint the fix, as a `Diagnostic.hint`
- * @returns {any} the sentinel
- */
-export function uninitSentinel(message, hint) {
-	return new Proxy(
-		{},
-		{
-			get(_target, prop) {
-				if (prop === UNINIT) return true;
-				if (prop === 'then' || prop === 'constructor' || typeof prop === 'symbol') {
-					return undefined;
-				}
-				const err = /** @type {any} */ (new Error(message));
-				err.diagnostics = [
-					{ severity: 'error', code: 'runtime::not_initialized', message, hint }
-				];
-				throw err;
-			}
-		}
-	);
-}
-
-/**
- * The marker the patched `if (wasm !== undefined)` guards read to tell a
- * sentinel from real instance exports, which never carry it.
- */
-export const UNINIT = '__quillmarkUninit';