@quillmark/wasm 0.92.1 → 0.94.0

package/core/wasm_bg.wasm.d.ts

@@ -3,20 +3,31 @@
 export const memory: WebAssembly.Memory;
 export const __wbg_document_free: (a: number, b: number) => void;
 export const __wbg_quill_free: (a: number, b: number) => void;
+export const document_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;
@@ -28,24 +39,29 @@ 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 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;
@@ -56,6 +72,7 @@ export const quill_seedDocument: (a: number) => number;
 export const quill_seedMain: (a: number, b: number) => void;
 export const quill_toTree: (a: number) => number;
 export const quill_validate: (a: number, b: number, c: number) => void;
+export const rebase: (a: number, b: number, c: number, d: number) => void;
 export const __wbindgen_export: (a: number, b: number) => number;
 export const __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
 export const __wbindgen_export3: (a: number) => void;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@quillmark/wasm",
-  "version": "0.92.1",
-  "description": "WebAssembly bindings for quillmark",
+  "version": "0.94.0",
+  "description": "WebAssembly bindings for Quillmark, a schema-driven document engine",
   "type": "module",
   "license": "MIT OR Apache-2.0",
   "engines": {
@@ -9,7 +9,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/quillmark-org/quillmark.git"
+    "url": "git+https://github.com/borb-sh/quillmark.git"
   },
   "files": [
     "core",
@@ -30,6 +30,7 @@
   "sideEffects": [
     "./core/wasm.js",
     "./backends/typst/wasm.js",
+    "./backends/pdfform/wasm.js",
     "./runtime/runtime.js"
   ]
 }

package/runtime/runtime.d.ts

@@ -14,6 +14,8 @@
 // public entry point, so this is a structural fact. Replacing the re-export
 // with a wrapper is a breaking design change, not a refactor. See runtime.js.
 export { Quill, Document, init } from '../core/wasm.js';
+// The document-free corpus codec, re-exported from the core build.
+export { importMarkdown, exportMarkdown, rebase, mapPos } from '../core/wasm.js';
 
 // Core-build types consumers read off `Quill`/`Document`.
 export type {
@@ -68,7 +70,7 @@ export declare function isQuillmarkError(e: unknown): e is QuillmarkError;
 // (run via `npm run typecheck`), so these and the generated
 // `pkg/backends/typst/wasm.d.ts` cannot silently diverge.
 
-import type { Quill, Document } from '../core/wasm.js';
+import type { Quill, Document, Card } from '../core/wasm.js';
 import type { Diagnostic } from '../core/wasm.js';
 
 /** Canonical contract every backend build must satisfy. One emitted output. */
@@ -84,6 +86,92 @@ export interface RenderOptions {
 	ppi?: number;
 	pages?: number[];
 	producer?: string;
+	/**
+	 * Populate {@link RenderResult.regions} with the schema-field geometry
+	 * sidecar (the same entries {@link LiveSession.regions} serves), for
+	 * consumers without a live session — e.g. overlays over a one-shot SVG
+	 * export. Defaults to `false`: exports pay no introspection cost.
+	 */
+	regions?: boolean;
+}
+
+/**
+ * How precisely a {@link CorpusHit.pos} resolved — the marker a caret UI reads
+ * to decide whether to trust the offset. Never sub-cluster: `'cluster'` is the
+ * finest, `'segment'` the floor it degrades to on origin-less ink.
+ *
+ * - `'cluster'` — `pos` is the first corpus char of the cluster under the point
+ *   (an escaped/CJK/shaping cluster floors to its first char). Place the caret
+ *   at `pos` directly.
+ * - `'segment'` — the point hit origin-less ink (list markers, numbering, a
+ *   multi-line code fence's interior), so `pos` degraded to the containing
+ *   segment's start. Treat `pos` as the selected segment, not a caret.
+ */
+export type HitGranularity = 'cluster' | 'segment';
+
+/** A click resolved to a field and USV offset into its RichText. */
+export interface CorpusHit {
+	field: string;
+	pos: number;
+	/**
+	 * Whether {@link pos} is cluster-exact or floored to the segment start
+	 * ({@link HitGranularity}). Absent when the backend does not report it.
+	 */
+	granularity?: HitGranularity;
+}
+
+/**
+ * A rendered field region: the quill schema field address (`field`) plus its
+ * geometry (`rect`) on the page. Emitted by backends that place schema fields
+ * (`pdfform` AcroForm widgets; Typst form-fields and span-tracked content —
+ * richtext bodies, `richtext[]` elements, card content fields, direct scalar
+ * references). Only fields with a schema address produce a region — a
+ * backend-only widget produces none, and the backend widget name never
+ * appears.
+ *
+ * Use it to scroll to / highlight the focused field's rect; for the click
+ * direction use {@link LiveSession.fieldAt}, which resolves a point on *any*
+ * placement, not just the first one surfaced here. Geometry only —
+ * `LiveSession.paint` already bakes every value into the raster (see
+ * {@link LiveSession}), so a region is never a compositing input.
+ *
+ * COORDINATE TRANSFORM. `rect` is in PDF points with a **bottom-left** origin.
+ *
+ * For an **HTML/CSS overlay** on a `width:100%` canvas, position hotspots as
+ * percentages of the page — they track the displayed size across DPI and pane
+ * resize for free, and only the Y axis flips:
+ *
+ * ```js
+ * const [x0, y0, x1, y1] = region.rect;            // PDF pt, bottom-left origin
+ * const left   = (x0 / pageWidthPt) * 100;         // % of page (from PageSize.widthPt)
+ * const top    = (1 - y1 / pageHeightPt) * 100;    // % — flip Y (from PageSize.heightPt)
+ * const width  = ((x1 - x0) / pageWidthPt) * 100;
+ * const height = ((y1 - y0) / pageHeightPt) * 100;
+ * ```
+ *
+ * For painting **into a raster** at `renderScale` (= `layoutScale × densityScale`),
+ * use the device-pixel form instead:
+ *
+ * ```js
+ * const left   = x0 * renderScale;
+ * const top    = (pageHeightPt - y1) * renderScale;  // flip Y
+ * ```
+ */
+export interface FieldRegion {
+	/** Quill schema field path (e.g. `"signature_block"`), not a backend widget name. */
+	field: string;
+	/** 0-based page index. */
+	page: number;
+	/** `[x0, y0, x1, y1]` in PDF points (1/72″), bottom-left origin. */
+	rect: [number, number, number, number];
+	/**
+	 * The corpus slice this box covers — USV `[start, end)` into the field's
+	 * `RichText` for content ink (one segment), absent for a scalar reference
+	 * site or widget. Consumers key segment highlights on it;
+	 * {@link LiveSession.fieldBoxes} unions same-page segments for the
+	 * whole-field box.
+	 */
+	span?: [number, number];
 }
 
 /** Canonical contract every backend build must satisfy. Result of one render. */
@@ -92,6 +180,14 @@ export interface RenderResult {
 	warnings: Diagnostic[];
 	outputFormat: OutputFormat;
 	renderTimeMs: number;
+	/**
+	 * Schema-field geometry sidecar — populated only when
+	 * {@link RenderOptions.regions} requested it; empty otherwise. The same
+	 * entries {@link LiveSession.regions} serves, for consumers without a live
+	 * session. Page indices are document-space even under a `pages` subset
+	 * render.
+	 */
+	regions: FieldRegion[];
 }
 
 /** Canonical contract every backend build must satisfy. The emittable formats. */
@@ -99,7 +195,6 @@ export type OutputFormat = 'pdf' | 'svg' | 'txt' | 'png';
 
 /**
  * Canonical contract every backend build must satisfy. Page geometry in pt.
- * @experimental Part of the iterative-session/canvas surface — see {@link RenderSession}.
  */
 export interface PageSize {
 	widthPt: number;
@@ -108,7 +203,6 @@ export interface PageSize {
 
 /**
  * Canonical contract every backend build must satisfy. Inputs to `paint`.
- * @experimental Part of the iterative-session/canvas surface — see {@link RenderSession}.
  */
 export interface PaintOptions {
 	layoutScale?: number;
@@ -117,13 +211,36 @@ export interface PaintOptions {
 
 /**
  * Canonical contract every backend build must satisfy. Output of `paint`.
- * @experimental Part of the iterative-session/canvas surface — see {@link RenderSession}.
  */
 export interface PaintResult {
-	layoutWidth: number;
+	layoutWidth: number;      // canvas.style.width target; independent of densityScale
 	layoutHeight: number;
-	pixelWidth: number;
+	pixelWidth: number;       // canvas.width the painter wrote (clamped at 16384)
 	pixelHeight: number;
+	/**
+	 * True when `MAX_BACKING_DIMENSION` forced `densityScale` down: 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.
+	 */
+	clamped: boolean;
+	/**
+	 * The `densityScale` actually applied — equal to the requested value unless
+	 * `clamped`, then reduced proportionally. `layoutScale × effectiveDensityScale`
+	 * is the scale the backing store was rasterized at.
+	 */
+	effectiveDensityScale: number;
+}
+
+/**
+ * Canonical contract every backend build must satisfy. Output of
+ * {@link LiveSession.apply}: `dirtyPages` lists the pages whose rendered
+ * content differs from the previous compile, including added pages; removed
+ * pages are implied by `pageCount`. Repaint `dirty ∩ visible`.
+ */
+export interface ChangeSet {
+	pageCount: number;
+	dirtyPages: number[];
 }
 
 /**
@@ -161,16 +278,20 @@ export interface EngineOptions {
 export declare class Engine {
 	constructor(options?: EngineOptions);
 
-	/** Render `doc` against `quill` in one shot. */
+	/**
+	 * Render `doc` against `quill` in one shot. Both handles are read
+	 * synchronously before the first await, so the caller may `free()` them as
+	 * soon as this call returns.
+	 */
 	render(quill: Quill, doc: Document, options?: RenderOptions): Promise<RenderResult>;
 
 	/**
-	 * Open an iterative render session (canvas preview / per-page paint).
-	 * @experimental Ships ahead of its first production consumer (the designed
-	 * canvas live-preview path — see `prose/canon/PREVIEW.md`). The session/paint
-	 * surface may change in any 0.x release; `render()` is the stable path.
+	 * Open a live render session (canvas preview / per-page paint / `apply`).
+	 * The `quill` and `doc` handles are read synchronously before the first
+	 * await, so the caller may `free()` them as soon as this call returns; the
+	 * caller owns the returned session and must `.free()` it.
 	 */
-	open(quill: Quill, doc: Document): Promise<RenderSession>;
+	open(quill: Quill, doc: Document): Promise<LiveSession>;
 
 	/**
 	 * Output formats `quill`'s backend can emit. An ALWAYS-free pre-render probe:
@@ -180,29 +301,126 @@ export declare class Engine {
 	supportedFormats(quill: Quill): Promise<OutputFormat[]>;
 
 	/**
-	 * Whether `quill`'s backend can paint sessions to a canvas. Same always-free
-	 * probe as `supportedFormats`: answered from the descriptor's required
-	 * `canvas` manifest, no binary load and no quill clone.
-	 * @experimental Probes the experimental session/canvas surface — see {@link RenderSession}.
+	 * Whether `quill`'s BACKEND can paint sessions to a canvas — a pre-session
+	 * ESTIMATE, not a fact about any particular compile. Same always-free probe
+	 * as `supportedFormats`: answered from the descriptor's required `canvas`
+	 * manifest, no binary load and no quill clone. Both the Typst and pdfform
+	 * backends report `true` here unconditionally; each paints a complete page
+	 * raster (see {@link LiveSession.paint}) — but a specific compile can still
+	 * refuse to paint (e.g. a 0-page document), so this can answer `true` while
+	 * the resulting {@link LiveSession.supportsCanvas} answers `false`. Gate
+	 * mounting a canvas UI on this; gate the actual `paint` call on the session's
+	 * getter once `open()` has run.
 	 */
 	supportsCanvas(quill: Quill): Promise<boolean>;
 }
 
 /**
  * Iterative render session over a compiled snapshot. `free()` when done.
- * @experimental The whole session/canvas-paint surface (`Engine.open`,
- * `RenderSession`, `PaintOptions`, `PaintResult`, `PageSize`) ships ahead of
- * its first production consumer and may change shape in any 0.x release.
- * The stable render path is `Engine.render`.
+ *
+ * CANVAS PAINT IS COMPLETE. {@link LiveSession.paint} writes a complete page
+ * raster — every piece of page content is already visible in the painted
+ * pixels, with NO compositing required by the caller. Both backends that
+ * support canvas satisfy this: Typst rasterizes its laid-out page natively;
+ * pdfform pre-flattens bound field values into the page content and rasterizes
+ * that, so field values appear in the raster on their own.
+ * {@link LiveSession.regions} carries schema-field geometry for interactive
+ * overlays / cross-navigation drawn on top of the raster; it is never needed to
+ * complete the picture.
  */
-export declare class RenderSession {
+export declare class LiveSession {
 	private constructor();
 	readonly pageCount: number;
 	readonly backendId: string;
+	/**
+	 * `true` iff `paint`/`pageSize` will succeed for THIS compile — the
+	 * authoritative answer, derived from the session's canvas seam, so it can
+	 * never disagree with what `paint` actually does. This can be `false` even
+	 * when {@link Engine.supportsCanvas} answered `true` for the same `quill`
+	 * (that probe is a pre-session backend estimate; e.g. a canvas-capable
+	 * backend compiled to a 0-page document has nothing to paint). Re-check
+	 * this getter after `open()` rather than relying on the engine hint alone.
+	 */
 	readonly supportsCanvas: boolean;
 	readonly warnings: Diagnostic[];
+	/**
+	 * Recompile the session against `doc` — the edit verb of a live preview.
+	 * Transactional: on throw every read (`render`, `paint`, `pageSize`,
+	 * `regions`) keeps serving the last-good compile, and the session recovers
+	 * on the next successful `apply`. On success reads serve the new compile;
+	 * repaint `dirtyPages ∩ visible`.
+	 */
+	apply(doc: Document): ChangeSet;
 	render(options?: RenderOptions): RenderResult;
+	/**
+	 * Schema-field geometry for this compiled session, keyed on quill schema
+	 * field path. A session-level query: no render, no byte artifact. Read it
+	 * to scroll to / highlight the focused field over a `paint`-ed canvas;
+	 * the click direction is {@link fieldAt}. Empty for backends that place
+	 * no schema fields.
+	 *
+	 * `field` is **not** unique: a content field surfaces its **first
+	 * placement** as one {@link FieldRegion} per page that placement touches
+	 * (so a highlight covers continuation pages); a scalar referenced at
+	 * several plate sites surfaces each site; tracked content plus a
+	 * `field:`-bound widget yields both, widget ordered first. Group by
+	 * `field` — every entry routes to that field. Later placements of one
+	 * content value are not enumerated; {@link fieldAt} still resolves
+	 * clicks on them.
+	 */
+	regions(): FieldRegion[];
+	/**
+	 * The whole-field highlight boxes for `field` — one union rect per page,
+	 * over the field's `span`-bearing content segments (the "highlight the
+	 * focused field" quantity). Owns the union {@link regions} leaves derived
+	 * (span-filter + per-page union), keeping `regions()` the low-level disjoint
+	 * truth, so a 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 {@link regions} rect. Reflects the
+	 * current compile, like `regions()`.
+	 */
+	fieldBoxes(field: string): FieldRegion[];
+	/**
+	 * 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 {@link FieldRegion.rect} —
+	 * from a canvas click, invert the overlay transform documented there:
+	 * `x = clickPx.x / renderScale`,
+	 * `y = pageHeightPt - clickPx.y / renderScale`. Unlike {@link regions},
+	 * *every* placement answers, not just the first.
+	 */
+	fieldAt(page: number, x: number, y: number): string | undefined;
+	/**
+	 * Fine-grained click → corpus position (caret placement). Same PDF-point
+	 * space as {@link fieldAt}; `undefined` off all content ink.
+	 */
+	positionAt(page: number, x: number, y: number): CorpusHit | undefined;
+	/** Corpus position → caret rect — reverse of {@link positionAt}. */
+	locate(field: string, pos: number): FieldRegion | undefined;
+	/** Page geometry in points (1/72″). Report-only; the painter sizes the canvas. */
 	pageSize(page: number): PageSize;
+	/**
+	 * Paint `page` into a 2D canvas context, sizing the backing store itself
+	 * (it owns `canvas.width`/`height`; the caller owns `canvas.style.*`). The
+	 * painted raster is COMPLETE — all page content visible, no caller-side
+	 * compositing (Typst rasterizes natively; pdfform rasterizes its
+	 * pre-flattened page). Effective rasterization scale is
+	 * `layoutScale × densityScale`, clamped so neither backing dimension exceeds
+	 * 16384 px — {@link PaintResult.clamped} reports the clamp and
+	 * {@link PaintResult.effectiveDensityScale} the density actually applied.
+	 *
+	 * The write is a whole-backing-store `putImageData`, which bypasses the 2D
+	 * context transform, `globalAlpha`, and clip: the painter owns the entire
+	 * canvas, so give each visible page its own `` element. You cannot
+	 * paint two pages into one canvas, paint into a sub-rect, or apply a context
+	 * transform through this call — the raster is complete precisely so you never
+	 * need to. Keep the per-page canvases alive while their pages stay near the
+	 * viewport: each `paint` re-rasterizes from scratch, so reusing (pooling) a
+	 * canvas across pages on scroll re-runs a full render, whereas an idle canvas
+	 * retains its pixels for free.
+	 */
 	paint(
 		ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
 		page: number,
@@ -210,3 +428,91 @@ export declare class RenderSession {
 	): PaintResult;
 	free(): void;
 }
+
+// ── Typed writer — the tier-1 front door ────────────────────────────────────
+
+// `quill.writer(doc)` is patched onto the re-exported `Quill` prototype (the
+// class is re-exported verbatim, so the method is declared by merging into the
+// core module's `Quill` rather than redeclaring the class).
+declare module '../core/wasm.js' {
+	interface Quill {
+		/**
+		 * Bind this quill's schema to `doc` for typed writes — the documented
+		 * front door, mirroring core's `quill.writer(&mut doc)`. The schema grants
+		 * the typing, so the quill is the factory. The returned writer holds both
+		 * handles by reference and owns neither (nothing to `free()`); it is
+		 * ephemeral by convention — bind, write, discard.
+		 */
+		writer(doc: Document): DocumentWriter;
+	}
+}
+
+/**
+ * A `Document` bound to its `Quill` for typed writes — the tier-1 default,
+ * constructed via {@link Quill.writer}. Speaks names, values, and markdown; a
+ * consumer here never meets an `Addr`, a corpus object, or a `Delta`. Bare
+ * `set` / `setAll` / `setBody` / `addCard` / `card(i).set` instead of threading
+ * the `quill` handle through every `commit*` call. Holds both handles by
+ * reference and owns neither — nothing to `free()`.
+ *
+ * Typed commit is the default whenever a quill is in hand: it resolves each
+ * field's schema type and strict-commits it, throwing `UnknownField` for a name
+ * the schema does not declare — on the typed path an undeclared name is a typo,
+ * not a fallback. The raw `Document.setField` / `setFields` verbs remain the
+ * deliberate quill-free primitive (standalone data, storage/migration infra, or
+ * holding not-yet-conforming in-progress input).
+ */
+export declare class DocumentWriter {
+	constructor(quill: Quill, doc: Document);
+	/** The bound document — the instance passed in, mutated in place. */
+	readonly document: Document;
+	/**
+	 * Typed-commit one main-card field (strict coerce, mismatch throws now).
+	 * Throws `UnknownField` for a name the schema does not declare.
+	 */
+	set(name: string, value: unknown): void;
+	/**
+	 * Typed-commit several main-card fields atomically — nothing is applied on
+	 * error (throws a {@link QuillmarkError} carrying one diagnostic per
+	 * offending field, including an `UnknownField` for each undeclared name).
+	 */
+	setAll(fields: Record<string, unknown>): void;
+	/**
+	 * Set the main body from markdown (edit semantics: anchors rebase), discarding
+	 * the delta — the receipt-free body write. Use `doc.revise({}, md)` for the
+	 * `Delta` receipt.
+	 */
+	setBody(markdown: string): void;
+	/**
+	 * Build a composable card of `kind`, typed-commit `fields` onto it, set its
+	 * body from optional markdown, and append it — the fused `makeCard` + typed
+	 * commit + `pushCard`. Transactional: a rejected field (throws a per-field
+	 * diagnostic bundle) or an invalid kind/body leaves the document untouched.
+	 */
+	addCard(kind: string, fields?: Record<string, unknown>, body?: string): void;
+	/** Remove the composable card at `index`, returning it (or `undefined`). */
+	removeCard(index: number): Card | undefined;
+	/**
+	 * A {@link CardWriter} for the composable card at `index`. Index validity is
+	 * checked lazily at commit time, so this never throws. The cursor is
+	 * ephemeral — a `removeCard`/`addCard` between binding and writing silently
+	 * retargets it; for durable addressing stamp `$id` and re-resolve at write.
+	 */
+	card(index: number): CardWriter;
+}
+
+/**
+ * A composable card bound to its `Quill` for typed writes, from
+ * {@link DocumentWriter.card}. Same verbs as {@link DocumentWriter}, targeting
+ * the card at its bound index; each write throws `IndexOutOfRange` if that index
+ * is out of range.
+ */
+export declare class CardWriter {
+	constructor(quill: Quill, doc: Document, index: number);
+	/** The bound card index. */
+	readonly index: number;
+	set(name: string, value: unknown): void;
+	setAll(fields: Record<string, unknown>): void;
+	/** Set this card's body from markdown (edit semantics), discarding the delta. */
+	setBody(markdown: string): void;
+}