@quillmark/wasm 0.67.0 → 0.69.0

package/README.md

@@ -79,53 +79,89 @@ O(1) getter for the number of composable cards (excluding the main card).
 Use this to validate indices before calling card mutators (`removeCard`,
 `updateCardField`, etc.) without allocating the full `cards` array.
 
+### `quill.form(doc)`
+
+Returns `{ main, cards, diagnostics }` — a schema-aware snapshot of `doc`
+without invoking the backend. `diagnostics` contains validation errors and
+warnings; an empty array means the document is valid. Useful for validating
+content without rendering:
+
+```ts
+const form = quill.form(Document.fromMarkdown(markdown));
+const errors = form.diagnostics.filter(d => d.severity === "error");
+```
+
+### `quill.render(parsed, opts?)` vs. `quill.open(parsed)`
+
+Use **`Quill.render`** for one-shot exports (PDF/SVG/PNG) — compiles, emits
+artifacts, done. Use **`RenderSession`** (returned by `Quill.open`) for
+reactive previews where you'll paint or re-emit pages multiple times: the
+session retains the compiled snapshot so subsequent `paint` / `render`
+calls skip recompilation. Don't open a session per export.
+
 ### `quill.render(parsed, opts?)`
 Render with a pre-parsed `Document`.
 
 ### `quill.open(parsed)` + `session.render(opts?)`
 Open once, render all or selected pages (`opts.pages`).
 
-The session also exposes `pageCount`, `backendId`, `warnings` (snapshot of
-session-level diagnostics attached at `open` time), `pageSize(page)`, and
-`paint(ctx, page, scale)` for canvas previews. See below.
+The session also exposes `pageCount`, `backendId`, `supportsCanvas`,
+`warnings` (snapshot of session-level diagnostics attached at `open` time),
+`pageSize(page)`, and `paint(ctx, page, opts?)` for canvas previews. See
+below.
+
+A document that compiles to zero pages still produces a valid session
+(`pageCount === 0`); `paint(ctx, 0)` and `pageSize(0)` then throw
+`page index 0 out of range (pageCount=0)`. Branch on `pageCount === 0` to
+render a "no pages to preview" UI without relying on the throw.
 
 ### Canvas Preview (Typst only)
 
-`session.paint(ctx, page, scale)` rasterizes a page directly into a
-`CanvasRenderingContext2D`, skipping PNG/SVG byte round-trips. Pair with
-`session.pageSize(page)` to size the canvas:
+`session.paint(ctx, page, opts?)` rasterizes a page directly into a
+`CanvasRenderingContext2D` (main thread) or
+`OffscreenCanvasRenderingContext2D` (Worker), skipping PNG/SVG byte
+round-trips.
+
+The painter owns `canvas.width` / `canvas.height` — it sizes the backing
+store itself. Consumers own `canvas.style.*` (or the layout system that
+sets them) and read `layoutWidth` / `layoutHeight` from the returned
+`PaintResult`.
 
 ```ts
-const dpr = window.devicePixelRatio || 1;
-const userZoom = 1;                              // your zoom UI
-const scale = dpr * userZoom;                    // multiplier on 72 ppi
-
-const { widthPt, heightPt } = session.pageSize(0);
-// Reassigning canvas.width/height clears the backing store, which is what
-// you want between pages. If you reuse the same canvas at the same size
-// (e.g. repaint after a zoom that didn't change scale), call
-// ctx.clearRect(0, 0, canvas.width, canvas.height) before paint instead.
-canvas.width  = Math.round(widthPt  * scale);    // device px
-canvas.height = Math.round(heightPt * scale);
-canvas.style.width  = `${widthPt  * userZoom}px`;
-canvas.style.height = `${heightPt * userZoom}px`;
-
-session.paint(canvas.getContext("2d"), 0, scale);
+const result = session.paint(canvas.getContext("2d"), 0, {
+  layoutScale: 1,                            // layout px per Typst pt
+  densityScale: window.devicePixelRatio,     // backing-store density
+});
+
+canvas.style.width  = `${result.layoutWidth}px`;
+canvas.style.height = `${result.layoutHeight}px`;
 ```
 
-- `scale` is a multiplier on Typst's natural 72 ppi (1 pt → 1 device
-  pixel at `scale = 1`). Always include `devicePixelRatio` for crisp
-  output.
+- `layoutScale` (default 1) sets the canvas's display-box size:
+  `layoutWidth = widthPt * layoutScale`. For on-screen canvases this is
+  CSS pixels per Typst point. Defaults to 1 (one CSS pixel per pt).
+- `densityScale` (default 1) is the backing-store density multiplier.
+  Fold `window.devicePixelRatio`, in-app zoom, and `visualViewport.scale`
+  (pinch-zoom) into a single value here. Pass `devicePixelRatio` for
+  crisp output on high-DPI displays.
+- The effective rasterization scale is `layoutScale * densityScale`. If
+  that would exceed the safe maximum (16384 px per side), `densityScale`
+  is clamped proportionally; compare `result.pixelWidth` against
+  `Math.round(result.layoutWidth * densityScale)` to detect.
+- `paint` is always a full repaint — setting the backing-store width /
+  height clears it. No `clearRect` required.
 - `pageCount` and `pageSize(page)` are stable for the session's
   lifetime (immutable snapshot) — cache them.
-- Setting `canvas.width` / `canvas.height` clears the backing store; if
-  you reuse a canvas without resizing, call `clearRect` before `paint`.
-- Currently main-thread only: `paint` accepts `CanvasRenderingContext2D`,
-  not `OffscreenCanvasRenderingContext2D`. Worker support is on the
-  follow-up list.
-- Backend support: Typst only. Calling `paint` on a session opened by
-  any other backend throws an error that includes the resolved
-  `backendId`.
+- Worker support: pass an `OffscreenCanvasRenderingContext2D` and the
+  same call signature works. `layoutWidth` / `layoutHeight` are
+  informational in that mode (no CSS layout box); fold everything into
+  `densityScale`. Loading the WASM module inside a Worker is the host's
+  responsibility.
+- Backend support: gated by `supportsCanvas`. Probe upfront with
+  `quill.supportsCanvas` (or `session.supportsCanvas`) before mounting a
+  canvas-based UI; the throw on `paint` / `pageSize` remains the
+  enforcement contract and includes the resolved `backendId` for
+  debugging.
 
 ### Errors
 
@@ -160,6 +196,22 @@ without manual `.free()` discipline. `.free()` is still emitted as an eager
 teardown hook for callers that want deterministic release. Requires
 Node 14.6+ / current evergreen browsers (all supported targets).
 
+For environments where `using` (the [explicit resource management][erm]
+proposal) hasn't landed, use an explicit `try` / `finally`:
+
+```ts
+const session = quill.open(doc);
+try {
+  for (let p = 0; p < session.pageCount; p++) {
+    session.paint(ctx, p);
+  }
+} finally {
+  session.free();
+}
+```
+
+[erm]: https://github.com/tc39/proposal-explicit-resource-management
+
 ## Notes
 
 - Parsed markdown requires top-level `QUILL` in frontmatter. Empty input

package/bundler/wasm.d.ts

@@ -17,14 +17,179 @@ export interface CardInput {
 /**
  * Page dimensions in Typst points (1 pt = 1/72 inch).
  *
- * Returned by `RenderSession.pageSize`. Use these to size a canvas backing
- * store (`widthPt * scale × heightPt * scale`) before calling `paint`.
+ * Report-only: the painter sizes the canvas itself based on
+ * `PaintOptions`. `pageSize` is exposed for callers that need page
+ * geometry up-front (e.g. to lay out a scrollable list of canvases
+ * before any pixels are rendered).
  */
 export interface PageSize {
     widthPt: number;
     heightPt: number;
 }
 
+/**
+ * Inputs to `RenderSession.paint`. Both fields are optional and default
+ * to `1`.
+ *
+ * - `layoutScale` — layout-space pixels per Typst point. For on-screen
+ *   canvases this is CSS pixels per pt; the page's layout-pixel size is
+ *   `widthPt * layoutScale × heightPt * layoutScale`. The painter
+ *   surfaces these dimensions as `layoutWidth` / `layoutHeight` so
+ *   consumers can drive `canvas.style.*` (or any layout system).
+ * - `densityScale` — backing-store density multiplier. Fold
+ *   `window.devicePixelRatio`, in-app zoom, and `visualViewport.scale`
+ *   (pinch-zoom) into a single value here. Defaults to `1`, which
+ *   produces a non-retina backing store — pass `window.devicePixelRatio`
+ *   for crisp output on high-DPI displays.
+ *
+ * The effective rasterization scale is `layoutScale * densityScale`.
+ * Both must be finite and `> 0`. For `OffscreenCanvasRenderingContext2D`
+ * the two collapse to a single scalar; folding everything into
+ * `densityScale` is the simplest convention.
+ */
+export interface PaintOptions {
+    layoutScale?: number;
+    densityScale?: number;
+}
+
+/**
+ * Returned by `RenderSession.paint`.
+ *
+ * - `layoutWidth` / `layoutHeight` — layout-pixel dimensions of the
+ *   canvas's display box. For on-screen canvases this is CSS pixels:
+ *   set `canvas.style.width = layoutWidth + "px"` and
+ *   `canvas.style.height = layoutHeight + "px"` (or feed these into
+ *   your layout system). Independent of `densityScale`.
+ * - `pixelWidth` / `pixelHeight` — integer backing-store pixel
+ *   dimensions the painter wrote to `canvas.width` / `canvas.height`.
+ *   Equal to `round(layoutWidth * densityScale)` ×
+ *   `round(layoutHeight * densityScale)` *unless* the requested backing
+ *   exceeded the painter's safe maximum (16384 px per side), in which
+ *   case `densityScale` was clamped to fit. Detect clamping via
+ *   `pixelWidth < round(layoutWidth * densityScale)`.
+ *
+ * The painter owns `canvas.width` / `canvas.height`; consumers must not
+ * write to them. The painter does **not** touch `canvas.style.*`;
+ * consumers own layout.
+ *
+ * For `OffscreenCanvasRenderingContext2D` (Worker rasterization, no
+ * DOM), `layoutWidth` / `layoutHeight` are informational — there's no
+ * CSS layout box to apply them to.
+ */
+export interface PaintResult {
+    layoutWidth: number;
+    layoutHeight: number;
+    pixelWidth: number;
+    pixelHeight: number;
+}
+
+
+
+/** UI layout hints for a single field. */
+export interface QuillFieldUi {
+    group?: string;
+    order?: number;
+    compact?: boolean;
+    multiline?: boolean;
+}
+
+/** UI layout hints for a card (main or named card type). */
+export interface QuillCardUi {
+    hide_body?: boolean;
+    default_title?: string;
+}
+
+/** Schema entry for a single field declared in a quill's `Quill.yaml`. */
+export interface QuillFieldSchema {
+    type: "string" | "number" | "integer" | "boolean" | "array" | "object" | "date" | "datetime" | "markdown";
+    title?: string;
+    description?: string;
+    default?: unknown;
+    examples?: unknown;
+    required?: boolean;
+    enum?: string[];
+    ui?: QuillFieldUi;
+    properties?: Record<string, QuillFieldSchema>;
+    items?: QuillFieldSchema;
+}
+
+/** Schema entry for the main card or a named card type. */
+export interface QuillCardSchema {
+    title?: string;
+    description?: string;
+    fields: Record<string, QuillFieldSchema>;
+    ui?: QuillCardUi;
+}
+
+/**
+ * Public schema contract returned as `QuillMetadata.schema`.
+ *
+ * Identical to `QuillConfig::public_schema()` on the Rust side.
+ */
+export interface QuillSchema {
+    name: string;
+    main: QuillCardSchema;
+    /** Present only when the quill declares at least one named card type. */
+    card_types?: Record<string, QuillCardSchema>;
+    /** The quill's bundled example document, if declared. */
+    example?: string;
+}
+
+/**
+ * Read-only snapshot of the loaded quill's engine info and declared schema.
+ * Returned by `Quill.metadata`.
+ *
+ * Well-known keys are strongly typed; any additional keys declared under
+ * `quill:` in `Quill.yaml` appear as `unknown`.
+ */
+export interface QuillMetadata {
+    schema: QuillSchema;
+    backend: string;
+    version: string;
+    author: string;
+    description: string;
+    supportedFormats: OutputFormat[];
+    [key: string]: unknown;
+}
+
+/** Source of a field's effective value in a form view. */
+export type FormFieldSource = "document" | "default" | "missing";
+
+/**
+ * A single field's view within a `FormCard`.
+ *
+ * - `value` — the document-supplied value (`null` when absent).
+ * - `default` — the schema default (`null` when no default is declared).
+ * - `source` — where the effective value comes from.
+ */
+export interface FormFieldValue {
+    value: unknown;
+    default: unknown;
+    source: FormFieldSource;
+}
+
+/**
+ * A card viewed through its schema, as returned by `Quill.form`,
+ * `Quill.blankMain`, and `Quill.blankCard`.
+ */
+export interface FormCard {
+    schema: QuillCardSchema;
+    values: Record<string, FormFieldValue>;
+}
+
+/**
+ * Schema-aware form view of a document, returned by `Quill.form`.
+ *
+ * - `main` — the main card viewed through the quill's main schema.
+ * - `cards` — composable card blocks, in document order (unknown tags excluded).
+ * - `diagnostics` — diagnostics from unknown card tags and validation.
+ */
+export interface Form {
+    main: FormCard;
+    cards: FormCard[];
+    diagnostics: Diagnostic[];
+}
+
 
 export interface Artifact {
     format: OutputFormat;
@@ -299,7 +464,7 @@ export class Quill {
      *
      * [`Form::cards`]: quillmark::form::Form::cards
      */
-    blankCard(card_type: string): any;
+    blankCard(card_type: string): FormCard | null;
     /**
      * A blank form for the main card — no document values supplied.
      *
@@ -309,7 +474,7 @@ export class Quill {
      *
      * [`Form::main`]: quillmark::form::Form::main
      */
-    blankMain(): any;
+    blankMain(): FormCard;
     /**
      * The schema-aware form view of `doc`.
      *
@@ -329,7 +494,7 @@ export class Quill {
      *
      * [`Form`]: quillmark::form::Form
      */
-    form(doc: Document): any;
+    form(doc: Document): Form;
     /**
      * Open an iterative render session for page-selective rendering.
      */
@@ -367,7 +532,16 @@ export class Quill {
      * Equivalent by value for the lifetime of the handle; the quill is
      * immutable once constructed.
      */
-    readonly metadata: any;
+    readonly metadata: QuillMetadata;
+    /**
+     * Whether this quill's backend supports canvas preview.
+     *
+     * `true` iff `RenderSession.paint` and `RenderSession.pageSize` will
+     * succeed for sessions opened by this quill. Use this as a precondition
+     * probe before mounting a canvas-based preview UI; the throw on `paint`
+     * remains the enforcement contract.
+     */
+    readonly supportsCanvas: boolean;
 }
 
 /**
@@ -391,6 +565,21 @@ export class Quillmark {
     quill(tree: Map<string, Uint8Array>): Quill;
 }
 
+/**
+ * An iterative render handle backed by an immutable compiled snapshot.
+ *
+ * Created via [`Quill::open`]. Holds the compiled output so that
+ * [`RenderSession::render`], [`RenderSession::paint`], and
+ * [`RenderSession::page_size`] can be called repeatedly without
+ * recompiling.
+ *
+ * **Empty documents.** A document that compiles to zero pages still
+ * produces a valid session (`pageCount === 0`). Iterating
+ * `0..pageCount` is then a no-op; calling `paint(ctx, 0)` or
+ * `pageSize(0)` throws `"... page index 0 out of range
+ * (pageCount=0)"`. Hosts that surface "no pages to preview" UI should
+ * branch on `pageCount === 0` rather than on a thrown error.
+ */
 export class RenderSession {
     private constructor();
     free(): void;
@@ -398,6 +587,11 @@ export class RenderSession {
     /**
      * Page dimensions in Typst points (1 pt = 1/72 inch).
      *
+     * Report-only: the painter sizes the canvas itself based on
+     * `PaintOptions`. Exposed for consumers that need page geometry
+     * up-front (e.g. to lay out a scrollable list of canvases before
+     * any pixels are rendered).
+     *
      * Stable for a given `page` across the session's lifetime — the
      * compiled document is an immutable snapshot, so callers can cache
      * results.
@@ -409,33 +603,51 @@ export class RenderSession {
     /**
      * Paint `page` into a 2D canvas context.
      *
-     * `scale` multiplies Typst's natural 72 ppi (1 pt → 1 device pixel at
-     * `scale = 1`). Typical usage:
-     * `scale = (window.devicePixelRatio || 1) * userZoom`.
-     *
-     * The caller must size `ctx.canvas` so that
-     * `canvas.width === round(widthPt * scale)` and `canvas.height ===
-     * round(heightPt * scale)` *before* calling `paint`. Setting
-     * `canvas.width` / `canvas.height` clears the backing store, which is
-     * the recommended way to handle page-to-page transitions; if you
-     * reuse a canvas without resizing, call
-     * `ctx.clearRect(0, 0, canvas.width, canvas.height)` first to avoid
-     * stale pixels showing through transparent regions.
-     *
-     * `paint` writes into the backing store at origin `(0, 0)` and does
-     * not clear outside the rendered region.
-     *
-     * Throws if the backend does not support canvas preview (the message
-     * includes the resolved `backendId` for debugging), or if `page` is
-     * out of range.
-     */
-    paint(ctx: CanvasRenderingContext2D, page: number, scale: number): void;
+     * Accepts either a `CanvasRenderingContext2D` (main thread) or an
+     * `OffscreenCanvasRenderingContext2D` (Worker / off-DOM rasterization).
+     * Both dispatch to the same Rust rasterizer; the dispatch happens at
+     * the JS boundary so neither context type is privileged.
+     *
+     * The painter owns `canvas.width` / `canvas.height` and writes them
+     * itself; consumers must not. The painter does not touch
+     * `canvas.style.*` — that's layout, owned by the consumer (see
+     * `PaintResult.layoutWidth` / `layoutHeight`).
+     *
+     * `opts.layoutScale` (default 1.0) is layout-space pixels per Typst
+     * point and determines the canvas's display-box size. `opts.densityScale`
+     * (default 1.0) is the rasterization density multiplier the consumer
+     * folds `window.devicePixelRatio`, in-app zoom, and
+     * `visualViewport.scale` (pinch-zoom) into. The effective
+     * rasterization scale is `layoutScale * densityScale`.
+     *
+     * If `layoutScale * densityScale` would exceed the safe backing-store
+     * maximum (16384 px per side), `densityScale` is clamped
+     * proportionally so the largest dimension fits. The actual
+     * backing-store dimensions are reported in the returned
+     * `PaintResult` — compare against
+     * `round(layoutWidth * densityScale)` to detect clamping.
+     *
+     * Each call resets the backing store (`paint` is always a full
+     * repaint). Consumers do not need to call `clearRect`.
+     *
+     * Throws when:
+     * - the backend does not support canvas preview (message includes the
+     *   resolved `backendId`),
+     * - `page` is out of range,
+     * - `ctx` is neither `CanvasRenderingContext2D` nor
+     *   `OffscreenCanvasRenderingContext2D`,
+     * - `opts.layoutScale` or `opts.densityScale` is non-finite or `<= 0`.
+     */
+    paint(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, page: number, opts: PaintOptions | undefined): PaintResult;
     /**
      * Render all or selected pages from this session.
      */
     render(opts?: RenderOptions | null): RenderResult;
     /**
      * The backend that produced this session (e.g. `"typst"`).
+     *
+     * Equal to the `backendId` of the [`Quill`] that opened this session
+     * (sessions inherit their quill's backend), so checking either is fine.
      */
     readonly backendId: string;
     /**
@@ -445,6 +657,14 @@ export class RenderSession {
      * document is an immutable snapshot.
      */
     readonly pageCount: number;
+    /**
+     * Whether this session's backend supports canvas preview.
+     *
+     * `true` iff [`paint`](Self::paint) and [`page_size`](Self::page_size)
+     * will succeed. Equal to `Quill.supportsCanvas` for the quill that
+     * opened this session.
+     */
+    readonly supportsCanvas: boolean;
     /**
      * Session-level warnings attached at `quill.open(...)` time.
      *