@quillmark/wasm 0.94.0 → 0.96.0

package/core/wasm_bg.wasm.d.ts

@@ -3,69 +3,69 @@
 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__addCard: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void;
+export const document__commitField: (a: number, b: number, c: number, d: number, e: number) => void;
+export const document__commitFields: (a: number, b: number, c: number, d: number, e: number) => void;
+export const document__readerGet: (a: number, b: number, c: number, d: number) => void;
+export const document__reviseField: (a: number, b: number, c: number, d: number, e: number, f: 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_card: (a: number, b: number, c: number) => void;
 export const document_cardCount: (a: number) => number;
+export const document_cardIndexById: (a: number, b: number, c: 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_get: (a: number, b: number, c: number) => void;
+export const document_getExt: (a: number, b: number, c: number) => void;
+export const document_getExtNamespace: (a: number, b: number, c: number, d: number, e: number) => void;
+export const document_getMarkdown: (a: number, b: number, c: 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_isFill: (a: number, b: number, c: 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;
 export const document_removeCard: (a: number, b: number, c: number) => void;
-export const document_removeCardExt: (a: number, b: number, c: number) => void;
-export const document_removeCardExtNamespace: (a: number, b: number, c: number, d: number, e: number) => void;
-export const document_removeCardField: (a: number, b: number, c: number, d: number, e: number) => void;
-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_removeExt: (a: number, b: number, c: number) => void;
+export const document_removeExtNamespace: (a: number, b: number, c: number, d: number, e: number) => void;
+export const document_removeField: (a: number, b: number, c: 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, 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_seedOverlay: (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_storeExt: (a: number, b: number, c: number, d: number) => void;
+export const document_storeExtNamespace: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+export const document_storeField: (a: number, b: number, c: number, d: number) => void;
+export const document_storeFields: (a: number, b: number, c: number, d: number) => void;
+export const document_storeFill: (a: number, b: number, c: number, d: number) => void;
+export const document_storeSeedNamespace: (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_warnings: (a: number, b: number) => void;
 export const exportMarkdown: (a: number, b: number) => void;
+export const formatDocPath: (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 parseDocPath: (a: number, b: number, c: 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;
 export const quill_metadata: (a: number, b: number) => void;
+export const quill_resolve: (a: number, b: number, c: number) => void;
 export const quill_schema: (a: number, b: number) => void;
 export const quill_seedCard: (a: number, b: number, c: number, d: number, e: number) => void;
 export const quill_seedDocument: (a: number) => number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quillmark/wasm",
-  "version": "0.94.0",
+  "version": "0.96.0",
   "description": "WebAssembly bindings for Quillmark, a schema-driven document engine",
   "type": "module",
   "license": "MIT OR Apache-2.0",

package/runtime/runtime.d.ts

@@ -14,8 +14,23 @@
 // 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.
+// The document-free content codec, re-exported from the core build.
 export { importMarkdown, exportMarkdown, rebase, mapPos } from '../core/wasm.js';
+// The document-model path parser/serializer — route on `Diagnostic.path`
+// segments instead of regexing the string.
+export { parseDocPath, formatDocPath } 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 {
@@ -30,9 +45,53 @@ export type {
 	QuillCardBody,
 	QuillFieldUi,
 	QuillCardUi,
+	QuillGroupUi,
 	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,
+	TableProps,
+	ImageProps,
+	TableCell,
+	CardInput,
+	PathStep,
+	Addr,
+	CardAddr,
+	Delta,
+	Assoc,
+	LineOp,
+	MarkOp,
+	ChangeBundle,
+	DocPathSeg
+} from '../core/wasm.js';
+
+// The resolved-value view — the return shape of `quill.resolve(doc)`. Value
+// + source rung per declared field (the body rides the fields map under
+// `$body`); diagnostics stay `quill.validate`, guidance stays `quill.schema`.
+// Declared in the core build's generated `.d.ts` via a
+// `typescript_custom_section`; re-exported here so the single public entry
+// point names them.
+export type {
+	FieldSource,
+	ResolvedField,
+	ResolvedMain,
+	ResolvedCard,
+	Resolved
+} from '../core/wasm.js';
+
 // ── Error contract ──────────────────────────────────────────────────────────
 
 /**
@@ -96,11 +155,11 @@ export interface RenderOptions {
 }
 
 /**
- * How precisely a {@link CorpusHit.pos} resolved — the marker a caret UI reads
+ * 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 corpus char of the cluster under the point
+ * - `'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
@@ -109,8 +168,12 @@ export interface RenderOptions {
  */
 export type HitGranularity = 'cluster' | 'segment';
 
-/** A click resolved to a field and USV offset into its RichText. */
-export interface CorpusHit {
+/** A click resolved to a field and USV offset into its Content. */
+export interface ContentHit {
+	/**
+	 * The field's canonical `DocPath` address (`parseDocPath`-routable) — the same
+	 * address {@link LiveSession.fieldAt} returns for that point.
+	 */
 	field: string;
 	pos: number;
 	/**
@@ -121,8 +184,8 @@ export interface CorpusHit {
 }
 
 /**
- * A rendered field region: the quill schema field address (`field`) plus its
- * geometry (`rect`) on the page. Emitted by backends that place schema fields
+ * A rendered field region: the canonical `DocPath` 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
@@ -158,15 +221,20 @@ export interface CorpusHit {
  * ```
  */
 export interface FieldRegion {
-	/** Quill schema field path (e.g. `"signature_block"`), not a backend widget name. */
+	/**
+	 * The field's canonical `DocPath` address (`parseDocPath`-routable), not a
+	 * backend widget name: `main.signature_block` for a main field,
+	 * `cards.<kind>[<i>].signature_block` for a card field (`cards[<i>].…` when the
+	 * card's kind is unknown).
+	 */
 	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
+	 * 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.
@@ -353,11 +421,11 @@ export declare class LiveSession {
 	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.
+	 * Schema-field geometry for this compiled session, keyed on the canonical
+	 * `DocPath` address (`parseDocPath`-routable). 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
@@ -370,9 +438,10 @@ export declare class LiveSession {
 	 */
 	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
+	 * The whole-field highlight boxes for `field` (a canonical `DocPath` address,
+	 * as {@link regions} keys) — 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`
@@ -383,21 +452,25 @@ export declare class LiveSession {
 	/**
 	 * 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:
+	 * document and get back the canonical `DocPath` field address
+	 * (`parseDocPath`-routable) 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
+	 * 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): CorpusHit | undefined;
-	/** Corpus position → caret rect — reverse of {@link positionAt}. */
+	positionAt(page: number, x: number, y: number): ContentHit | undefined;
+	/**
+	 * Content position → caret rect — reverse of {@link positionAt}. `field` is a
+	 * canonical `DocPath` address (`parseDocPath`-routable), as {@link regions} keys.
+	 */
 	locate(field: string, pos: number): FieldRegion | undefined;
 	/** Page geometry in points (1/72″). Report-only; the painter sizes the canvas. */
 	pageSize(page: number): PageSize;
@@ -429,7 +502,7 @@ export declare class LiveSession {
 	free(): void;
 }
 
-// ── Typed writer — the tier-1 front door ────────────────────────────────────
+// ── 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
@@ -444,21 +517,30 @@ declare module '../core/wasm.js' {
 		 * 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.reader(&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.
+		 */
+		reader(doc: Document): DocumentReader;
 	}
 }
 
 /**
- * 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()`.
+ * 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.setField` / `setFields` verbs remain the
+ * 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).
  */
@@ -483,13 +565,23 @@ export declare class DocumentWriter {
 	 * `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 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.
+	 * 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): void;
+	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;
 	/**
@@ -511,8 +603,84 @@ 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
+ * surface, constructed via {@link Quill.reader} 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 DocumentReader {
+	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 CardReader} 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): CardReader;
+}
+
+/**
+ * A composable card bound to its `Quill` for interpreted reads, from
+ * {@link DocumentReader.card}. Same verbs as {@link DocumentReader}, reading the card
+ * at its bound index; each read throws `IndexOutOfRange` if that index is out of
+ * range.
+ */
+export declare class CardReader {
+	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 DocumentReader.getBody}. */
+	getBody(): string;
 }