@quillmark/wasm 0.101.0 → 0.103.0

package/core/wasm_bg.wasm.d.ts

@@ -11,11 +11,12 @@ export const document__readerGetContent: (a: number, b: number, c: number, d: nu
 export const document__reviseField: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
 export const document_applyChange: (a: number, b: number, c: number, d: number) => void;
 export const document_blueprintInstruction: (a: number, b: number, c: number) => void;
+export const document_bodyMarkdown: (a: number, b: number, c: number) => void;
 export const document_card: (a: number, b: number, c: number) => void;
 export const document_cardCount: (a: number) => number;
 export const document_cards: (a: number, b: number) => void;
 export const document_clone: (a: number) => number;
-export const document_currentSchemaVersion: (a: number) => void;
+export const document_currentStorageVersion: (a: number) => void;
 export const document_equals: (a: number, b: number) => number;
 export const document_formatDiagnostic: (a: number, b: number) => void;
 export const document_formatRules: (a: number) => void;
@@ -23,34 +24,33 @@ export const document_fromJson: (a: number, b: number, c: number) => void;
 export const document_fromMarkdown: (a: number, b: number, c: number) => void;
 export const document_getExt: (a: number, b: number, c: number) => void;
 export const document_getExtNamespace: (a: number, b: number, c: number, d: number, e: number) => void;
-export const document_getMarkdown: (a: number, b: number, c: number) => void;
 export const document_getStored: (a: number, b: number, c: number) => void;
 export const document_insertCard: (a: number, b: number, c: number, d: number) => void;
-export const document_install: (a: number, b: number, c: number, d: number) => void;
 export const document_isFill: (a: number, b: number, c: number) => void;
 export const document_loadJson: (a: number, b: number, c: number, d: number) => void;
 export const document_main: (a: number, b: number) => void;
 export const document_makeCard: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
 export const document_moveCard: (a: number, b: number, c: number, d: number) => void;
 export const document_new: (a: number, b: number, c: number) => void;
+export const document_overwrite: (a: number, b: number, c: number, d: number) => void;
 export const document_quillRef: (a: number, b: number) => void;
 export const document_quillRefHint: (a: number) => void;
 export const document_removeCard: (a: number, b: number, c: number) => void;
 export const document_removeExt: (a: number, b: number, c: number) => void;
 export const document_removeExtNamespace: (a: number, b: number, c: number, d: number, e: number) => void;
 export const document_removeField: (a: number, b: number, c: number) => void;
-export const document_removeSeedNamespace: (a: number, b: number, c: number, d: number) => void;
+export const document_removeSeedOverlay: (a: number, b: number, c: number, d: number) => void;
 export const document_revise: (a: number, b: number, c: number, d: number, e: number) => void;
-export const document_schemaVersionOf: (a: number, b: number, c: number) => void;
 export const document_seedOverlay: (a: number, b: number, c: number, d: number) => void;
 export const document_setCardKind: (a: number, b: number, c: number, d: number, e: number) => void;
 export const document_setQuillRef: (a: number, b: number, c: number, d: number) => void;
+export const document_storageVersionOf: (a: number, b: number, c: number) => void;
 export const document_storeExt: (a: number, b: number, c: number, d: number) => void;
 export const document_storeExtNamespace: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
 export const document_storeField: (a: number, b: number, c: number, d: number) => void;
 export const document_storeFields: (a: number, b: number, c: number, d: number) => void;
 export const document_storeFill: (a: number, b: number, c: number, d: number) => void;
-export const document_storeSeedNamespace: (a: number, b: number, c: number, d: number, e: number) => void;
+export const document_storeSeedOverlay: (a: number, b: number, c: number, d: number, e: number) => void;
 export const document_toJson: (a: number, b: number) => void;
 export const document_toMarkdown: (a: number, b: number) => void;
 export const document_tryFromJson: (a: number, b: number) => number;
@@ -58,7 +58,6 @@ export const document_warnings: (a: number, b: number) => void;
 export const exportMarkdown: (a: number, b: number) => void;
 export const formatDocPath: (a: number, b: number) => void;
 export const importMarkdown: (a: number, b: number, c: number) => void;
-export const init: () => void;
 export const mapPos: (a: number, b: number, c: number, d: number) => void;
 export const parseDocPath: (a: number, b: number, c: number) => void;
 export const quill_backendId: (a: number, b: number) => void;
@@ -75,6 +74,7 @@ export const quill_seedMain: (a: number, b: number) => void;
 export const quill_toTree: (a: number) => number;
 export const quill_validate: (a: number, b: number, c: number) => void;
 export const rebase: (a: number, b: number, c: number, d: number) => void;
+export const start: () => void;
 export const __wbindgen_export: (a: number, b: number) => number;
 export const __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
 export const __wbindgen_export3: (a: number) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quillmark/wasm",
-  "version": "0.101.0",
+  "version": "0.103.0",
   "description": "WebAssembly bindings for Quillmark, a schema-driven document engine",
   "type": "module",
   "license": "Apache-2.0",
@@ -27,10 +27,13 @@
       "default": "./runtime/runtime.js"
     }
   },
+  "imports": {
+    "#quillmark-env": {
+      "node": "./runtime/env-node.js",
+      "default": "./runtime/env-web.js"
+    }
+  },
   "sideEffects": [
-    "./core/wasm.js",
-    "./backends/typst/wasm.js",
-    "./backends/pdfform/wasm.js",
     "./runtime/runtime.js"
   ]
 }

package/runtime/env-node.js

@@ -0,0 +1,20 @@
+// The Node half of the `#quillmark-env` seam (package.json `imports`). See
+// env-web.js for why the seam is resolution-time rather than a runtime branch.
+//
+// Node's `fetch` rejects `file:` URLs, so the default source (a `file:` URL
+// pointing at the binary beside this package) is read off disk into bytes.
+// Everything else (caller-supplied bytes, a `Response`, a `WebAssembly.Module`,
+// an `http:` URL) passes through to the generated glue untouched.
+
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * @param {unknown} source
+ * @returns {Promise<unknown> | unknown} bytes for a `file:` URL, else `source`
+ */
+export function toModuleSource(source) {
+	return source instanceof URL && source.protocol === 'file:'
+		? readFile(fileURLToPath(source))
+		: source;
+}

package/runtime/env-web.js

@@ -0,0 +1,19 @@
+// The browser half of the `#quillmark-env` seam (package.json `imports`): the
+// wasm byte source, resolved per environment at module resolution rather than
+// by sniffing globals at runtime.
+//
+// A pass-through here. wasm-bindgen's `--target web` glue accepts a URL and
+// fetches it itself (`WebAssembly.instantiateStreaming`), the streaming path.
+//
+// The seam exists for the Node half, which cannot, and `node:fs` must never
+// reach a browser graph. Static resolution keeps it out: no `typeof process`
+// branch for a bundler to trip over, no dynamic `import('node:fs')` to warn
+// about.
+
+/**
+ * @param {unknown} source
+ * @returns {unknown} `source` unchanged
+ */
+export function toModuleSource(source) {
+	return source;
+}

package/runtime/runtime.d.ts

@@ -1,29 +1,93 @@
 // @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, init } from '../core/wasm.js';
-// 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';
+
+// 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';
+
+/**
+ * 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.
+ *
+ * `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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * @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 rejects with `runtime::init_conflict` rather than silently
+ *   ignoring it. Passing the same value again is fine.
+ */
+export declare function init(source?: InitInput): Promise<CoreSurface>;
 
 import type { CardAddr } from '../core/wasm.js';
 
@@ -55,7 +119,7 @@ export type {
 } from '../core/wasm.js';
 
 // Content edit vocabulary: the op-grained content model `Document`'s methods
-// speak (`applyChange(addr, bundle)`, `install(addr, rt)`, `revise(…) => Delta`).
+// speak (`applyChange(addr, bundle)`, `overwrite(addr, rt)`, `revise(…) => Delta`).
 // Declared in the core build; re-exported here so the single public entry point
 // names every type its own re-exported surface already references: `Card.body`
 // is a `Content`, `PayloadItem.nestedFills` a `PathStep[][]`, `CardInput.body` a
@@ -411,7 +475,7 @@ export interface PaintResult {
 
 /**
  * Canonical contract every backend build must satisfy. Output of
- * {@link LiveSession.apply}: `dirtyPages` lists the pages whose rendered
+ * {@link LiveSession.update}: `dirtyPages` lists the pages whose rendered
  * content differs from the previous compile, including added pages; removed
  * pages are implied by `pageCount`. Repaint `dirty ∩ visible`.
  */
@@ -463,7 +527,7 @@ export declare class Engine {
 	render(quill: Quill, doc: Document, options?: RenderOptions): Promise<RenderResult>;
 
 	/**
-	 * Open a live render session (canvas preview / per-page paint / `apply`).
+	 * Open a live render session (canvas preview / per-page paint / `update`).
 	 * The `quill` and `doc` handles are read synchronously before the first
 	 * await, so the caller may `free()` them as soon as this call returns; the
 	 * caller owns the returned session and must `.free()` it.
@@ -524,10 +588,10 @@ export declare class LiveSession {
 	 * Recompile the session against `doc`: the edit verb of a live preview.
 	 * Transactional: on throw every read (`render`, `paint`, `pageSize`,
 	 * `regions`) keeps serving the last-good compile, and the session recovers
-	 * on the next successful `apply`. On success reads serve the new compile;
+	 * on the next successful `update`. On success reads serve the new compile;
 	 * repaint `dirtyPages ∩ visible`.
 	 */
-	apply(doc: Document): ChangeSet;
+	update(doc: Document): ChangeSet;
 	render(options?: RenderOptions): RenderResult;
 	/**
 	 * Schema-field geometry for this compiled session, keyed on the canonical
@@ -642,7 +706,7 @@ declare module '../core/wasm.js' {
 /**
  * A `Document` bound to its `Quill` for typed writes: the schema-bound writer,
  * constructed via {@link Quill.writer}. Speaks names, values, and markdown. Bare
- * `set` / `setAll` / `setBody` / `reviseField` / `addCard` / `card(i).set`
+ * `set` / `setAll` / `reviseBody` / `reviseField` / `addCard` / `card(i).set`
  * instead of threading the `quill` handle through the underscored ABI. Holds both
  * handles by reference and owns neither: nothing to `free()`.
  *
@@ -669,11 +733,12 @@ export declare class DocumentWriter {
 	 */
 	setAll(fields: Record<string, unknown>): void;
 	/**
-	 * Set the main body from markdown (edit semantics: anchors rebase), discarding
-	 * the delta, the receipt-free body write. Use `doc.revise({}, md)` for the
-	 * `Delta` receipt.
+	 * Revise the main body from markdown (edit semantics: anchors rebase),
+	 * returning the text `Delta`. The content lane's `revise` reached through the
+	 * writer: a body carries no field schema to type against, so the receipt is
+	 * the content lane's.
 	 */
-	setBody(markdown: string): void;
+	reviseBody(markdown: string): Delta;
 	/**
 	 * Revise the content main-card field `name` from authored text: typed *and*
 	 * anchor-preserving. Surviving anchors rebase, then the diffed result is
@@ -725,8 +790,8 @@ export declare class CardWriter {
 	readonly kind: string;
 	set(name: string, value: unknown): void;
 	setAll(fields: Record<string, unknown>): void;
-	/** Set this card's body from markdown (edit semantics), discarding the delta. */
-	setBody(markdown: string): void;
+	/** Revise this card's body from markdown (edit semantics), returning the text `Delta`. */
+	reviseBody(markdown: string): Delta;
 	/**
 	 * Revise the content field `name` on this card from authored text: typed *and*
 	 * anchor-preserving; the card twin of {@link DocumentWriter.reviseField},
@@ -747,12 +812,12 @@ export declare class CardWriter {
  * The schema authority is the point: unlike the quill-free transport `Document.getStored`,
  * a name the schema does not declare throws `UnknownField` (a typo) rather than
  * reading back `undefined`, and a content field holding a value that does not
- * decode throws `FieldRichtextDecode`. A field's markdown lives here, not on the
- * body-only `Document.getMarkdown`. The body read stays quill-free (a body's type
+ * decode throws `FieldDecode`. A field's markdown lives here, not on the
+ * body-only `Document.bodyMarkdown`. The body read stays quill-free (a body's type
  * is a format fact) and never throws.
  *
  * `getContent` is the same read at the other end of the codec, returning the
- * corpus rather than the projection. It binds the quill for the same reason
+ * `Content` rather than the projection. It binds the quill for the same reason
  * `get` does: a `richtext` string is markdown and a `plaintext` string is
  * literal text, so the same stored bytes decode two ways and only the declared
  * type says which.
@@ -766,23 +831,23 @@ export declare class DocumentReader {
 	 * to markdown, every other type verbatim. A bare string is `Addr` shorthand for
 	 * `{ field }`; an absent `addr.field` reads the body markdown. `undefined` for
 	 * an absent field; throws `UnknownField` for a name the schema does not declare,
-	 * `FieldRichtextDecode` for a richtext field holding an undecodable value, and
+	 * `FieldDecode` for a richtext field holding an undecodable value, and
 	 * `IndexOutOfRange` for a bad `addr.card`.
 	 */
 	get(addr: Addr | string): unknown;
 	/**
-	 * Read the content field at `addr` as its canonical `Content` corpus: the
-	 * corpus twin of {@link get}, which projects. Decodes through the codec the
+	 * Read the content field at `addr` as its canonical `Content`: the
+	 * `Content` twin of {@link get}, which projects. Decodes through the codec the
 	 * declared type names (`richtext` as markdown, `plaintext` as literal text),
-	 * so a committed field and a parsed one read back the same corpus and the
+	 * so a committed field and a parsed one read back the same `Content` and the
 	 * storage form stops being the caller's business. An absent `addr.field`
-	 * reads the body corpus. `undefined` for an absent field; throws
+	 * reads the body `Content`. `undefined` for an absent field; throws
 	 * `UnknownField`, `FieldNotContent` for a declared type that is not a content
-	 * leaf, `FieldRichtextDecode` for an undecodable value, and `IndexOutOfRange`.
+	 * leaf, `FieldDecode` for an undecodable value, and `IndexOutOfRange`.
 	 */
 	getContent(addr: Addr | string): Content | undefined;
 	/** The main body's markdown: the quill-free body read. Equals `get({})`. */
-	getBody(): string;
+	bodyMarkdown(): string;
 	/**
 	 * A {@link CardReader} for the composable card at `index`. Index validity is
 	 * checked lazily at read time, so an out-of-range index does not throw here.
@@ -815,9 +880,9 @@ export declare class CardReader {
 	get(name: string): unknown;
 	/**
 	 * Read the content field `name` on this card as its canonical `Content`
-	 * corpus: the card twin of {@link DocumentReader.getContent}.
+	 * `Content`: the card twin of {@link DocumentReader.getContent}.
 	 */
 	getContent(name: string): Content | undefined;
-	/** This card's body markdown: the card twin of {@link DocumentReader.getBody}. */
-	getBody(): string;
+	/** This card's body markdown: the card twin of {@link DocumentReader.bodyMarkdown}. */
+	bodyMarkdown(): string;
 }