@quillmark/wasm 0.92.1 → 0.95.1

package/runtime/runtime.d.ts

@@ -14,6 +14,20 @@
 // 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 content codec, re-exported from the core build.
+export { importMarkdown, exportMarkdown, rebase, mapPos } from '../core/wasm.js';
+
+import type { CardAddr } from '../core/wasm.js';
+
+/**
+ * The main card's address — the default target of the card-scoped verbs
+ * (`storeFields` / `storeExt` / `commitFields` / …). A named, {@link CardAddr}-typed
+ * alias for the empty address `{}`, so a main-card write names its target:
+ * `doc.storeFields(MAIN_CARD_ADDR, fields)`. It IS `{}` (frozen at runtime), a
+ * pure alias — `{}` and `undefined` stay equally valid. A card selector only,
+ * never a field address.
+ */
+export declare const MAIN_CARD_ADDR: CardAddr;
 
 // Core-build types consumers read off `Quill`/`Document`.
 export type {
@@ -31,6 +45,31 @@ export type {
 	QuillMetadata
 } from '../core/wasm.js';
 
+// Content edit vocabulary — the op-grained content model `Document`'s methods
+// speak (`applyChange(addr, bundle)`, `install(addr, rt)`, `revise(…) => Delta`).
+// Declared in the core build; re-exported here so the single public entry point
+// names every type its own re-exported surface already references — `Card.body`
+// is a `Content`, `PayloadItem.nestedFills` a `PathStep[][]`, `CardInput.body` a
+// `Content | string` — rather than forcing consumers to derive them structurally
+// off the `Document` handle. The content write path (a ProseMirror↔content codec)
+// must name all of them; they are its correctness core, not edge types.
+export type {
+	Content,
+	ContentLine,
+	ContentContainer,
+	ContentMark,
+	ContentIsland,
+	CardInput,
+	PathStep,
+	Addr,
+	CardAddr,
+	Delta,
+	Assoc,
+	LineOp,
+	MarkOp,
+	ChangeBundle
+} from '../core/wasm.js';
+
 // ── Error contract ──────────────────────────────────────────────────────────
 
 /**
@@ -68,7 +107,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 +123,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 ContentHit.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 content 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 Content. */
+export interface ContentHit {
+	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 content slice this box covers — USV `[start, end)` into the field's
+	 * `Content` 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 +217,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 +232,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 +240,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 +248,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 +315,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 +338,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 → content position (caret placement). Same PDF-point
+	 * space as {@link fieldAt}; `undefined` off all content ink.
+	 */
+	positionAt(page: number, x: number, y: number): ContentHit | undefined;
+	/** Content 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 +465,186 @@ export declare class RenderSession {
 	): PaintResult;
 	free(): void;
 }
+
+// ── Typed writer — the schema-bound 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;
+		/**
+		 * Bind this quill's schema to `doc` for interpreted reads — the read twin of
+		 * {@link Quill.writer}, mirroring core's `quill.view(&doc)`. Each field is
+		 * read by its declared type (a richtext field to markdown, every other type
+		 * verbatim) with schema authority, so a name the schema does not declare
+		 * throws rather than reading back `undefined`. Holds both handles by
+		 * reference and owns neither (nothing to `free()`); ephemeral by convention —
+		 * bind, read, discard.
+		 */
+		view(doc: Document): DocumentView;
+	}
+}
+
+/**
+ * A `Document` bound to its `Quill` for typed writes — the schema-bound writer,
+ * constructed via {@link Quill.writer}. Speaks names, values, and markdown. Bare
+ * `set` / `setAll` / `setBody` / `reviseField` / `addCard` / `card(i).set`
+ * instead of threading the `quill` handle through the underscored ABI. 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.storeField` / `storeFields` 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;
+	/**
+	 * Revise the richtext main-card field `name` from markdown — typed *and*
+	 * anchor-preserving. Surviving anchors rebase, then the diffed result is
+	 * schema-conformed (`richtext(inline)` rejects a multi-block result). Throws
+	 * `UnknownField` for a name the schema does not declare. Returns the `Delta`.
+	 */
+	reviseField(name: string, markdown: string): Delta;
+	/**
+	 * Build a composable card of `kind`, typed-commit `fields` onto it, set its
+	 * body from optional markdown, and place it — the fused `makeCard` + typed
+	 * commit + insertion. `at` picks the position: omitted appends, a number
+	 * inserts at that index, so a positioned typed insert is one atomic call
+	 * rather than `addCard` + `moveCard`. Transactional: a rejected field (throws
+	 * a per-field diagnostic bundle) or an invalid kind/body/position leaves the
+	 * document untouched.
+	 */
+	addCard(kind: string, fields?: Record<string, unknown>, body?: string, at?: number): 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;
+	/**
+	 * The bound card's `$kind` (empty string when it carries none), read through
+	 * the document — mirrors core `CardWriter::kind()`. Throws `IndexOutOfRange`
+	 * if the bound index is out of range.
+	 */
+	readonly kind: string;
+	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;
+	/**
+	 * Revise the richtext field `name` on this card from markdown — typed *and*
+	 * anchor-preserving; the card twin of {@link DocumentWriter.reviseField}.
+	 * Throws `UnknownField` for an undeclared name and `IndexOutOfRange` if the
+	 * bound index is out of range. Returns the `Delta`.
+	 */
+	reviseField(name: string, markdown: string): Delta;
+}
+
+/**
+ * A `Document` bound to its `Quill` for interpreted reads — the schema-plane read
+ * view, constructed via {@link Quill.view} and the read twin of
+ * {@link DocumentWriter}. One `get` reads each field by its declared type: a
+ * richtext field to its markdown projection, a plaintext field to its literal
+ * text, every other type its canonical value verbatim. Holds both handles by
+ * reference and owns neither — nothing to `free()`.
+ *
+ * The schema authority is the point: unlike the quill-free transport `Document.get`,
+ * a name the schema does not declare throws `UnknownField` (a typo) rather than
+ * reading back `undefined`, and a content field holding a value that does not
+ * decode throws `FieldRichtextDecode`. A field's markdown lives here, not on the
+ * body-only `Document.getMarkdown`. The body read stays quill-free (a body's type
+ * is a format fact) and never throws.
+ */
+export declare class DocumentView {
+	constructor(quill: Quill, doc: Document);
+	/** The bound document — the instance passed in. */
+	readonly document: Document;
+	/**
+	 * Read the value at `addr`, interpreted by its declared type: a richtext field
+	 * to markdown, every other type verbatim. A bare string is `Addr` shorthand for
+	 * `{ field }`; an absent `addr.field` reads the body markdown. `undefined` for
+	 * an absent field; throws `UnknownField` for a name the schema does not declare,
+	 * `FieldRichtextDecode` for a richtext field holding an undecodable value, and
+	 * `IndexOutOfRange` for a bad `addr.card`.
+	 */
+	get(addr: Addr | string): unknown;
+	/** The main body's markdown — the quill-free body read. Equals `get({})`. */
+	getBody(): string;
+	/**
+	 * A {@link CardView} for the composable card at `index`. Index validity is
+	 * checked lazily at read time, so this never throws. The cursor is ephemeral —
+	 * a `removeCard`/`addCard` between binding and reading silently retargets it.
+	 */
+	card(index: number): CardView;
+}
+
+/**
+ * A composable card bound to its `Quill` for interpreted reads, from
+ * {@link DocumentView.card}. Same verbs as {@link DocumentView}, reading the card
+ * at its bound index; each read throws `IndexOutOfRange` if that index is out of
+ * range.
+ */
+export declare class CardView {
+	constructor(quill: Quill, doc: Document, index: number);
+	/** The bound card index. */
+	readonly index: number;
+	/**
+	 * The bound card's `$kind` (empty string when it carries none). Throws
+	 * `IndexOutOfRange` if the bound index is out of range.
+	 */
+	readonly kind: string;
+	/**
+	 * Read the field `name` on this card, interpreted by its declared type.
+	 * `undefined` when absent; throws `UnknownField` for an undeclared name and
+	 * `IndexOutOfRange` for a bad index.
+	 */
+	get(name: string): unknown;
+	/** This card's body markdown — the card twin of {@link DocumentView.getBody}. */
+	getBody(): string;
+}