@quillmark/wasm 0.95.1 → 0.96.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## v0.96.0 - 2026-07-23
+
+- docs(spec): keep plate JSON out of the markdown spec
+- docs(core): fix doc-lint and mkdocs-strict CI failures
+- core: gate plate $body at construction, not post-hoc strip
+- docs(core): trim duplicated $kind comment in to_plate_json
+- core: plate $body/$kind absent on undefined (#1030)
+- core: compile_data conforms once — ladder consumes the gate's coerced output
+- rename: view()→reader(), fieldStates()→resolve() across core and bindings
+- core: one shared resolver behind compile_data and field_states
+- content: dense-prose + simplify pass on the #1002 decision
+- content: decide island-id ↔ content-hash determinism (#1002)
+- Re-key runtime.d.ts geometry docs onto the canonical DocPath form
+- Canon lint cleanup: dedup spine restatements, fold CI job, shape-based anchor check
+- Canon docs infra: single-source the spine in prose/README.md, enforce in CI
+- release: strip the seed coverage comment by construction; fix blank-notes fallback
+- Reject signed years in date/datetime grammar (#1008)
+- core: silence unused_must_use on Payload::insert in tests
+- DocPath: root every main-field address at `main`
+- fieldStates: ordered rows carrying `name`, body as a sibling (drop `$body`)
+- Descope phase 5: cut the conformance suite, contractVersion, and phase-plan docs
+- Contract phase 5 — conformance suite + contractVersion
+- Contract phase 4 — typed-surface completion: QuillCardUi.groups + island props
+- Phase 3 doc: separate tested value-parity from structural source-rung claim
+- Fix rustdoc intra-doc links on EditError::doc_path / RenderedRegion.field
+- simplify pass: hoist kinds vec, unify render-sidecar addressing, merge doc_path arms
+- Contract phases 2–3: geometry DocPath unification, mutator paths, lean fieldStates
+- Repivot the contract rework around consumer evidence (phase-doc rewrite)
+- Qualify card fill diagnostics by schema-declared kind only (#1014)
+- Contract phase 2 — canonical DocPath (+ phase 1 wasm test fix) (#1012)
+- edit:: diagnostic codes on mutator failures (contract phase 1) (#1006)
+- Add document-contract rework phase plan (#1005)
+- content: centralize island type dispatch behind KnownIslandType (#985) (#1001)
+
+
 ## v0.95.1 - 2026-07-19
 
 
@@ -30,49 +65,6 @@
 - feat(content,wasm,python): `LineOp::SetContinues { line, continues }` — hard breaks lower op-wise. Split, join, and a text-delta `\n` all mint `continues: false` lines, so a within-block hard break (a paragraph hard break, a code fence's interior line) had no op and fell back to a whole-install, losing that edit's identity anchors. Threaded through the wire codec into WASM `applyChange` (TS union updated) and Python; `continues: true` on line 0 is rejected with `ApplyError::FirstLineContinues` before the write, leaving the content untouched (#949)
 - feat(wasm): the runtime root re-exports the edit vocabulary its own signatures reference — `Content` / `ContentLine` / `ContentContainer` / `ContentMark` / `ContentIsland`, `Addr` / `Delta` / `Assoc` / `LineOp` / `MarkOp` / `ChangeBundle`, `CardInput` / `PathStep` — as type-only exports (single entry point preserved; no `/core` subpath), with a presence guard so a dropped re-export fails `npm run typecheck` (#948)
 
-<!-- seed: commits since v0.94.0 — confirm the entries above cover them, then delete this comment
-- chore: prune redundant logic and duplicate tests (post-0.94.0 residue scan) (#996)
-- release: unbreak the crates.io publish lane; fold curated notes into the seed (#995)
-- Emit date fields as click-to-edit value-objects (#990) (#994)
-- Split `datetime` into strict `date` and `datetime` types (#991) (#993)
-- Python binding: commit to the Tier-1 surface (#970) (#992)
-- audit #982: complete the Content-genus residual sweep (retire "corpus") (#989)
-- feat: schema-bound read view — `quill.view(doc)` and `TypedReader` (#988)
-- Rebase marks through line ops; collapse bundle normalize (#987)
-- core: retire the V0_81_0 and V0_82_0 storage read shims (#929) (#986)
-- Document binding build performance guidance in CLAUDE.md (#984)
-- richtext: to_markdown projects a value, not a file — no trailing newline (#965) (#977)
-- docs(markdown-spec): scope $body wire claim, fix lossless→lossy projection (#983)
-- Delete prose/review directory
-- rename: content genus off its codec's name — RichText → Content, crate → quillmark-content (#976) (#981)
-- Add note to not run cargo fmt (#980)
-- fix(core,wasm,python): getMarkdown surfaces present-but-not-richtext instead of blanking (#968) (#979)
-- docs: purge rogue .qmd file-extension mentions (#975)
-- Rewrite CLAUDE.md for density (#974)
-- docs: fix mkdocs strict build — drop cross-tree link to prose/canon
-- wasm: name the main-card address (MAIN_CARD_ADDR), reject unknown addr keys (#969)
-- core: collapse the two parse functions into one `Document::parse` -> `Parsed` (#964)
-- core,wasm: writer-level reviseField; hide the quill-taking Document ABI (#966)
-- core,wasm,docs: dense-prose pass over the #963 write surface
-- docs: document the write-surface reshape (#955, #957, #960)
-- python: rename opaque store verbs set_* → store_* (#960)
-- wasm: unify Document on Addr addressing; store_* verbs; reviseChecked (#955, #960, #957)
-- core: rename opaque store verbs set_* → store_*; add revise_field_checked (#960, #957)
-- core: collapse the Payload insert helpers; tighten prose
-- core: use plain code spans for pub(crate) refs in Payload::insert docs
-- docs: 0.94→0.95 migration guide and BINDINGS parity refresh (#956, #958, #959, #961)
-- wasm,core: writer/card-surface parity cleanups (#961)
-- wasm,core: single-card, $id, and seed-overlay reads (#956)
-- core: enforce field invariants at the Payload::insert boundary (#958)
-- core: make ParseOutput the single owner of parse warnings (#959)
-- docs(bindings): densify the card-read doc comments
-- feat(wasm,python): keyed card reads mirroring the card write verbs (#953)
-- docs: remove prose/simplifications backlog for greenfield re-analysis
-- Add setContinues line op so hard breaks lower op-wise (#949)
-- Re-export corpus edit vocabulary from @quillmark/wasm root (#948)
--->
-
-
 ## v0.94.0 - 2026-07-15
 
 These notes cover everything since v0.92.1. No 0.93.x was separately

package/README.md

@@ -258,7 +258,7 @@ main card's `qty`, `doc.storeField({ card: 2, field: "qty" }, 3)` a composable
 card's. Reads are total over the field axis (`get` → `undefined`, `isFill` → `false` for
 an absent field; only an out-of-range card throws); field writes throw on a body
 address. `getMarkdown` is the body markdown read (a `CardAddr`; a field's
-markdown is read through `quill.view(doc).get(field)`). Card-scoped verbs take a
+markdown is read through `quill.reader(doc).get(field)`). Card-scoped verbs take a
 `CardAddr` (`{ card? }`) first: `doc.getExt({ card: 2 })`, and the batch below.
 
 Batch mutation: `doc.storeFields({}, {...})` / `doc.storeFields({ card: index }, {...})`
@@ -462,10 +462,11 @@ compilation failures. The same shape applies to every throw site:
 
 - `Document.fromMarkdown` — parse errors (missing root `$quill` metadata, YAML
   errors, `parse::input_too_large` for inputs > 10 MB).
-- `Document` mutators (`storeField`, the writer's `set`, etc.) — `EditError`
-  variants (`InvalidFieldName`, `InvalidKindName`, `ReservedKind`,
-  `IndexOutOfRange`, `ValueTooDeep`, `Import`) appear in `diagnostics[0].message`
-  with the `[EditError::<Variant>]` prefix.
+- `Document` mutators (`storeField`, the writer's `set`, etc.) — mutator
+  failures carry a namespaced `edit::*` `code` on `diagnostics[0]`
+  (`edit::invalid_field_name`, `edit::unknown_field`, `edit::index_out_of_range`,
+  `edit::field_conform`, …). Route on `diagnostics[0].code`, never on message
+  text.
 - `engine.render` / `session.render` — backend compilation failures and
   validation errors.
 

package/backends/pdfform/wasm.d.ts

@@ -110,14 +110,44 @@ export type ContentMark = { start: number; end: number } & (
 | { type: string; attrs: unknown }
 );
 
-/** A structured object (table, figure, …) occupying one island slot in `Content.text`. */
-export interface ContentIsland {
+/** A cell in a `TableProps` — its plain `text` plus the `marks` over it. `marks`
+ * rides the same wire shape as prose `ContentMark`, but each mark's `start`/`end`
+ * are USV offsets into this cell's `text` (`0..text.length`), not into
+ * `Content.text`. */
+export interface TableCell {
+    text: string;
+    marks: ContentMark[];
+}
+
+/** `props` of a `type: "table"` island: a pipe table normalized to one column
+ * count that `header`, every row of `rows`, and `aligns` all share. */
+export interface TableProps {
+    header: TableCell[];
+    rows: TableCell[][];
+    /** Per-column alignment, one entry per column. */
+    aligns: ("none" | "left" | "center" | "right")[];
+}
+
+/** `props` of a `type: "image"` island. */
+export interface ImageProps {
+    url: string;
+    alt: string;
+}
+
+/** A structured object occupying one island slot in `Content.text`. `type` is an
+ * open set: the engine pins `props` as `TableProps` for `table` and `ImageProps`
+ * for `image`; an island of any other type round-trips with opaque `props`. Like
+ * `ContentMark`, the open `type` arm means a discriminant check does not itself
+ * narrow `props` — key off `type` and read `props` as the matching shape. */
+export type ContentIsland = {
     id: string;
-    type: string;
-    props: unknown;
     /** How faithfully the markdown projection can carry this island. */
     loss: "lossless" | "degraded" | "unrepresentable";
-}
+} & (
+| { type: "table"; props: TableProps }
+| { type: "image"; props: ImageProps }
+| { type: string; props: unknown }
+);
 
 /**
  * A write address — one navigation concept for the whole `Document` surface. An
@@ -203,6 +233,21 @@ export interface ChangeBundle {
 
 
 
+/**
+ * One segment of a parsed `Diagnostic.path` (see `parseDocPath`). The head
+ * carries the document-model root — `main` (only before `body`), a `card`
+ * (`kind: null` is the unknown-kind `cards[i]` form), or a `field`; the tail is
+ * `field` / `index` / a terminal `body`.
+ */
+export type DocPathSeg =
+| { seg: "main" }
+| { seg: "card"; kind: string | null; index: number }
+| { seg: "field"; name: string }
+| { seg: "index"; index: number }
+| { seg: "body" };
+
+
+
 /**
  * Page dimensions in points (1 pt = 1/72 inch). Typst measures in Typst
  * points; pdfform measures in PDF points — the same unit.
@@ -288,6 +333,55 @@ export interface PaintResult {
 
 
 
+/** The commitment-ladder rung that produced a `ResolvedField.value`. */
+export type FieldSource = "authored" | "default" | "zero";
+
+/**
+ * One resolved row: its `name`, the value the render projection would use, and
+ * the `FieldSource` rung it came from. Rows are an ordered array — declaration
+ * order is structural, not object-key order. The card body is a `body` sibling
+ * on its card, never a row in `fields`. Diagnostics stay `Quill.validate`'s;
+ * schema guidance (`example:`, labels) reads from `Quill.schema`.
+ */
+export interface ResolvedField {
+    name: string;
+    value: unknown;
+    source: FieldSource;
+}
+
+/**
+ * The main card's resolved rows in declaration order, plus its body row —
+ * `null` when the main enables no body.
+ */
+export interface ResolvedMain {
+    fields: ResolvedField[];
+    body: ResolvedField | null;
+}
+
+/**
+ * One composable card's resolved rows in declaration order, with its authored
+ * `kind` (`null` for an unknown-kind card), its document-array `index`, and its
+ * body row — `null` when the kind enables no body.
+ */
+export interface ResolvedCard {
+    kind: string | null;
+    index: number;
+    fields: ResolvedField[];
+    body: ResolvedField | null;
+}
+
+/**
+ * The resolved-value view (`Quill.resolve`): the main card and every
+ * composable card. Value and provenance only — completeness and errors stay
+ * `Quill.validate`.
+ */
+export interface Resolved {
+    main: ResolvedMain;
+    cards: ResolvedCard[];
+}
+
+
+
 /** UI layout hints for a single field. Field display order is not a hint:
  * key order in the schema's `fields`/`properties` objects is declaration
  * order, the ordering contract. */
@@ -298,9 +392,23 @@ export interface QuillFieldUi {
     multiline?: boolean;
 }
 
+/** One entry in a card's `ui.groups` registry: a display-label override for the
+ * group id (the map key). An empty object carries no override — the consumer
+ * derives the label from the id (`memo_for` → "Memo For"), as it does a field
+ * label from its key. */
+export interface QuillGroupUi {
+    title?: string;
+}
+
 /** UI layout hints for a card (main or named card kind). */
 export interface QuillCardUi {
     title?: string;
+    /** The card's group registry: the ordered table of contents naming every
+     * group a field's `ui.group` may reference. The map key is the group id, and
+     * key order is declaration order — the display-order contract, the same one
+     * `fields` key order carries. Absent when the card declares no groups (or
+     * uses the deprecated implicit-group form). */
+    groups?: Record<string, QuillGroupUi>;
 }
 
 /** Body namespace for a card (main or named card kind). */
@@ -467,7 +575,7 @@ export class Document {
      * A single composable card by index — the whole `Card`, the card-indexed
      * twin of the [`main`](Self::main) getter, so reading one card need not
      * materialize every card via [`cards`](Self::cards). An out-of-range
-     * `index` throws `[EditError::IndexOutOfRange]`, matching the card write
+     * `index` throws `edit::index_out_of_range`, matching the card write
      * verbs.
      */
     card(index: number): Card;
@@ -523,7 +631,7 @@ export class Document {
      * the **body content** when `addr.field` is absent. A bare string is `Addr`
      * shorthand for `{ field }`. Reads are total over the field axis: an absent
      * field is `undefined`; only an out-of-range `addr.card` throws
-     * `[EditError::IndexOutOfRange]`. Reads need no schema, so they live on
+     * `edit::index_out_of_range`. Reads need no schema, so they live on
      * `Document`, not the typed writer; for the markdown projection of a
      * richtext value use [`getMarkdown`](Self::get_markdown).
      */
@@ -550,7 +658,7 @@ export class Document {
      *
      * `addr` is an optional **card address** (`{ card }`, absent = main). A
      * present `field` throws — a field's markdown is read through the
-     * schema-plane `quill.view(doc).get(field)`, which interprets by declared
+     * schema-plane `quill.reader(doc).get(field)`, which interprets by declared
      * type (#978). An out-of-range `addr.card` throws.
      */
     getMarkdown(addr?: CardAddr): string;
@@ -808,8 +916,8 @@ export 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
+     * compiled document and get back the `DocPath` 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 `FieldRegion.rect` —
      * from a canvas click, invert the overlay transform documented on
      * `FieldRegion`: `x = clickPx.x / renderScale`,
@@ -873,11 +981,12 @@ export class LiveSession {
     /**
      * Schema-field geometry for this compiled session — each content field's
      * **first placement** (one region per page it touches) plus widget and
-     * scalar-reference-site regions, keyed on the quill schema field path; a
-     * field may still appear more than once (group by `field`, see
-     * `FieldRegion`). A session-level query: no render, no byte artifact. An
-     * interactive preview reads it to scroll to / highlight the focused
-     * field over a `paint`-ed canvas; the click direction is `fieldAt`.
+     * scalar-reference-site regions, keyed on the canonical `DocPath` address
+     * (`parseDocPath`-routable; the session resolves the backend's plate-space
+     * per-kind ordinal to it); a field may still appear more than once (group
+     * by `field`, see `FieldRegion`). A session-level query: no render, no byte
+     * artifact. An interactive preview reads it to scroll to / highlight the
+     * focused field over a `paint`-ed canvas; the click direction is `fieldAt`.
      * Empty for backends that place no schema fields.
      */
     regions(): FieldRegion[];
@@ -916,6 +1025,17 @@ export class Quill {
      * canonical shape.
      */
     static fromTree(tree: Map<string, Uint8Array>): Quill;
+    /**
+     * The resolved-value view of `doc` against this quill's schema — for every
+     * declared field the value the render projection would use and the
+     * `FieldSource` rung it came from (`"authored" | "default" | "zero"`), in
+     * one call. The card body rides the `fields` map under the `$body` key.
+     *
+     * Value and provenance only: completeness and errors stay `validate`'s
+     * (a consumer merges it with its own diagnostic producers regardless), and
+     * schema guidance reads from `Quill.schema`.
+     */
+    resolve(doc: Document): Resolved;
     /**
      * Seed a starter composable `Card` of the given kind (carries `$kind`),
      * layering an optional per-kind seed `overlay` over the schema-example
@@ -1035,6 +1155,15 @@ export class Quillmark {
  */
 export function exportMarkdown(rt: Content): string;
 
+/**
+ * Serialize structured [`DocPathSeg`] segments back to the canonical path
+ * string — the inverse of `parseDocPath`, for a consumer that builds a path
+ * rather than reads one. Throws on a segment array the deserializer rejects,
+ * and on an empty segment array (symmetric with `parseDocPath("")`, which
+ * throws "empty path").
+ */
+export function formatDocPath(segs: DocPathSeg[]): string;
+
 /**
  * Import a markdown string to a canonical `Content` content — the pure,
  * document-free codec. Pair with `install(addr, importMarkdown(md))` to spell
@@ -1056,6 +1185,15 @@ export function init(): void;
  */
 export function mapPos(delta: Delta, pos: number, assoc: Assoc): number;
 
+/**
+ * Parse a canonical document-model `Diagnostic.path`
+ * (`cards.<kind>[<i>].<field>`, `main.body`, `recipients[0].name`) into its
+ * structured [`DocPathSeg`] segments — the exported inverse of the engine's
+ * one path serializer, so a consumer routes on segments instead of regexing
+ * the string. Throws on a malformed path.
+ */
+export function parseDocPath(path: string): DocPathSeg[];
+
 /**
  * Rebase `markdown` onto a `base` content — the pure, document-free twin of
  * `revise`: cold-import + `diff_import`, returning the new `content` and the

package/backends/pdfform/wasm.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./wasm_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    Document, LiveSession, Quill, Quillmark, exportMarkdown, importMarkdown, init, mapPos, rebase
+    Document, LiveSession, Quill, Quillmark, exportMarkdown, formatDocPath, importMarkdown, init, mapPos, parseDocPath, rebase
 } from "./wasm_bg.js";