@quillmark/wasm 0.92.1 → 0.94.0

package/backends/typst/wasm_bg.wasm.d.ts

@@ -2,23 +2,34 @@
 /* eslint-disable */
 export const memory: WebAssembly.Memory;
 export const __wbg_document_free: (a: number, b: number) => void;
+export const __wbg_livesession_free: (a: number, b: number) => void;
 export const __wbg_quill_free: (a: number, b: number) => void;
 export const __wbg_quillmark_free: (a: number, b: number) => void;
-export const __wbg_rendersession_free: (a: number, b: number) => void;
+export const document_addCard: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: 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_cardCount: (a: number) => number;
 export const document_cards: (a: number, b: number) => void;
 export const document_clone: (a: number) => number;
+export const document_commitCardField: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+export const document_commitCardFields: (a: number, b: number, c: number, d: number, e: number) => void;
+export const document_commitField: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+export const document_commitFields: (a: number, b: number, c: number, d: number) => void;
 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_get: (a: number, b: number, c: number, d: number) => void;
+export const document_getMarkdown: (a: number, b: number, c: number, d: 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_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_pushCard: (a: number, b: number, c: number) => void;
 export const document_quillRef: (a: number, b: number) => void;
 export const document_quillRefHint: (a: number) => void;
@@ -30,24 +41,42 @@ export const document_removeExt: (a: number, b: number) => void;
 export const document_removeExtNamespace: (a: number, b: number, c: number, d: number) => void;
 export const document_removeField: (a: number, b: number, c: number, d: number) => void;
 export const document_removeSeedNamespace: (a: number, b: number, c: number, d: number) => void;
-export const document_replaceBody: (a: number, b: number, c: number) => void;
+export const document_replaceBody: (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_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_setCardField: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+export const document_setCardFields: (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_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_setFields: (a: number, b: number, c: 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_setSeedNamespace: (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;
-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, b: number) => void;
+export const exportMarkdown: (a: number, b: number) => void;
+export const importMarkdown: (a: number, b: number, c: number) => void;
 export const init: () => void;
+export const livesession_apply: (a: number, b: number, c: number) => void;
+export const livesession_backendId: (a: number, b: number) => void;
+export const livesession_fieldAt: (a: number, b: number, c: number, d: number, e: number) => void;
+export const livesession_fieldBoxes: (a: number, b: number, c: number, d: number) => void;
+export const livesession_locate: (a: number, b: number, c: number, d: number) => number;
+export const livesession_pageCount: (a: number) => number;
+export const livesession_pageSize: (a: number, b: number, c: number) => void;
+export const livesession_paint: (a: number, b: number, c: number, d: number, e: number) => void;
+export const livesession_positionAt: (a: number, b: number, c: number, d: number) => number;
+export const livesession_regions: (a: number, b: number) => void;
+export const livesession_render: (a: number, b: number, c: number) => void;
+export const livesession_supportsCanvas: (a: number) => number;
+export const livesession_warnings: (a: number, b: number) => void;
+export const mapPos: (a: number, b: number, c: number, d: number) => 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;
@@ -63,13 +92,7 @@ export const quillmark_open: (a: number, b: number, c: number, d: number) => voi
 export const quillmark_render: (a: number, b: number, c: number, d: number, e: number) => void;
 export const quillmark_supportedFormats: (a: number, b: number, c: number) => void;
 export const quillmark_supportsCanvas: (a: number, b: number) => number;
-export const rendersession_backendId: (a: number, b: number) => void;
-export const rendersession_pageCount: (a: number) => number;
-export const rendersession_pageSize: (a: number, b: number, c: number) => void;
-export const rendersession_paint: (a: number, b: number, c: number, d: number, e: number) => void;
-export const rendersession_render: (a: number, b: number, c: number) => void;
-export const rendersession_supportsCanvas: (a: number) => number;
-export const rendersession_warnings: (a: number, b: number) => void;
+export const rebase: (a: number, b: number, c: number, d: 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;

package/core/wasm.d.ts

@@ -24,10 +24,11 @@ export type PayloadItem =
 | { type: "comment"; text: string; inline?: boolean };
 
 /**
- * A single card block. The one shape exchanged in both directions: returned by
- * `Document.main` / `Document.cards` / `Document.removeCard` / `Quill.seedCard`,
- * and accepted by `Document.pushCard` / `Document.insertCard`. Build a fresh
- * one with `Document.makeCard`.
+ * 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
@@ -42,15 +43,149 @@ export interface Card {
     ext?: Record<string, unknown>;
     seed?: Record<string, unknown>;
     payloadItems: PayloadItem[];
-    body: string;
+    /**
+     * 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";
+}
 
-/** UI layout hints for a single field. */
+/**
+ * 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[];
+}
+
+
+
+/** 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;
-    order?: number;
     compact?: boolean;
     multiline?: boolean;
 }
@@ -73,20 +208,28 @@ export interface QuillCardBody {
  * 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>` sentinel and validation reports
- * `validation::field_absent` if the field is absent at validate
- * time — a non-fatal signal, since the render path zero-fills an absent
- * field). There is no separate `required` axis.
+ * `!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" | "markdown";
+    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. */
@@ -141,16 +284,38 @@ export interface Location {
     column: number;
 }
 
-export type Severity = "error" | "warning" | "note";
+export type Severity = "error" | "warning";
 
 
 /**
  * Typed in-memory Quillmark document.
  */
 export class Document {
-    private constructor();
     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
@@ -159,6 +324,60 @@ export class Document {
      */
     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):
@@ -197,11 +416,53 @@ export class 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
-     * `Card` (see [`pushCard`](Self::push_card)).
+     * `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.
      */
-    insertCard(index: number, card: Card): void;
+    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
@@ -215,12 +476,22 @@ export class Document {
      */
     moveCard(from: number, to: number): void;
     /**
-     * Append a card to the end of the card list. Accepts a `Card` (the shape
-     * returned by `cards` / `removeCard` / `quill.seedCard`); build a fresh
-     * one with [`Document.makeCard`](Document::make_card). Throws if
-     * `card.kind` is not a valid kind name.
+     * `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: Card): void;
+    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
@@ -272,7 +543,25 @@ export class Document {
      * 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 —
@@ -292,6 +581,19 @@ export class Document {
      * 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.
@@ -318,6 +620,15 @@ export class Document {
      * 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)).
@@ -358,15 +669,6 @@ export class Document {
      * genuinely malformed markdown.
      */
     static tryFromJson(json: string): Document | undefined;
-    /**
-     * Replace the body of the card at `index`. Throws if out of range.
-     */
-    updateCardBody(index: number, body: string): void;
-    /**
-     * Update a field on the card at `index`.
-     * Throws if `index` is out of range, `name` is reserved or invalid.
-     */
-    updateCardField(index: number, name: string, value: any): void;
     /**
      * Number of composable cards (excludes the main card). O(1).
      */
@@ -443,10 +745,10 @@ export class Quill {
      *
      * Forwards the canonical `validation::*` diagnostics — same `code`,
      * `path`, and `hint` the engine emits — including the non-fatal
-     * `validation::field_absent` completeness signal that `render` demotes.
-     * Field values, defaults, and order are not part of this surface: read
-     * them from the `Document` payload and `Quill.schema` (fields carry
-     * `ui.order`).
+     * `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[];
     /**
@@ -465,14 +767,47 @@ export class Quill {
     readonly metadata: QuillMetadata;
     /**
      * Document schema for the quill: the user-fillable fields plus their
-     * `ui` hints (group / order / showWhen). The single field-metadata
-     * surface — drives form editors and LLM/MCP consumers alike. Returns the
-     * `QuillSchema` shape.
+     * `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;
 }
 
+/**
+ * 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 };

package/core/wasm.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./wasm_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    Document, Quill, init
+    Document, Quill, exportMarkdown, importMarkdown, init, mapPos, rebase
 } from "./wasm_bg.js";