@quillmark/wasm 0.95.1 → 0.97.0

package/runtime/runtime.d.ts

@@ -16,6 +16,9 @@
 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';
+// 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';
 
@@ -42,6 +45,7 @@ export type {
 	QuillCardBody,
 	QuillFieldUi,
 	QuillCardUi,
+	QuillGroupUi,
 	QuillMetadata
 } from '../core/wasm.js';
 
@@ -59,6 +63,9 @@ export type {
 	ContentContainer,
 	ContentMark,
 	ContentIsland,
+	TableProps,
+	ImageProps,
+	TableCell,
 	CardInput,
 	PathStep,
 	Addr,
@@ -67,7 +74,23 @@ export type {
 	Assoc,
 	LineOp,
 	MarkOp,
-	ChangeBundle
+	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 is a `body` sibling on its card,
+// never a row in `fields`); 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 ──────────────────────────────────────────────────────────
@@ -98,6 +121,37 @@ export interface QuillmarkError extends Error {
  */
 export declare function isQuillmarkError(e: unknown): e is QuillmarkError;
 
+// ── Open-set discriminant guards ────────────────────────────────────────────
+// `ContentIsland.type` / `ContentMark.type` are open sets — each union has a
+// residual `{ type: string; … }` arm, so a bare discriminant check never narrows
+// the payload (TS keeps the residual arm live, since a `string` can equal the
+// literal). These guards are the checked narrowing path for the pinned arms; an
+// unrecognized `type` fails every guard and keeps its opaque payload. Only the
+// payload-carrying arms get a guard — the bare marks
+// (`strong`/`emph`/`underline`/`strike`/`code`) narrow to nothing.
+
+import type { ContentIsland, TableProps, ImageProps, ContentMark } from '../core/wasm.js';
+
+/** Narrow a {@link ContentIsland} to the pinned `table` arm (`props: TableProps`). */
+export declare function isTableIsland(
+	island: ContentIsland
+): island is ContentIsland & { type: 'table'; props: TableProps };
+
+/** Narrow a {@link ContentIsland} to the pinned `image` arm (`props: ImageProps`). */
+export declare function isImageIsland(
+	island: ContentIsland
+): island is ContentIsland & { type: 'image'; props: ImageProps };
+
+/** Narrow a {@link ContentMark} to the `link` arm (carries `url`). */
+export declare function isLinkMark(
+	mark: ContentMark
+): mark is ContentMark & { type: 'link'; url: string };
+
+/** Narrow a {@link ContentMark} to the `anchor` arm (carries `id`). */
+export declare function isAnchorMark(
+	mark: ContentMark
+): mark is ContentMark & { type: 'anchor'; id: string };
+
 // ── Canonical render-side types ─────────────────────────────────────────────
 // These are the BACKEND-NEUTRAL render contract of the plural-backend API. They
 // are defined HERE (not re-exported from one private backend) because no single
@@ -148,6 +202,10 @@ export type HitGranularity = 'cluster' | 'segment';
 
 /** 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;
 	/**
@@ -158,8 +216,8 @@ export interface ContentHit {
 }
 
 /**
- * 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
@@ -195,7 +253,12 @@ export interface ContentHit {
  * ```
  */
 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;
@@ -390,11 +453,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
@@ -407,9 +470,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`
@@ -420,10 +484,11 @@ 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.
@@ -434,7 +499,10 @@ export declare class LiveSession {
 	 * 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}. */
+	/**
+	 * 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;
@@ -483,14 +551,14 @@ declare module '../core/wasm.js' {
 		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
+		 * {@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.
 		 */
-		view(doc: Document): DocumentView;
+		reader(doc: Document): DocumentReader;
 	}
 }
 
@@ -588,20 +656,20 @@ export declare class CardWriter {
 
 /**
  * A `Document` bound to its `Quill` for interpreted reads — the schema-plane read
- * view, constructed via {@link Quill.view} and the read twin of
+ * 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`,
+ * The schema authority is the point: unlike the quill-free transport `Document.getStored`,
  * 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 {
+export declare class DocumentReader {
 	constructor(quill: Quill, doc: Document);
 	/** The bound document — the instance passed in. */
 	readonly document: Document;
@@ -617,20 +685,20 @@ export declare class DocumentView {
 	/** 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
+	 * 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): CardView;
+	card(index: number): CardReader;
 }
 
 /**
  * A composable card bound to its `Quill` for interpreted reads, from
- * {@link DocumentView.card}. Same verbs as {@link DocumentView}, reading the card
+ * {@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 CardView {
+export declare class CardReader {
 	constructor(quill: Quill, doc: Document, index: number);
 	/** The bound card index. */
 	readonly index: number;
@@ -645,6 +713,6 @@ export declare class CardView {
 	 * `IndexOutOfRange` for a bad index.
 	 */
 	get(name: string): unknown;
-	/** This card's body markdown — the card twin of {@link DocumentView.getBody}. */
+	/** This card's body markdown — the card twin of {@link DocumentReader.getBody}. */
 	getBody(): string;
 }

package/runtime/runtime.js

@@ -63,6 +63,10 @@ export { Quill, Document, init };
 // projection), `importMarkdown`, and the position-mapping pair (`rebase`,
 // `mapPos`).
 export { importMarkdown, exportMarkdown, rebase, mapPos } from '../core/wasm.js';
+// The document-model path parser/serializer: `parseDocPath(str) => DocPathSeg[]`
+// and its inverse `formatDocPath`, so a consumer routes on `Diagnostic.path`
+// segments instead of reverse-engineering the grammar.
+export { parseDocPath, formatDocPath } from '../core/wasm.js';
 
 // ── The main-card address ───────────────────────────────────────────────────
 /**
@@ -94,6 +98,49 @@ export function isQuillmarkError(e) {
 	return e instanceof Error && Array.isArray(/** @type {any} */ (e).diagnostics);
 }
 
+// ── Open-set discriminant guards ────────────────────────────────────────────
+// `ContentIsland.type` and `ContentMark.type` are OPEN sets: each union carries
+// a residual `{ type: string; … }` arm, so a bare `x.type === 'table'` check
+// never narrows the payload — TS keeps the residual arm live (a `string` can be
+// `'table'`), leaving `props` / the mark payload opaque at every consumer. These
+// are the checked narrowing path: on the true branch the payload's pinned shape
+// is asserted. Only the payload-carrying arms get a guard — an island always
+// carries `props`, a `link` mark carries `url`, an `anchor` mark carries `id`;
+// the bare marks (`strong`/`emph`/`underline`/`strike`/`code`) narrow to
+// nothing. An unrecognized `type` fails every guard and keeps its opaque payload.
+
+/**
+ * @param {import('../core/wasm.js').ContentIsland} island
+ * @returns {island is import('../core/wasm.js').ContentIsland & { type: 'table'; props: import('../core/wasm.js').TableProps }}
+ */
+export function isTableIsland(island) {
+	return island.type === 'table';
+}
+
+/**
+ * @param {import('../core/wasm.js').ContentIsland} island
+ * @returns {island is import('../core/wasm.js').ContentIsland & { type: 'image'; props: import('../core/wasm.js').ImageProps }}
+ */
+export function isImageIsland(island) {
+	return island.type === 'image';
+}
+
+/**
+ * @param {import('../core/wasm.js').ContentMark} mark
+ * @returns {mark is import('../core/wasm.js').ContentMark & { type: 'link'; url: string }}
+ */
+export function isLinkMark(mark) {
+	return mark.type === 'link';
+}
+
+/**
+ * @param {import('../core/wasm.js').ContentMark} mark
+ * @returns {mark is import('../core/wasm.js').ContentMark & { type: 'anchor'; id: string }}
+ */
+export function isAnchorMark(mark) {
+	return mark.type === 'anchor';
+}
+
 // Backend builds are NEVER statically imported here — that would pull a
 // multi-MB binary into the eager graph and defeat lazy loading. Each entry is a
 // DESCRIPTOR: `load` is a thunk returning a dynamic `import()` (a backend's
@@ -749,11 +796,11 @@ Quill.prototype.writer = function writer(doc) {
 	return new DocumentWriter(this, doc);
 };
 
-// ── Typed-reader sugar: the schema-plane read view ──────────────────────────
-// The read twin of the writer above. The transport `Document.get` is schema-free
+// ── Typed-reader sugar: the schema-plane read surface ──────────────────────────
+// The read twin of the writer above. The transport `Document.getStored` is schema-free
 // — a `Document` cannot say which fields are richtext, so an unknown field name
 // reads back `undefined` rather than as the typo it is. Binding the quill's
-// schema (`_viewGet` takes the handle, like the `commit*` verbs) lets one `get`
+// schema (`_readerGet` takes the handle, like the `commit*` verbs) lets one `get`
 // interpret by declared type: a richtext field to markdown, a plaintext field to
 // its literal text, every other type verbatim, and an unknown name throws
 // `UnknownField`. A field's markdown lives here, not on the body-only
@@ -762,11 +809,11 @@ Quill.prototype.writer = function writer(doc) {
 
 /**
  * A {@link Document} bound to its {@link Quill} for typed reads — the JS twin of
- * Rust's `quill.view(&doc)` and the read counterpart of {@link DocumentWriter}.
+ * Rust's `quill.reader(&doc)` and the read counterpart of {@link DocumentWriter}.
  * Reads target the main card; use {@link card} for a composable card. Holds both
  * handles by reference and owns neither, so there is nothing to `free()`.
  */
-export class DocumentView {
+export class DocumentReader {
 	#quill;
 	#doc;
 	/**
@@ -792,7 +839,7 @@ export class DocumentView {
 	 * @returns {unknown}
 	 */
 	get(addr) {
-		return this.#doc._viewGet(this.#quill, addr);
+		return this.#doc._readerGet(this.#quill, addr);
 	}
 	/**
 	 * The main body's markdown — the quill-free body read (a body's type is a
@@ -800,28 +847,28 @@ export class DocumentView {
 	 * @returns {string}
 	 */
 	getBody() {
-		return this.#doc._viewGet(this.#quill, {});
+		return this.#doc._readerGet(this.#quill, {});
 	}
 	/**
-	 * A {@link CardView} bound to the composable card at `index`. Index validity
+	 * A {@link CardReader} bound to the composable card at `index`. Index validity
 	 * is checked lazily by the underlying read (it throws `IndexOutOfRange` at read
 	 * time), so constructing one never throws. Ephemeral like the writer cursor —
 	 * it holds `index`, not the card, so a `removeCard`/`addCard` between binding
 	 * and reading silently retargets it.
 	 * @param {number} index
-	 * @returns {CardView}
+	 * @returns {CardReader}
 	 */
 	card(index) {
-		return new CardView(this.#quill, this.#doc, index);
+		return new CardReader(this.#quill, this.#doc, index);
 	}
 }
 
 /**
  * A single composable card bound to its {@link Quill} for typed reads, from
- * {@link DocumentView.card}. Same `get` / `getBody` verbs as
- * {@link DocumentView}, reading the card at its bound index.
+ * {@link DocumentReader.card}. Same `get` / `getBody` verbs as
+ * {@link DocumentReader}, reading the card at its bound index.
  */
-export class CardView {
+export class CardReader {
 	#quill;
 	#doc;
 	#index;
@@ -855,30 +902,30 @@ export class CardView {
 	 * @returns {unknown}
 	 */
 	get(name) {
-		return this.#doc._viewGet(this.#quill, { card: this.#index, field: name });
+		return this.#doc._readerGet(this.#quill, { card: this.#index, field: name });
 	}
 	/**
-	 * This card's body markdown — the card twin of {@link DocumentView.getBody}.
+	 * This card's body markdown — the card twin of {@link DocumentReader.getBody}.
 	 * @returns {string}
 	 */
 	getBody() {
-		return this.#doc._viewGet(this.#quill, { card: this.#index });
+		return this.#doc._readerGet(this.#quill, { card: this.#index });
 	}
 }
 
-// ── `quill.view(doc)` — the schema-plane read front door ─────────────────────
+// ── `quill.reader(doc)` — the schema-plane read front door ─────────────────────
 // The read twin of `quill.writer(doc)`, patched onto the same re-exported `Quill`
 // prototype (the `Quill === CoreQuill` identity invariant holds — this only adds
-// a method constructing the pure-JS view, which owns no WASM handle).
+// a method constructing the pure-JS reader, which owns no WASM handle).
 /**
- * A {@link DocumentView} binding this quill's schema to `doc` for interpreted
- * reads — the read front door, mirroring core's `quill.view(&doc)`. The returned
- * view holds both handles by reference and owns neither, so there is nothing to
+ * A {@link DocumentReader} binding this quill's schema to `doc` for interpreted
+ * reads — the read front door, mirroring core's `quill.reader(&doc)`. The returned
+ * reader holds both handles by reference and owns neither, so there is nothing to
  * `free()`. Ephemeral by convention: bind, read, discard.
  * @this {Quill}
  * @param {Document} doc the document to read, held by reference (not owned)
- * @returns {DocumentView}
+ * @returns {DocumentReader}
  */
-Quill.prototype.view = function view(doc) {
-	return new DocumentView(this, doc);
+Quill.prototype.reader = function reader(doc) {
+	return new DocumentReader(this, doc);
 };