@quillmark/wasm 0.94.0 → 0.95.1

package/core/wasm_bg.wasm.d.ts

@@ -3,57 +3,54 @@
 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__reviseField: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+export const document__viewGet: (a: number, b: number, c: number, d: 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;

package/package.json

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

package/runtime/runtime.d.ts

@@ -14,9 +14,21 @@
 // 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';
 
+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 {
 	Card,
@@ -33,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 ──────────────────────────────────────────────────────────
 
 /**
@@ -96,11 +133,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 +146,8 @@ 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 {
 	field: string;
 	pos: number;
 	/**
@@ -165,8 +202,8 @@ export interface FieldRegion {
 	/** `[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.
@@ -393,11 +430,11 @@ export declare class LiveSession {
 	 */
 	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}. */
 	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 +466,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 +481,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.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 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 +529,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 +567,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
+ * 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;
 }