@quillmark/wasm 0.88.0 → 0.90.0

package/core/wasm_bg.wasm.d.ts

@@ -0,0 +1,62 @@
+/* tslint:disable */
+/* eslint-disable */
+export const memory: WebAssembly.Memory;
+export const __wbg_document_free: (a: number, b: number) => void;
+export const __wbg_quill_free: (a: number, b: number) => void;
+export const document_blueprintInstruction: (a: number, b: number, c: number) => void;
+export const document_cardCount: (a: number) => number;
+export const document_cards: (a: number) => number;
+export const document_clone: (a: number) => number;
+export const document_currentSchemaVersion: (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;
+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_insertCard: (a: number, b: number, c: number, d: number) => void;
+export const document_main: (a: number) => number;
+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_pushCard: (a: number, b: number, c: 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) => number;
+export const document_removeCardExt: (a: number, b: number, c: number) => void;
+export const document_removeCardExtNamespace: (a: number, b: number, c: number, d: number, e: number) => void;
+export const document_removeCardField: (a: number, b: number, c: number, d: number, e: number) => void;
+export const document_removeExt: (a: number) => number;
+export const document_removeExtNamespace: (a: number, b: number, c: number) => number;
+export const document_removeField: (a: number, b: number, c: number, d: number) => void;
+export const document_replaceBody: (a: number, b: number, c: number) => void;
+export const document_schemaVersionOf: (a: number, b: number, c: number) => void;
+export const document_setCardExt: (a: number, b: number, c: number, d: number) => void;
+export const document_setCardExtNamespace: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+export const document_setCardKind: (a: number, b: number, c: number, d: number, e: number) => void;
+export const document_setExt: (a: number, b: number, c: number) => void;
+export const document_setExtNamespace: (a: number, b: number, c: number, d: number, e: number) => void;
+export const document_setField: (a: number, b: number, c: number, d: number, e: number) => void;
+export const document_setFill: (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_toJson: (a: number, b: number) => void;
+export const document_toMarkdown: (a: number, b: number) => void;
+export const document_tryFromJson: (a: number, b: number) => number;
+export const document_updateCardBody: (a: number, b: number, c: number, d: number, e: number) => void;
+export const document_updateCardField: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+export const document_warnings: (a: number) => number;
+export const init: () => void;
+export const quill_backendId: (a: number, b: number) => void;
+export const quill_blueprint: (a: number, b: number) => void;
+export const quill_fromTree: (a: number, b: number) => void;
+export const quill_metadata: (a: number) => number;
+export const quill_schema: (a: number) => number;
+export const quill_seedCard: (a: number, b: number, c: number) => number;
+export const quill_seedDocument: (a: number) => number;
+export const quill_seedMain: (a: number) => number;
+export const quill_toTree: (a: number) => number;
+export const quill_validate: (a: number, b: number, c: number) => 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;
+export const __wbindgen_export4: (a: number, b: number, c: number) => void;
+export const __wbindgen_add_to_stack_pointer: (a: number) => number;
+export const __wbindgen_start: () => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quillmark/wasm",
-  "version": "0.88.0",
+  "version": "0.90.0",
   "description": "WebAssembly bindings for quillmark",
   "type": "module",
   "license": "MIT OR Apache-2.0",
@@ -12,24 +12,24 @@
     "url": "git+https://github.com/quillmark-org/quillmark.git"
   },
   "files": [
-    "bundler/wasm_bg.wasm",
-    "bundler/wasm_bg.js",
-    "bundler/wasm_bg.wasm.d.ts",
-    "bundler/wasm.js",
-    "bundler/wasm.d.ts",
+    "core",
+    "backends",
+    "runtime",
     "CHANGELOG.md"
   ],
-  "main": "./bundler/wasm.js",
-  "module": "./bundler/wasm.js",
-  "types": "./bundler/wasm.d.ts",
+  "main": "./runtime/runtime.js",
+  "module": "./runtime/runtime.js",
+  "types": "./runtime/runtime.d.ts",
   "exports": {
     ".": {
-      "types": "./bundler/wasm.d.ts",
-      "import": "./bundler/wasm.js",
-      "default": "./bundler/wasm.js"
+      "types": "./runtime/runtime.d.ts",
+      "import": "./runtime/runtime.js",
+      "default": "./runtime/runtime.js"
     }
   },
   "sideEffects": [
-    "./bundler/wasm.js"
+    "./core/wasm.js",
+    "./backends/typst/wasm.js",
+    "./runtime/runtime.js"
   ]
 }

package/runtime/runtime.d.ts

@@ -0,0 +1,212 @@
+// @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.
+export { Quill, Document, init } from '../core/wasm.js';
+
+// Core-build types consumers read off `Quill`/`Document`.
+export type {
+	Card,
+	PayloadItem,
+	Diagnostic,
+	Location,
+	Severity,
+	QuillSchema,
+	QuillFieldSchema,
+	QuillCardSchema,
+	QuillCardBody,
+	QuillFieldUi,
+	QuillCardUi,
+	QuillMetadata
+} from '../core/wasm.js';
+
+// ── Error contract ──────────────────────────────────────────────────────────
+
+/**
+ * The error every fallible method in this package throws — parse
+ * (`Document.fromMarkdown`), document mutation, validation
+ * (`Quill.fromTree`, `quill.validate`), and rendering (`engine.render`,
+ * `engine.open`, `session.render`).
+ *
+ * This is a STRUCTURAL interface, not a class: the WASM layer throws a real
+ * `Error` and attaches `diagnostics` to it, so there is no constructor to
+ * `instanceof` against — narrow with {@link isQuillmarkError}. `diagnostics`
+ * is always non-empty; `message` is the first diagnostic's message (or an
+ * `"N error(s): …"` aggregate for multi-diagnostic failures), so iterate
+ * `diagnostics` for per-error detail. The shape is identical to
+ * `RenderResult.warnings` entries.
+ */
+export interface QuillmarkError extends Error {
+	diagnostics: Diagnostic[];
+}
+
+/**
+ * Narrow an unknown caught value to {@link QuillmarkError}. Structural
+ * (`Error` carrying a `diagnostics` array), so it works on errors from any
+ * build or WASM instance in the page — consistent with the package's
+ * duck-typed handling of handles.
+ */
+export declare function isQuillmarkError(e: unknown): e is QuillmarkError;
+
+// ── Canonical render-side types ─────────────────────────────────────────────
+// These are the BACKEND-NEUTRAL render contract of the plural-backend API. They
+// are defined HERE (not re-exported from one private backend) because no single
+// backend build owns the canonical API's types. Every backend build MUST satisfy
+// these shapes; that they match the Typst backend's generated declarations is
+// enforced by the type-level drift guard `crates/bindings/wasm/runtime.types.test-d.ts`
+// (run via `npm run typecheck`), so these and the generated
+// `pkg/backends/typst/wasm.d.ts` cannot silently diverge.
+
+import type { Quill, Document } from '../core/wasm.js';
+import type { Diagnostic } from '../core/wasm.js';
+
+/** Canonical contract every backend build must satisfy. One emitted output. */
+export interface Artifact {
+	format: OutputFormat;
+	bytes: Uint8Array;
+	mimeType: string;
+}
+
+/** Canonical contract every backend build must satisfy. Options for one render. */
+export interface RenderOptions {
+	format?: OutputFormat;
+	ppi?: number;
+	pages?: number[];
+	producer?: string;
+}
+
+/** Canonical contract every backend build must satisfy. Result of one render. */
+export interface RenderResult {
+	artifacts: Artifact[];
+	warnings: Diagnostic[];
+	outputFormat: OutputFormat;
+	renderTimeMs: number;
+}
+
+/** Canonical contract every backend build must satisfy. The emittable formats. */
+export type OutputFormat = 'pdf' | 'svg' | 'txt' | 'png';
+
+/**
+ * Canonical contract every backend build must satisfy. Page geometry in pt.
+ * @experimental Part of the iterative-session/canvas surface — see {@link RenderSession}.
+ */
+export interface PageSize {
+	widthPt: number;
+	heightPt: number;
+}
+
+/**
+ * Canonical contract every backend build must satisfy. Inputs to `paint`.
+ * @experimental Part of the iterative-session/canvas surface — see {@link RenderSession}.
+ */
+export interface PaintOptions {
+	layoutScale?: number;
+	densityScale?: number;
+}
+
+/**
+ * Canonical contract every backend build must satisfy. Output of `paint`.
+ * @experimental Part of the iterative-session/canvas surface — see {@link RenderSession}.
+ */
+export interface PaintResult {
+	layoutWidth: number;
+	layoutHeight: number;
+	pixelWidth: number;
+	pixelHeight: number;
+}
+
+/**
+ * A backend registry entry. `load` is the lazy thunk returning the dynamically-
+ * imported backend build module; `formats`/`canvas` are the REQUIRED static
+ * capability manifest. That manifest is what makes
+ * `Engine.supportedFormats`/`Engine.supportsCanvas` always FREE: they answer
+ * from it directly — no backend binary is loaded and no quill is cloned into
+ * backend memory. A malformed descriptor throws at `new Engine(...)`.
+ */
+export interface BackendDescriptor {
+	load: () => Promise<unknown>;
+	formats: OutputFormat[];
+	canvas: boolean;
+}
+
+export interface EngineOptions {
+	/**
+	 * Extra or overriding backend descriptors, merged over the built-ins. Keys are
+	 * backend ids (as declared by `Quill.yaml`'s `backend:` and reported by
+	 * `Quill.backendId`). Each value is a `BackendDescriptor` — `formats`/`canvas`
+	 * are required, so capability probes are ALWAYS free (no binary load, no quill
+	 * clone). Malformed entries throw at construction. The default registry maps
+	 * `"typst"` to the bundled Typst build.
+	 */
+	backends?: Record<string, BackendDescriptor>;
+}
+
+/**
+ * Render dispatcher over the canonical `Quill`/`Document`. Routes on
+ * `quill.backendId`, lazily loads that backend build, clones the quill and
+ * document into the backend's WASM memory on demand, renders, and frees the
+ * clones. The cross-memory crossing is invisible to callers.
+ */
+export declare class Engine {
+	constructor(options?: EngineOptions);
+
+	/** Render `doc` against `quill` in one shot. */
+	render(quill: Quill, doc: Document, options?: RenderOptions): Promise<RenderResult>;
+
+	/**
+	 * Open an iterative render session (canvas preview / per-page paint).
+	 * @experimental Ships ahead of its first production consumer (the designed
+	 * canvas live-preview path — see `prose/canon/PREVIEW.md`). The session/paint
+	 * surface may change in any 0.x release; `render()` is the stable path.
+	 */
+	open(quill: Quill, doc: Document): Promise<RenderSession>;
+
+	/**
+	 * Output formats `quill`'s backend can emit. An ALWAYS-free pre-render probe:
+	 * it answers from the descriptor's required `formats` manifest WITHOUT loading
+	 * the backend binary or cloning the quill. Async for API stability.
+	 */
+	supportedFormats(quill: Quill): Promise<OutputFormat[]>;
+
+	/**
+	 * Whether `quill`'s backend can paint sessions to a canvas. Same always-free
+	 * probe as `supportedFormats`: answered from the descriptor's required
+	 * `canvas` manifest, no binary load and no quill clone.
+	 * @experimental Probes the experimental session/canvas surface — see {@link RenderSession}.
+	 */
+	supportsCanvas(quill: Quill): Promise<boolean>;
+}
+
+/**
+ * Iterative render session over a compiled snapshot. `free()` when done.
+ * @experimental The whole session/canvas-paint surface (`Engine.open`,
+ * `RenderSession`, `PaintOptions`, `PaintResult`, `PageSize`) ships ahead of
+ * its first production consumer and may change shape in any 0.x release.
+ * The stable render path is `Engine.render`.
+ */
+export declare class RenderSession {
+	private constructor();
+	readonly pageCount: number;
+	readonly backendId: string;
+	readonly supportsCanvas: boolean;
+	readonly warnings: Diagnostic[];
+	render(options?: RenderOptions): RenderResult;
+	pageSize(page: number): PageSize;
+	paint(
+		ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
+		page: number,
+		options?: PaintOptions
+	): PaintResult;
+	free(): void;
+}