@quillmark/wasm 0.92.1 → 0.94.0

package/backends/pdfform/wasm.d.ts

@@ -0,0 +1,1099 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * A path to a value nested inside a field `value`: `string` keys and
+ * `number` array indices, e.g. `["addr", "street"]` or `["recipients", 0, "name"]`.
+ */
+export type PathStep = string | number;
+
+/** A field or comment entry in a `Card.payloadItems` list. */
+export type PayloadItem =
+| {
+    type: "field";
+    key: string;
+    value: unknown;
+    fill?: boolean;
+    /**
+     * Paths to `!must_fill` markers nested *inside* `value` (the `value`
+     * projection itself is fill-free). Absent when the field has no nested
+     * placeholders. Preserved across `pushCard` / `makeCard`.
+     */
+    nestedFills?: PathStep[][];
+}
+| { type: "comment"; text: string; inline?: boolean };
+
+/**
+ * A single card block, as read back from a document: returned by
+ * `Document.main` / `Document.cards` / `Document.removeCard` / `Quill.seedCard`
+ * / `Document.makeCard`. To feed a card *into* a document use `CardInput`
+ * (which `pushCard` / `insertCard` accept); every `Card` is a valid `CardInput`,
+ * so a card read from one document pushes straight into another.
+ *
+ * `$` system entries are hoisted to named fields: `kind` (the `$kind`, empty
+ * string when none), optional `quill` (the `$quill` `name@version`, main card
+ * only), optional `id` (`$id`), optional `ext` (`$ext`), and optional `seed`
+ * (the `$seed` per-kind overlay map, main card only). `payloadItems` carries
+ * user fields and comments in order.
+ */
+export interface Card {
+    kind: string;
+    quill?: string;
+    id?: string;
+    ext?: Record<string, unknown>;
+    seed?: Record<string, unknown>;
+    payloadItems: PayloadItem[];
+    /**
+     * The card body as canonical `RichText` — the source-of-truth content model.
+     * Always this corpus shape on read, never a markdown string. For the markdown
+     * projection call the codec `exportMarkdown(card.body)`. Write a body back
+     * with `doc.install(addr, rt)` / `doc.revise(addr, md)`, or via `CardInput.body`.
+     */
+    body: RichText;
+}
+
+/**
+ * A card written *into* a document — the input twin of `Card`, accepted by
+ * `Document.pushCard` / `Document.insertCard`. Like `Card` but `body` also
+ * takes a markdown `string` (imported to the corpus, so a markdown / LLM writer
+ * needn't build the `RichText` shape), and every field but `kind` is optional —
+ * an absent field defaults (no payload items, an empty body). Write one inline
+ * (`{ kind, body }`) or build it with `Document.makeCard`.
+ */
+export interface CardInput {
+    kind: string;
+    quill?: string;
+    id?: string;
+    ext?: Record<string, unknown>;
+    seed?: Record<string, unknown>;
+    payloadItems?: PayloadItem[];
+    body?: RichText | string;
+}
+
+/**
+ * Canonical richtext corpus — the content model for a card body (and richtext
+ * fields). One text sequence over a single coordinate space (Unicode scalar
+ * values): `text` plus line attributes, anchored `marks`, and embedded
+ * `islands`. Every edit is a splice; markdown is a projection, not the model.
+ * Mirrors `quillmark_richtext::serial`'s canonical JSON encoding.
+ */
+export interface RichText {
+    text: string;
+    lines: RichTextLine[];
+    marks: RichTextMark[];
+    islands: RichTextIsland[];
+}
+
+/** One `\n`-separated segment of `RichText.text`, in order. */
+export type RichTextLine = {
+    containers: RichTextContainer[];
+    /** A within-block hard line break rather than a new block. Omitted (false) in the common case. */
+    continues?: boolean;
+} & (
+| { kind: "para" }
+| { kind: "heading"; level: number }
+| { kind: "code"; lang?: string }
+| { kind: "island" }
+| { kind: "rule" }
+);
+
+/** An ancestor block a line nests inside, outermost first. */
+export type RichTextContainer =
+| { container: "list_item"; ordered: boolean; start: number; ordinal: number }
+| { container: "quote" };
+
+/** A mark over char range `[start, end)` into `RichText.text`. */
+export type RichTextMark = { start: number; end: number } & (
+| { type: "strong" | "emph" | "underline" | "strike" | "code" }
+| { type: "link"; url: string }
+| { type: "anchor"; id: string }
+| { type: string; attrs: unknown }
+);
+
+/** A structured object (table, figure, …) occupying one island slot in `RichText.text`. */
+export interface RichTextIsland {
+    id: string;
+    type: string;
+    props: unknown;
+    /** How faithfully the markdown projection can carry this island. */
+    loss: "lossless" | "degraded" | "unrepresentable";
+}
+
+/**
+ * A richtext write address. An absent `field` targets the card body; an absent
+ * `card` targets the main card. `{}` is the main-card body; `{ card: 2 }` the
+ * body of the composable card at index 2; `{ field: "intro" }` the main card's
+ * `intro` richtext field; `{ card: 2, field: "intro" }` a card field.
+ */
+export interface Addr {
+    card?: number;
+    field?: string;
+}
+
+/**
+ * A text-splice change set over the USV corpus (CodeMirror `ChangeSet`
+ * semantics) — plain, structured-clone-able data. Returned by `revise` and by
+ * the `rebase` codec; map a stored position through it with `mapPos`.
+ */
+export interface Delta {
+    ops: ({ retain: number } | { insert: string } | { delete: number })[];
+}
+
+/** Which side of a same-position insertion `mapPos` lands a point on. */
+export type Assoc = "before" | "after";
+
+/**
+ * A mark edit in post-text-delta coordinates. `add` / `remove` carry the
+ * `RichTextMark` vocabulary (`{ type, … }`); `removeAnchor` drops one identity
+ * anchor by id.
+ */
+export type MarkOp =
+| ({ op: "add" | "remove"; start: number; end: number } & (
+| { type: "strong" | "emph" | "underline" | "strike" | "code" }
+| { type: "link"; url: string }
+| { type: "anchor"; id: string }
+| { type: string; attrs: unknown }
+))
+| { op: "removeAnchor"; id: string };
+
+/** A line/block edit. `split`/`join` splice `\n`; `setKind`/`setContainers` touch metadata. */
+export type LineOp =
+| { op: "split"; at: number }
+| { op: "join"; line: number }
+| ({ op: "setKind"; line: number } & (
+| { kind: "para" | "island" | "rule" }
+| { kind: "heading"; level: number }
+| { kind: "code"; lang?: string }
+))
+| { op: "setContainers"; line: number; containers: RichTextContainer[] };
+
+/**
+ * A committed corpus edit bundle for `applyChange`: a text `delta` (default no
+ * text change), then `lineOps`, then `markOps` (mark ranges are in post-delta
+ * coordinates). Every field is optional.
+ */
+export interface ChangeBundle {
+    delta?: Delta;
+    lineOps?: LineOp[];
+    markOps?: MarkOp[];
+}
+
+
+
+/**
+ * Page dimensions in points (1 pt = 1/72 inch). Typst measures in Typst
+ * points; pdfform measures in PDF points — the same unit.
+ *
+ * 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 `LiveSession.paint`. Both fields are optional and default
+ * to `1`.
+ *
+ * - `layoutScale` — layout-space pixels per point (Typst point / PDF
+ *   point — the same 1/72″ unit). 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 `LiveSession.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.
+ * - `clamped` — `true` when that 16384-px clamp fired, so the page is
+ *   painted at fewer device pixels than requested and renders soft at the
+ *   same `canvas.style` size. Reads the clamp off the return value instead
+ *   of the `pixelWidth < round(layoutWidth * densityScale)` derivation.
+ * - `effectiveDensityScale` — the `densityScale` actually applied: the
+ *   requested value unless `clamped`, then reduced proportionally.
+ *   `layoutScale * effectiveDensityScale` is the scale the backing store
+ *   was rasterized at.
+ *
+ * The painter owns `canvas.width` / `canvas.height`; consumers must not
+ * write to them. The painter does **not** touch `canvas.style.*`;
+ * consumers own layout. The write is a whole-backing-store `putImageData`,
+ * which bypasses the 2D context transform, `globalAlpha`, and clip: give
+ * each visible page its own `` — you cannot composite two pages, a
+ * sub-rect, or a context transform through `paint`.
+ *
+ * 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;
+    clamped: boolean;
+    effectiveDensityScale: number;
+}
+
+
+
+/** UI layout hints for a single field. Field display order is not a hint:
+ * key order in the schema's `fields`/`properties` objects is declaration
+ * order, the ordering contract. */
+export interface QuillFieldUi {
+    title?: string;
+    group?: string;
+    compact?: boolean;
+    multiline?: boolean;
+}
+
+/** UI layout hints for a card (main or named card kind). */
+export interface QuillCardUi {
+    title?: string;
+}
+
+/** Body namespace for a card (main or named card kind). */
+export interface QuillCardBody {
+    /** When false, consumers must not accept or store body content for this card kind. Defaults to true. */
+    enabled?: boolean;
+    /** Example body content embedded verbatim in the blueprint body region. Fallback is "Write <card> body here." */
+    example?: string;
+}
+
+/** Schema entry for a single field declared in a quill's `Quill.yaml`.
+ *
+ * A field's *cell* is determined by `default`: a field with a `default`
+ * is **Endorsed** (the rendered value is shippable as-is), while a field
+ * without a `default` is **Unendorsed** (the blueprint carries a
+ * `!must_fill` marker; a marker left in the document yields the non-fatal
+ * `validation::must_fill` warning from validate, and the render path
+ * zero-fills the field). There is no separate `required` axis.
+ */
+export interface QuillFieldSchema {
+    type: "string" | "number" | "integer" | "boolean" | "array" | "object" | "datetime" | "richtext" | "plaintext" | "enum";
+    description?: string;
+    default?: unknown;
+    example?: unknown;
+    /** Closed value domain. On `type: "enum"` declared as `values`; the
+     *  deprecated `enum` modifier on `type: "string"` is accepted for one
+     *  release. Both round-trip through this field. */
+    enum?: string[];
+    /** Required on `type: "enum"`: the closed set of allowed string values. */
+    values?: string[];
+    ui?: QuillFieldUi;
+    properties?: Record<string, QuillFieldSchema>;
+    items?: QuillFieldSchema;
+    /** Present (and `true`) on a `richtext` or `plaintext` field declared
+     *  `inline` — the single-paragraph, container-free, island-free constraint.
+     *  Core serializes `inline: true` into the schema JSON; absent otherwise. */
+    inline?: boolean;
+}
+
+/** Schema entry for the main card or a named card kind. */
+export interface QuillCardSchema {
+    description?: string;
+    fields: Record<string, QuillFieldSchema>;
+    ui?: QuillCardUi;
+    body?: QuillCardBody;
+}
+
+/**
+ * Document schema returned by `Quill.schema`. Includes optional `ui` keys.
+ *
+ * Describes only the user-fillable fields. The quill reference
+ * (constructed as `${metadata.name}@${metadata.version}`) and card-kind
+ * discriminators are document-level metadata, not schema fields.
+ */
+export interface QuillSchema {
+    main: QuillCardSchema;
+    /** Present only when the quill declares at least one named card kind. */
+    card_kinds?: Record<string, QuillCardSchema>;
+}
+
+/**
+ * Identity snapshot mirroring the `quill:` section of `Quill.yaml`.
+ * The schema lives on `Quill.schema`; the backend's output formats are a
+ * resolved-backend capability read from the engine (`Quillmark.supportedFormats`),
+ * not part of this pure-config snapshot.
+ */
+export interface QuillMetadata {
+    name: string;
+    version: string;
+    backend: string;
+    author: string;
+    description: string;
+}
+
+
+export interface Artifact {
+    format: OutputFormat;
+    bytes: Uint8Array;
+    mimeType: string;
+}
+
+export interface ChangeSet {
+    pageCount: number;
+    dirtyPages: number[];
+}
+
+export interface CorpusHit {
+    field: string;
+    pos: number;
+    granularity?: HitGranularity;
+}
+
+export interface Diagnostic {
+    severity: Severity;
+    code?: string;
+    message: string;
+    location?: Location;
+    path?: string;
+    hint?: string;
+    sourceChain?: string[];
+}
+
+export interface FieldRegion {
+    field: string;
+    page: number;
+    rect: [number, number, number, number];
+    span?: [number, number];
+}
+
+export interface Location {
+    file: string;
+    line: number;
+    column: number;
+}
+
+export interface RenderOptions {
+    format?: OutputFormat;
+    ppi?: number;
+    pages?: number[];
+    producer?: string;
+    regions?: boolean;
+}
+
+export interface RenderResult {
+    artifacts: Artifact[];
+    warnings: Diagnostic[];
+    outputFormat: OutputFormat;
+    renderTimeMs: number;
+    regions: FieldRegion[];
+}
+
+export type HitGranularity = "cluster" | "segment";
+
+export type OutputFormat = "pdf" | "svg" | "txt" | "png";
+
+export type Severity = "error" | "warning";
+
+
+/**
+ * Typed in-memory Quillmark document.
+ */
+export class Document {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Build a composable card of `kind`, typed-commit `fields` onto it, set its
+     * body from optional markdown, and append it — the ABI under
+     * `writer.addCard`. Fuses `makeCard` + typed commit + `pushCard`
+     * transactionally: the card is committed in full before it joins the
+     * document, so a rejected field (or an invalid kind or body) leaves the
+     * document untouched. Field errors throw the same per-field diagnostic
+     * bundle as [`commitFields`](Self::commit_fields), including an
+     * `[EditError::UnknownField]` per undeclared name; an invalid kind or body
+     * throws a single-entry bundle keyed `$kind` / `$body`.
+     */
+    addCard(quill: Quill, kind: string, fields?: Record<string, unknown>, body?: string): void;
+    /**
+     * **Apply** a committed corpus edit `bundle` (`{ delta?, lineOps?, markOps? }`)
+     * at `addr` — the editor splice: text delta first, then line ops, then mark
+     * ops (mark ranges in post-delta coordinates), each all-or-nothing. An absent
+     * `addr.field` targets the body, an absent `addr.card` the main card.
+     *
+     * Throws on an out-of-range card, a field that is not richtext, a malformed
+     * bundle, or an op that applies out of bounds (the value is unchanged on a
+     * failed apply).
+     */
+    applyChange(addr: Addr, bundle: ChangeBundle): void;
+    /**
+     * Authoring-ergonomics header introducing a blueprint to an LLM/MCP
+     * consumer for the given `quillName`. Re-exposes core's canonical text for
+     * JS consumers; any surface that draws from the same core source stays
+     * uniform.
+     */
+    static blueprintInstruction(quill_name: string): string;
+    clone(): Document;
+    /**
+     * Typed field write on the composable card at `index` — the card-indexed
+     * twin of [`commitField`](Document::commit_field). Resolves the field's
+     * type from the card's `$kind` schema in `quill` and strict-commits it.
+     *
+     * Throws `[EditError::IndexOutOfRange]` when `index` is out of range, and
+     * the same typed-mismatch / name errors as `commitField` — including
+     * `[EditError::UnknownField]` for a field the card-kind schema does not
+     * declare (an unknown `$kind` has no schema, so every field is undeclared).
+     */
+    commitCardField(quill: Quill, index: number, name: string, value: any): void;
+    /**
+     * Batched twin of [`commitCardField`](Document::commit_card_field):
+     * typed-commit several fields on the card at `index` atomically, resolving
+     * each field's type from the card's `$kind` schema in `quill`. All-or-nothing
+     * with the same per-field-diagnostic contract as
+     * [`commitFields`](Document::commit_fields), including an
+     * `[EditError::UnknownField]` diagnostic per undeclared name. Throws
+     * `[EditError::IndexOutOfRange]` when `index` is out of range.
+     */
+    commitCardFields(quill: Quill, index: number, fields: Record<string, unknown>): void;
+    /**
+     * Typed field write on the main card, resolving the field's schema `type`
+     * from `quill` — the one write verb for **every** field type (richtext,
+     * scalar, array, object). The schema carries the `inline` constraint, so no
+     * type token or flag is passed. A richtext-typed field stores the canonical
+     * corpus, so identity marks (anchors, island ids) and corpus-only marks
+     * (e.g. `underline`) live on it and survive compiles and the storage DTO.
+     * Values use the encoding the seam already speaks: a corpus object
+     * or markdown string for richtext, a scalar/array/object otherwise.
+     *
+     * A field declared in the schema is strict-committed — a mismatch throws
+     * now, not at render. A name the schema does not declare throws
+     * `[EditError::UnknownField]` rather than falling to the opaque store: on
+     * the typed path it is a typo. Use [`setField`](Document::set_field) when
+     * opaque storage is the intent. Also throws `[EditError::FieldConform]` /
+     * `[EditError::FieldRichtextDecode]` / `[EditError::FieldRichtextNotInline]`
+     * on a typed mismatch and `[EditError::InvalidFieldName]` on a malformed
+     * name.
+     *
+     * The `quill` handle is passed per call because a `Document` carries only a
+     * `$quill` reference, not the resolved schema.
+     */
+    commitField(quill: Quill, name: string, value: any): void;
+    /**
+     * Batched twin of [`commitField`](Document::commit_field): typed-commit
+     * several main-card fields atomically, resolving each field's schema `type`
+     * from `quill`. All-or-nothing with the same per-field-diagnostic error
+     * contract as [`setFields`](Document::set_fields) — nothing is applied on
+     * error and the thrown error's `diagnostics` carry one entry per offending
+     * field, including an `[EditError::UnknownField]` for any name the schema
+     * does not declare, so a whole-form submit sees every typo in one pass.
+     */
+    commitFields(quill: Quill, fields: Record<string, unknown>): void;
+    /**
+     * Schema version this build writes via [`toJson`](Document::to_json).
+     * Tracks the `Document` model version (not the running crate version):
+     * the tag advances only when the wire format changes, not on every release.
+     */
+    static currentSchemaVersion(): string;
+    /**
+     * Structural equality (parse-time `warnings` excluded). Use to debounce
+     * upstream prop updates instead of re-parsing on every keystroke.
+     */
+    equals(other: Document): boolean;
+    /**
+     * Render a Diagnostic as the canonical pretty-printed text (core's
+     * `Diagnostic::fmt_pretty`). Single source of truth so a Diagnostic looks
+     * identical no matter which consumer surfaces it.
+     */
+    static formatDiagnostic(diag: Diagnostic): string;
+    /**
+     * Authoring-format rules for the card-yaml markdown surface. The canonical
+     * text is core's (`quillmark_core::document::FORMAT_RULES`), re-exposed
+     * here for JS consumers so it matches any other surface that draws from the
+     * same source. Read once at startup and cache; the value never changes
+     * between calls.
+     */
+    static formatRules(): string;
+    /**
+     * Reconstruct a `Document` from a versioned storage DTO string produced
+     * by [`toJson`](Document::to_json). Unknown `schema` tags are rejected.
+     * The result carries no parse-time warnings (`.warnings` is always empty).
+     *
+     * Throws if `json` is not a valid storage DTO (malformed JSON, unknown
+     * `schema`, missing fields, or unparseable quill reference).
+     */
+    static fromJson(json: string): Document;
+    /**
+     * Parse markdown into a typed Document. Throws on parse errors.
+     */
+    static fromMarkdown(markdown: string): Document;
+    /**
+     * Read a main-card field's stored value — the raw payload value (a corpus
+     * object for a richtext field, a scalar/array/object otherwise), or
+     * `undefined` when the field is absent. The quill-free read: reads need no
+     * schema, so they live on `Document`, not the typed writer. For the markdown
+     * projection of a richtext value use [`getMarkdown`](Self::get_markdown).
+     */
+    get(name: string): any;
+    /**
+     * The markdown projection of a main-card field (`name` given) or the main
+     * body (`name` omitted) — the on-demand, lossy export (corpus-only marks do
+     * not survive markdown), returning `""` for an absent field. Re-coins,
+     * lazily and by name, the projection the eager `fieldMarkdown` /
+     * `bodyMarkdown` getters dropped in #925; call it only when markdown is what
+     * you need out.
+     */
+    getMarkdown(name?: string): string;
+    /**
+     * Insert a card at `index` (must be in `0..=cards.length`). Accepts a
+     * `CardInput` (see [`pushCard`](Self::push_card)).
+     */
+    insertCard(index: number, card: CardInput): void;
+    /**
+     * **Install** a richtext value at `addr` — **value semantics**, corpus only.
+     * Stores exactly `rt` (a canonical `RichText` corpus object); the identity
+     * anchors of any previous value are gone. An absent `addr.field` targets the
+     * body, an absent `addr.card` the main card. For "here's new markdown," use
+     * [`revise`](Document::revise); the cold-import path is spelled at the call
+     * site as `install(addr, importMarkdown(md))`, so anchor loss is visible in
+     * source.
+     *
+     * Throws on an out-of-range card, a malformed field name, or an `rt` that is
+     * not a canonical corpus object.
+     */
+    install(addr: Addr, rt: RichText): void;
+    /**
+     * Replace this document's contents **in place** from a versioned storage
+     * DTO string — the mutating twin of the static
+     * [`fromJson`](Document::from_json) constructor. Parse-time `warnings` are
+     * cleared. Throws (leaving the document unchanged) on an invalid DTO.
+     *
+     * The cross-WASM-memory `Document` bridge: mutate a document on a
+     * backend-memory clone, then write the mutated state back into the caller's
+     * canonical document with this — the one way to update a live handle across
+     * the linear-memory seam without the caller re-binding its variable.
+     */
+    loadJson(json: string): void;
+    /**
+     * Build a fresh `Card` from a kind and a flat field map — the ergonomic
+     * constructor for `pushCard` / `insertCard`. `fields` is an optional
+     * `Record<string, unknown>` (each entry becomes a card field, in
+     * insertion order); `body` defaults to `""`. Kind validity is checked by
+     * `pushCard` / `insertCard`, not here.
+     */
+    static makeCard(kind: string, fields?: Record<string, unknown>, body?: string): Card;
+    /**
+     * Move the card at `from` to position `to`. `from == to` is a no-op.
+     */
+    moveCard(from: number, to: number): void;
+    /**
+     * `new Document(quillRef)` — a blank document: a main card carrying only
+     * `$quill`, an empty body, and no composable cards. The programmatic
+     * blank canvas: absent fields resolve at render time (`default`, else
+     * type-empty zero), so nothing the caller did not set reaches the
+     * output. For an example-filled starter use `Quill.seedDocument()`.
+     * Throws on an invalid quill reference. Mirrors Python `Document(quill_ref)`.
+     */
+    constructor(quill_ref: string);
+    /**
+     * Append a card to the end of the card list. Accepts a `CardInput` — a card
+     * read back (`cards` / `removeCard` / `quill.seedCard`), a
+     * [`makeCard`](Document::make_card) result, or a bare `{ kind, body }`
+     * (every returned `Card` is a valid `CardInput`). Throws if `card.kind` is
+     * not a valid kind name.
+     */
+    pushCard(card: CardInput): void;
+    /**
+     * The canonical `$quill` reference grammar as author-facing text. Core is
+     * the single source of truth: drive schema `describe` and validation
+     * messages from this instead of re-stating the rule — it matches the
+     * `hint` on `parse::invalid_quill_reference`. Cache it; the value never
+     * changes.
+     */
+    static quillRefHint(): string;
+    removeCard(index: number): Card | undefined;
+    /**
+     * Remove the `$ext` map from the composable card at `index` *entirely*,
+     * returning the previous map or `undefined`. Throws if out of range.
+     * Prefer `removeCardExtNamespace` to clear only one consumer's slot.
+     */
+    removeCardExt(index: number): Record<string, unknown> | undefined;
+    /**
+     * Remove `namespace` from the composable card's `$ext` map, returning the
+     * value stored there or `undefined`; clears `$ext` entirely once empty.
+     * The card-indexed twin of `removeExtNamespace`. Throws if out of range.
+     */
+    removeCardExtNamespace(index: number, namespace: string): any;
+    /**
+     * Remove a field on the card at `index`. Returns the removed value or
+     * `undefined`. Throws if `index` is out of range or `name` is invalid.
+     */
+    removeCardField(index: number, name: string): any;
+    /**
+     * Remove the `$ext` map from the main card *entirely*, returning the
+     * previous map or `undefined`. This is a blunt escape hatch that discards
+     * every namespace at once — prefer `removeExtNamespace` to clear only your
+     * own slot while leaving sibling consumers' state intact.
+     */
+    removeExt(): Record<string, unknown> | undefined;
+    /**
+     * Remove `namespace` from the main card's `$ext` map, returning the value
+     * stored there or `undefined`. This is the recommended way to clear `$ext`
+     * state: sibling namespaces survive, and when the last namespace is removed
+     * the `$ext` entry is dropped entirely (not left as `$ext: {}`).
+     */
+    removeExtNamespace(namespace: string): any;
+    /**
+     * Remove a payload field on the main card, returning the removed value or
+     * `undefined`. Throws if `name` does not match `[A-Za-z_][A-Za-z0-9_]*`.
+     */
+    removeField(name: string): any;
+    /**
+     * Remove `cardKind` from the main card's `$seed` map, returning its
+     * overlay or `undefined`; drops `$seed` entirely once empty. Sibling
+     * kinds survive.
+     */
+    removeSeedNamespace(card_kind: string): any;
+    /**
+     * **Deprecated** — alias for `revise({}, markdown)`, kept one release cycle.
+     * Revise the main card's body from a markdown string (edit semantics: a
+     * `diff_import` that rebases surviving anchors). Discards the text delta;
+     * call [`revise`](Document::revise) to receive it.
+     */
+    replaceBody(body: string): void;
+    /**
+     * **Revise** the richtext value at `addr` from a markdown string — **edit
+     * semantics**, the default write path, returning the text [`Delta`]. Imports
+     * the markdown, diffs it against the current value, rebases surviving
+     * identity anchors, and returns the change an editor bridge maps its own
+     * positions through (`mapPos`). An absent `addr.field` targets the body, an
+     * absent `addr.card` the main card; an absent field cold-imports from empty.
+     *
+     * Throws on an out-of-range card, a malformed field name, a present
+     * non-corpus field value, or an over-nested markdown input.
+     */
+    revise(addr: Addr, markdown: string): Delta;
+    /**
+     * Read the `schema` version tag from a raw storage DTO string without a
+     * full parse, or `undefined`. Returns unknown future versions as-is —
+     * useful to distinguish "build too old" from "payload corrupt" when
+     * `fromJson` throws.
+     */
+    static schemaVersionOf(json: string): string | undefined;
+    /**
+     * Replace the `$ext` map on the composable card at `index`. Throws if out
+     * of range or `value` is not a plain object. Named to mirror `setExt` on
+     * the main card; `setCardExtNamespace` is the sibling-safe alternative.
+     */
+    setCardExt(index: number, value: any): void;
+    /**
+     * Merge `value` into the composable card's `$ext` map under `namespace`,
+     * preserving sibling namespaces. The card-indexed twin of `setExtNamespace`.
+     * Throws if out of range or `value` cannot be serialized.
+     */
+    setCardExtNamespace(index: number, namespace: string, value: any): void;
+    /**
+     * Set a field on the card at `index` — the card-indexed twin of
+     * [`setField`](Document::set_field). Stores the value opaquely.
+     * Throws if `index` is out of range, `name` is reserved or invalid.
+     */
+    setCardField(index: number, name: string, value: any): void;
+    /**
+     * Batched twin of [`setCardField`](Document::set_card_field): set
+     * several fields on the card at `index` atomically. Same all-or-nothing,
+     * one-diagnostic-per-field contract as [`setFields`](Document::set_fields).
+     * Throws if `index` is out of range.
+     */
+    setCardFields(index: number, fields: Record<string, unknown>): void;
+    /**
+     * Replace the kind of the card at `index`. Payload and body are untouched;
+     * schema-aware migration is the caller's responsibility.
+     * Throws if `index` is out of range or `newKind` is invalid.
+     */
+    setCardKind(index: number, new_kind: string): void;
+    /**
+     * Replace the opaque `$ext` map on the main card. `value` must be a plain
+     * object; throws otherwise. `$ext` carries out-of-band consumer state and
+     * never reaches the rendered output. Pass `{}` to record an explicit
+     * empty `$ext`.
+     */
+    setExt(value: any): void;
+    /**
+     * Merge `value` into the main card's `$ext` map under `namespace`, creating
+     * the map when absent and replacing any existing value at that key. Sibling
+     * namespaces are preserved, so independent consumers (`$ext.editor`,
+     * `$ext.agent`, …) don't clobber each other.
+     */
+    setExtNamespace(namespace: string, value: any): void;
+    /**
+     * Update a payload field on the main card. Clears any existing `!must_fill` marker.
+     *
+     * Throws if `name` does not match `[A-Za-z_][A-Za-z0-9_]*`.
+     */
+    setField(name: string, value: any): void;
+    /**
+     * Set several main-card payload fields atomically from a plain object,
+     * clearing any `!must_fill` marker on each key. Nothing is applied on
+     * error; the thrown error's `diagnostics` array carries one entry per
+     * offending field (`path` = field name), so externally-sourced names
+     * (database columns, form keys) surface every violation in one pass.
+     * Mirrors Python `set_fields`.
+     */
+    setFields(fields: Record<string, unknown>): void;
+    /**
+     * Update a payload field on the main card and mark it as `!must_fill`.
+     * Throws on invalid name (see [`setField`](Document::set_field)).
+     */
+    setFill(name: string, value: any): void;
+    /**
+     * Replace the QUILL reference string. Throws if `ref_str` is invalid.
+     */
+    setQuillRef(ref_str: string): void;
+    /**
+     * Merge a card-kind's seed `overlay` into the main card's `$seed` map
+     * under `cardKind`, preserving sibling kinds. Sets the starting values
+     * new cards of that kind spawn with. Throws if `overlay` cannot be
+     * serialized or nests too deep.
+     */
+    setSeedNamespace(card_kind: string, overlay: any): void;
+    /**
+     * Serialize this document to a versioned storage DTO string.
+     *
+     * Prefer this over `toMarkdown` for persistence across restarts or crate
+     * upgrades — the wire format is frozen per `schema` version. Parse-time
+     * `warnings` are excluded from the DTO.
+     *
+     * Output is **byte-deterministic** within a `schema` version: equal
+     * documents produce byte-equal output, safe for content-hash use cases.
+     */
+    toJson(): string;
+    /**
+     * Emit canonical Quillmark Markdown. Round-trip safe: re-parsing the
+     * result produces a `Document` equal to `self` by value and by type.
+     */
+    toMarkdown(): string;
+    /**
+     * Like [`fromJson`](Document::from_json) but returns `undefined` instead
+     * of throwing when `json` is not a valid storage DTO — use to
+     * discriminate format without exceptions as control flow.
+     * `undefined` means "not a storage DTO"; `fromMarkdown` still throws on
+     * genuinely malformed markdown.
+     */
+    static tryFromJson(json: string): Document | undefined;
+    /**
+     * Number of composable cards (excludes the main card). O(1).
+     */
+    readonly cardCount: number;
+    readonly cards: Card[];
+    /**
+     * The document's main (entry) card. Allocates and serializes on each
+     * call — cache locally if read in a hot loop.
+     */
+    readonly main: Card;
+    readonly quillRef: string;
+    readonly warnings: Diagnostic[];
+}
+
+/**
+ * Live render session: reads (`render`, `paint`, `pageSize`, `regions`,
+ * `fieldAt`, `positionAt`, `locate`) serve the current compile. `apply(doc)`
+ * recompiles a whole document in place, transactionally (on throw every read
+ * keeps serving the last-good compile). Geometry reads reflect the current
+ * compile; anchoring a caret across edits is the editor's job — re-read
+ * geometry after each committed `apply`.
+ *
+ * **Empty documents.** A zero-page document yields a valid session
+ * (`pageCount === 0`); `paint(ctx, 0)` or `pageSize(0)` throws with
+ * `"page index 0 out of range (pageCount=0)"`. Branch on `pageCount === 0`
+ * rather than catching the error.
+ */
+export class LiveSession {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Recompile the session against `doc` — the edit verb of a live preview.
+     * The document is compiled through the same schema pipeline as `open`
+     * (same quill), then applied transactionally: on throw every read
+     * (`render`, `paint`, `pageSize`, `regions`, `fieldAt`) keeps serving the last-good
+     * compile, and the session recovers on the next successful `apply`. On
+     * success reads serve the new compile; repaint `dirtyPages ∩ visible`.
+     */
+    apply(doc: Document): ChangeSet;
+    /**
+     * The schema field whose content is under a point on `page` — the
+     * forward (click → field) direction: hit-test a click against the
+     * compiled document and get back the field address to focus in the
+     * editor, or `undefined` off any field's ink. `x`/`y` are PDF points
+     * with a **bottom-left** origin, the same space as `FieldRegion.rect` —
+     * from a canvas click, invert the overlay transform documented on
+     * `FieldRegion`: `x = clickPx.x / renderScale`,
+     * `y = pageHeightPt - clickPx.y / renderScale`. Unlike `regions()`,
+     * *every* placement answers, not just the first.
+     */
+    fieldAt(page: number, x: number, y: number): string | undefined;
+    /**
+     * The whole-field highlight boxes for `field` — one union rect per page,
+     * over the field's `span`-bearing content segments. The convenience that
+     * owns the union `regions()` leaves derived: it keeps `regions()` the
+     * low-level disjoint truth (#829) and folds the span-filter + per-page
+     * union here, so a "highlight the focused field" consumer stops
+     * reimplementing it. **Content only** — a field placed solely as a scalar
+     * reference or a bound widget carries no `span` and returns `[]`; its box
+     * is a single `regions()` rect. Reflects the current compile, like
+     * `regions()`.
+     */
+    fieldBoxes(field: string): FieldRegion[];
+    /**
+     * A corpus position → **caret rect** — the reverse of `positionAt`: given
+     * a field and a USV offset into its `RichText`, return the box (in the
+     * same bottom-left PDF-point space as `FieldRegion.rect`) to draw a caret
+     * at, its `span` collapsed to `[pos, pos]`; `undefined` when the field
+     * places no tracked content or the offset maps to no drawn glyph.
+     */
+    locate(field: string, pos: number): FieldRegion | undefined;
+    /**
+     * Page dimensions in points (1 pt = 1/72 inch).
+     * Throws if the backend has no canvas painter or `page` is out of range.
+     */
+    pageSize(page: number): PageSize;
+    /**
+     * Paint `page` into a `CanvasRenderingContext2D` or
+     * `OffscreenCanvasRenderingContext2D`. The painter owns
+     * `canvas.width`/`height` (no `clearRect` needed); consumers own
+     * `canvas.style.*`. If `layoutScale * densityScale` exceeds 16384 px
+     * per side, `densityScale` is clamped — `PaintResult.clamped` reports it and
+     * `PaintResult.effectiveDensityScale` carries the density actually applied.
+     *
+     * `put_image_data` writes the whole backing store, bypassing the 2D
+     * context's transform, `globalAlpha`, and clip: the painter owns the entire
+     * canvas, so each visible page needs its own `` — you cannot composite
+     * two pages, a sub-rect, or a context transform through this call.
+     *
+     * Throws if the backend has no canvas painter, `page` is out of range,
+     * `ctx` is the wrong type, or either scale is non-finite or `<= 0`.
+     */
+    paint(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, page: number, opts: PaintOptions | undefined): PaintResult;
+    /**
+     * A point → **corpus position** — the fine-grained click direction:
+     * hit-test a point and get back the field *and* a USV offset into its
+     * `RichText` (for placing a caret or mapping a selection into the content
+     * model), or `undefined` off all content ink. `x`/`y` are PDF points,
+     * bottom-left origin — the same space as `fieldAt`. The offset is
+     * cluster-exact and degrades to the containing segment's start on
+     * origin-less ink (list markers, a code fence's interior). See
+     * `CorpusHit`.
+     */
+    positionAt(page: number, x: number, y: number): CorpusHit | undefined;
+    /**
+     * Schema-field geometry for this compiled session — each content field's
+     * **first placement** (one region per page it touches) plus widget and
+     * scalar-reference-site regions, keyed on the quill schema field path; a
+     * field may still appear more than once (group by `field`, see
+     * `FieldRegion`). A session-level query: no render, no byte artifact. An
+     * interactive preview reads it to scroll to / highlight the focused
+     * field over a `paint`-ed canvas; the click direction is `fieldAt`.
+     * Empty for backends that place no schema fields.
+     */
+    regions(): FieldRegion[];
+    render(opts?: RenderOptions | null): RenderResult;
+    /**
+     * The backend that produced this session (e.g. `"typst"`).
+     */
+    readonly backendId: string;
+    readonly pageCount: number;
+    /**
+     * `true` iff `paint` and `pageSize` will succeed for this session. Derived
+     * from the session's canvas seam, so it reflects exactly what `paint` will
+     * do — no separately captured flag.
+     */
+    readonly supportsCanvas: boolean;
+    /**
+     * Non-fatal diagnostics of the session's **current compile** (e.g. Typst
+     * font fallback) — set at open and refreshed by each committed `apply`;
+     * a failed apply keeps the last-good compile's warnings. Also appended
+     * to `RenderResult.warnings` on each `render()` call.
+     */
+    readonly warnings: Diagnostic[];
+}
+
+export class Quill {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Build a quill from a file tree. Pure — no backend, no engine; the
+     * declared backend is resolved later, at render time.
+     *
+     * Accepts either a `Map<string, Uint8Array>` or a plain object
+     * (`Record<string, Uint8Array>`). Plain objects are walked via
+     * `Object.entries` at the boundary; the Rust side sees a single
+     * canonical shape.
+     */
+    static fromTree(tree: Map<string, Uint8Array>): Quill;
+    /**
+     * Seed a starter composable `Card` of the given kind (carries `$kind`),
+     * layering an optional per-kind seed `overlay` over the schema-example
+     * base (`overlay › example › absent`). Returns `undefined` if `cardKind`
+     * is not declared in this quill's schema, else a `Card` that feeds
+     * straight into `Document.pushCard` / `insertCard`.
+     *
+     * Pass `document.main.seed?.[cardKind]` as `overlay` so a card added to a
+     * template-derived document inherits its curated starting values; omit it
+     * (or pass `undefined` / `null`) for the bare schema seed. `overlay` is a
+     * plain object — this reads the document, it does not mutate it.
+     */
+    seedCard(card_kind: string, overlay: Record<string, unknown> | undefined): Card | undefined;
+    /**
+     * Seed a starter `Document` from the schema — the main card plus one
+     * instance of each composable card kind, each committing its fields'
+     * `example:` values and leaving every other field absent (interpolated at
+     * render: `default:`, else type-empty zero). Illustration-first: a field
+     * with both an `example` and a `default` renders its example. See
+     * `prose/canon/SCHEMAS.md` § "Document seeding".
+     */
+    seedDocument(): Document;
+    /**
+     * Seed a starter main `Card` (carries `$quill`) from the schema — the
+     * `$kind: main` card of [`seedDocument`](Self::seed_document) in
+     * isolation, committing each field's `example:` value. Returns the same
+     * `Card` shape as the `Document.main` getter.
+     */
+    seedMain(): Card;
+    /**
+     * Flatten this quill back into its canonical file tree — the inverse of
+     * [`fromTree`](Self::from_tree). Round-trips: `Quill.fromTree(q.toTree())`
+     * reproduces an equivalent quill.
+     *
+     * This is how a quill crosses a WASM linear-memory boundary as data: a
+     * `Quill` built in one build (e.g. the Typst-less `@quillmark/wasm/core`)
+     * cannot be passed to an engine in another (separate linear memories), so
+     * `@quillmark/wasm/runtime` re-feeds this tree to the backend build's
+     * `Quill.fromTree` on demand. Keys are `"/"`-joined relative paths,
+     * matching what `fromTree` accepts.
+     */
+    toTree(): Map<string, Uint8Array>;
+    /**
+     * Validate `doc` against this quill's schema, returning every diagnostic
+     * (an empty array when the document is valid).
+     *
+     * Forwards the canonical `validation::*` diagnostics — same `code`,
+     * `path`, and `hint` the engine emits — including the non-fatal
+     * `validation::must_fill` warning for each `!must_fill` marker left in
+     * the document. Field values, defaults, and order are not part of this
+     * surface: read them from the `Document` payload and `Quill.schema`
+     * (schema key order is display order).
+     */
+    validate(doc: Document): Diagnostic[];
+    /**
+     * The *declared* backend identifier (`config.backend`, e.g. `"typst"`).
+     * Intent, not a resolved capability — capability (`supportedFormats` /
+     * `supportsCanvas`) is read from the engine.
+     */
+    readonly backendId: string;
+    readonly blueprint: string;
+    /**
+     * Identity snapshot of the `quill:` section of `Quill.yaml` plus any extra
+     * `quill:` keys. Pure config — the backend's output formats are a
+     * resolved-backend capability read from the engine
+     * (`Quillmark.supportedFormats`), not part of this snapshot.
+     */
+    readonly metadata: QuillMetadata;
+    /**
+     * Document schema for the quill: the user-fillable fields plus their
+     * `ui` hints (title / group / compact / multiline). The single
+     * field-metadata surface — drives form editors and LLM/MCP consumers
+     * alike. Key order in `fields`/`properties` is declaration order — the
+     * ordering contract. Returns the `QuillSchema` shape.
+     */
+    readonly schema: QuillSchema;
+}
+
+/**
+ * Render engine: a backend registry and render dispatcher. Render build only —
+ * the core build constructs and validates quills without it.
+ */
+export class Quillmark {
+    free(): void;
+    [Symbol.dispose](): void;
+    constructor();
+    /**
+     * Open a live render session for `doc` against `quill`'s backend.
+     */
+    open(quill: Quill, doc: Document): LiveSession;
+    /**
+     * Render `doc` against `quill` in one shot. Convenience over `open` +
+     * `LiveSession.render`: an unset `output_format` falls back to the
+     * backend's first supported format.
+     */
+    render(quill: Quill, doc: Document, opts?: RenderOptions | null): RenderResult;
+    /**
+     * The output formats `quill`'s backend can emit. Static capability —
+     * resolves the backend but compiles nothing. Throws `engine::backend_not_found`
+     * if no registered backend matches the quill's declared backend.
+     */
+    supportedFormats(quill: Quill): OutputFormat[];
+    /**
+     * Pre-session hint: `true` iff `quill`'s backend can paint sessions to a
+     * canvas, derived from the backend's output formats; `false` when the
+     * backend is unsupported. Use as a cheap precondition probe before mounting
+     * a canvas-based preview UI; the authoritative answer is the session's
+     * `supportsCanvas` getter once `open()` has been called.
+     */
+    supportsCanvas(quill: Quill): boolean;
+}
+
+/**
+ * Export a canonical `RichText` corpus to its markdown projection — the pure
+ * codec that replaces the eager `bodyMarkdown` / `fieldMarkdown` precomputes
+ * (`exportMarkdown(card.body)`). Throws if `rt` is not a canonical corpus.
+ */
+export function exportMarkdown(rt: RichText): string;
+
+/**
+ * Import a markdown string to a canonical `RichText` corpus — the pure,
+ * document-free codec. Pair with `install(addr, importMarkdown(md))` to spell
+ * the cold (anchor-losing) write at the call site; prefer `revise` for edit
+ * semantics. Throws on an over-nested input.
+ */
+export function importMarkdown(markdown: string): RichText;
+
+/**
+ * Initialize the WASM module with panic hooks for better error messages
+ */
+export function init(): void;
+
+/**
+ * Map a base corpus position through a `delta` to its new position — the pure
+ * position-mapping codec an editor bridge composes to hold a caret stable
+ * across a `revise`. `assoc` decides the side of a same-position insertion
+ * (`"after"` moves past it). Throws on a malformed `delta`.
+ */
+export function mapPos(delta: Delta, pos: number, assoc: Assoc): number;
+
+/**
+ * Rebase `markdown` onto a `base` corpus — the pure, document-free twin of
+ * `revise`: cold-import + `diff_import`, returning the new `corpus` and the
+ * text `delta` (surviving anchors rebased). Use it to compute a revise without
+ * a document in hand; `revise(addr, md)` fuses this with the store for
+ * atomicity. Throws on an over-nested markdown input or a non-corpus `base`.
+ */
+export function rebase(base: RichText, markdown: string): { corpus: RichText; delta: Delta };