@quillmark/wasm 0.113.0 → 0.114.0

package/CHANGELOG.md

@@ -1,5 +1,130 @@
 # Changelog
 
+## v0.114.0 - 2026-09-18
+
+### Schema, validation and the resolved view
+
+- feat(core): **`type: matrix`: a closed vocabulary someone ticks.** A card kind
+  gave add and remove, the wrong verbs for a roster the page prints in full, and
+  an `array<{member: enum, detail}>` hid every unpicked option, let the same
+  member in twice, and left the plate owning a second copy of the vocabulary to
+  print the unheld boxes. A `matrix` declares `members:` — ordered blocks of
+  `id: Title`, groups optional — and `properties:` as the columns, and the
+  loader expands them into an `object` whose properties are the member ids, each
+  carrying a synthesized `held: {type: boolean, default: false}` beside the
+  columns. Coercion, validation, blank-fill and addressing are the typed
+  dictionary's, reached through the new `FieldSchema::namespace_props`, so
+  `qualifications.flight_cc.held` regions on Typst and binds a checkbox on
+  acroform without a new address grammar. Four behaviors are the type's own.
+  **Key presence is the tick**: `cyber_200: true` normalizes to the member
+  object as the bare `classification: CUI` normalizes to `{value: CUI}`, and a
+  mapping naming no `held` is held, so a document stays sparse. **The roster
+  reaches the wire**: every member present in declaration order carrying its own
+  `title` and `group`, so a plate prints the vocabulary without holding a second
+  copy of it. **The wire carries the live world only**: an unheld member's
+  columns render at their blanks whatever the document retains, the closed shape
+  variants already hold, so tick, type, untick, retick keeps the answer in the
+  file and stops rendering it. **Obligation is gated on the tick**: a column with
+  no `default:` reads "required when held", the variant rule one level down,
+  while the matrix itself obliges nothing, takes no `default:` or `example:`
+  (`quill::{default,example}_on_namespace`, the existing namespace rule) and
+  seeds empty. `held`, `title` and `group` are reserved as column names
+  (`quill::matrix_reserved_column`); a member id is a snake_case identifier
+  (`quill::invalid_matrix_member`), unique across the roster
+  (`quill::duplicate_matrix_member`), and one outside it is refused as an
+  out-of-domain enum member is. The blueprint spells the roster in the existing
+  format slot, `# matrix<flight_cc | dodin_ops | …>`, over a `{}` cell, so no
+  third annotation form is minted and a model sees the whole vocabulary without
+  twenty-seven lines to delete. Closes #1831.
+- feat(core): **the transform schema carries a declared key order, and the Typst
+  codegen honours it.** `Codegen::emit_value` sorts dict keys so a reorder-only
+  `update` rebuilds byte-identical `lib.typ` and comemo reuses the whole compile.
+  A matrix is the one node that cannot pay it: printing the vocabulary as the
+  schema groups it is the type's purpose, and sorted keys hand the plate
+  `cyber_200` before `sq_cc_candidate`. A container node whose *schema* fixes an
+  order now says so with `quillmark:order`, and the emitter reads it. The order
+  is a property of the schema rather than of the data, so equal data still
+  produces byte-equal source and nothing about the reuse changes; a node
+  carrying no such key sorts as before.
+- feat(core): **`max:` on an array, and `validation::cardinality`.** A form with
+  thirty-seven ruled lines silently swallowed a thirty-eighth row, and the limit
+  lived in `description:` prose that no consumer reads. `max:` is a non-negative
+  integer on an `array`, refused elsewhere, and a `default:`/`example:` longer
+  than it fails the load (`quill::{default,example}_over_max`) rather than
+  seeding a document that warns on arrival. `Quill::validate` reports
+  `validation::cardinality` at the field's own path with `{max, actual}`, at
+  every depth — an array in a typed dictionary, a matrix member, a live variant
+  world or another array's elements is capped by its own declaration — and never
+  gates render: fatal ≡ won't-render is an invariant of the diagnostic model, and
+  the plate keeps its own rule for the surplus. The count is the render floor's,
+  so a bare scalar coerced to a one-element array is counted as one. `min:` is
+  not taken: obligation is `default:`'s absence, so `min: 1` is `required:` under
+  another name. Closes #1826.
+- feat(core): **the blueprint carries a cap as `# up to <N>`.** The author most
+  likely to exceed a limit is the MCP flow that reads the spec once and then
+  writes, and it reads the blueprint: `schema()` is consulted before that author
+  writes, and the `validate` warning arrives after the overflowing document
+  exists. The line rides the own-line leading slot directly under the field's
+  description, the form `# composable (0..N)` already takes for a card kind's
+  cardinality, so the `<type>[<format>]` inline grammar is untouched. It reaches
+  a field and an `object` property, the two positions that slot exists at.
+- feat(core): **`ui.layout: table` asks an editor for the grid a typed table
+  wants.** A row of four short cells drew as a stack of collapsed rows that open
+  one at a time — the right control for a row of long prose, the wrong one here —
+  and `UiFieldSchema` is `deny_unknown_fields`, so the shape had no way to ask.
+  `layout: table` is valid on an `array` whose `items` is an `object` and refused
+  with `quill::invalid_ui` anywhere else, and `schema()` echoes it verbatim. A
+  request, not a contract: the plate, `validate` and the blueprint are all
+  deliberately inert on it, and a consumer that cannot draw the control falls
+  back to its own choice for the type. `items.ui.title` is documented beside it
+  as the collapsed row's summary template, which needed no loader change.
+  Closes #1825.
+- feat(core): **a card kind declaring `body.enabled: false` warns.** A card is a
+  part someone writes; a repeated record someone fills in is a row, an
+  `array<object>` on the card that owns it. Four card kinds across three airmark
+  quills were rows in card costume, each bodiless with a plate reassembling them
+  from the stream by position. `quill::bodiless_card_kind` says so at
+  `Severity::Warning`, hinting at the row shape. A warning and not a load error,
+  because the loader sees the proxy and not the fact: whether a kind interleaves
+  among kinds of other sorts is a property of documents and the plate, nothing in
+  `Quill.yaml` states it, and a bodiless positional kind — a page break, a rule,
+  an inserted signature block — is a card. `main` keeps the key unwarned: a form
+  has no root prose. Closes #1824.
+
+### The binding surface
+
+- feat(wasm): **`formatDiagnostic` renders a diagnostic as the CLI does.**
+  `Document.formatDiagnostic` left the binding in 0.113 among the five owner
+  calls a host can make itself, and it was the one of the five that left a
+  surface behind: Python keeps the rendering on `PyDiagnostic.__str__`, which is
+  `fmt_pretty`, and the CLI prints through the same call, so WASM alone lost the
+  engine's English. A consumer wording its own still selects by `code` + `args`.
+
+### Docs and tests
+
+- docs(core): **`ERROR.md` § "Error Presentation" names the two lanes apart.** A
+  consumer surfacing the engine's wording calls the one printer; a consumer
+  wording its own selects by `code` + `args` and owns the layout with the
+  sentence.
+- docs(acroform): **the worked example gains the richtext field the fixture
+  does.** `sample_form` is what the backend guide points at for a hand-authored
+  `form.pdf` + `form.json`, so its excerpts state what that fixture declares.
+- test(core): **one fixture walk, one scalar-fidelity home, one card-order
+  test.** Closes #1676.
+- test(core): **one loader, one coercion table, one quill header.** Closes #1677.
+- test(pdf,typst): **one base-PDF builder, one home per invariant.** Closes
+  #1681, closes #1680.
+- ci: **the release dispatches the docs deploy it no longer triggers.**
+  `docs.yml` deploys Pages on `release: published`, and moving `gh release
+  create` onto `GITHUB_TOKEN` stopped that event starting a run, so the site sat
+  eleven releases behind at v0.102.0. `workflow_dispatch` is the one event exempt
+  from that rule, which `release-prepare.yml` already leans on for `ci.yml`, so
+  the release dispatches `docs.yml` at the tag it just pushed — the site is built
+  from the released bytes, and a prerelease is skipped as the event path skipped
+  it.
+- build(deps): **lopdf 0.44.0 → 0.45.0**, and **taiki-e/install-action 2.87.8 →
+  2.87.12** in the actions group.
+
 ## v0.113.0 - 2026-09-16
 
 Upgrade path: [0.112 → 0.113](docs/migrations/0.112-to-0.113.md).

package/core/wasm.d.ts

@@ -397,6 +397,11 @@ export interface QuillFieldUi {
     /** Label for an `enum`'s blank option. Absent, the consumer supplies a
      *  conventional label of its own. */
     blank_title?: string;
+    /** The control the field asks for, where the shape admits more than one.
+     *  A request, not a contract: a consumer that cannot draw it falls back to
+     *  its own choice for the type. `"table"` is valid only on an `array`
+     *  whose `items` is an `object`. */
+    layout?: "table";
 }
 
 /** One entry in a card's `ui.groups` registry: a display-label override for the
@@ -448,7 +453,7 @@ export interface QuillCardBody {
  * gates render: an absent field blank-fills.
  */
 export interface QuillFieldSchema {
-    type: "string" | "number" | "integer" | "boolean" | "array" | "object" | "date" | "datetime" | "richtext" | "plaintext" | "enum";
+    type: "string" | "number" | "integer" | "boolean" | "array" | "object" | "date" | "datetime" | "richtext" | "plaintext" | "enum" | "matrix";
     description?: string;
     default?: unknown;
     example?: unknown;
@@ -460,14 +465,30 @@ export interface QuillFieldSchema {
      *  member. Declaring it makes the field rest as a container,
      *  `{value: <member>, …that member's fields}`, rather than a bare string. */
     variants?: Record<string, Record<string, QuillFieldSchema>>;
+    /** The roster of a `type: "matrix"` field, required there and valid
+     *  nowhere else: the closed vocabulary a document ticks, in display order.
+     *  Each member is an object of `held` plus the field's `properties`
+     *  (the columns), addressed as `<field>.<member id>.held`. */
+    members?: QuillMatrixGroup[];
     ui?: QuillFieldUi;
     properties?: Record<string, QuillFieldSchema>;
     items?: QuillFieldSchema;
+    /** The element count past which an `array` overflows the page it is laid
+     *  out on. Valid only on an `array`. Never gates render: a document over
+     *  the cap warns `validation::cardinality` and renders. */
+    max?: number;
     /** `true` on a `richtext` or `plaintext` field declared `inline`: the
      *  single-paragraph, container-free, island-free constraint. */
     inline?: boolean;
 }
 
+/** One block of a `type: "matrix"` roster: an optional display heading and the
+ * members under it, member id to display title. Key order is display order. */
+export interface QuillMatrixGroup {
+    group?: string;
+    values: Record<string, string>;
+}
+
 /** Schema entry for the main card or a named card kind. */
 export interface QuillCardSchema {
     description?: string;
@@ -923,6 +944,19 @@ export class Quill {
  */
 export function exportMarkdown(rt: Content): string;
 
+/**
+ * Render a diagnostic as the CLI and Python's `str(diagnostic)` render it:
+ * the severity tag and the message, the code parenthesised after them, then
+ * location, path and hint each on an indented line of its own. The engine
+ * owns the one printer, so a consumer surfacing diagnostics reads it here
+ * rather than keeping a copy of the layout that drifts from the CLI's.
+ *
+ * Takes the `Diagnostic` shape every read hands back. Throws on a value that
+ * is not one — a missing `severity` or `message`, or a `severity` outside the
+ * two-value ladder.
+ */
+export function formatDiagnostic(diagnostic: Diagnostic): string;
+
 /**
  * Serialize structured [`DocPathSeg`] segments back to the canonical path
  * string: the inverse of `parseDocPath`. Throws on a segment array the
@@ -1043,6 +1077,7 @@ export interface InitOutput {
     readonly document_toStored: (a: number, b: number) => void;
     readonly document_warnings: (a: number, b: number) => void;
     readonly exportMarkdown: (a: number, b: number) => void;
+    readonly formatDiagnostic: (a: number, b: number) => void;
     readonly formatDocPath: (a: number, b: number) => void;
     readonly importMarkdown: (a: number, b: number, c: number) => void;
     readonly mapMarks: (a: number, b: number, c: number) => void;

package/core/wasm.js

@@ -1546,6 +1546,44 @@ export function exportMarkdown(rt) {
     }
 }
 
+/**
+ * Render a diagnostic as the CLI and Python's `str(diagnostic)` render it:
+ * the severity tag and the message, the code parenthesised after them, then
+ * location, path and hint each on an indented line of its own. The engine
+ * owns the one printer, so a consumer surfacing diagnostics reads it here
+ * rather than keeping a copy of the layout that drifts from the CLI's.
+ *
+ * Takes the `Diagnostic` shape every read hands back. Throws on a value that
+ * is not one — a missing `severity` or `message`, or a `severity` outside the
+ * two-value ladder.
+ * @param {Diagnostic} diagnostic
+ * @returns {string}
+ */
+export function formatDiagnostic(diagnostic) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        wasm.formatDiagnostic(retptr, addHeapObject(diagnostic));
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+        var ptr1 = r0;
+        var len1 = r1;
+        if (r3) {
+            ptr1 = 0; len1 = 0;
+            throw takeObject(r2);
+        }
+        deferred2_0 = ptr1;
+        deferred2_1 = len1;
+        return getStringFromWasm0(ptr1, len1);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export4(deferred2_0, deferred2_1, 1);
+    }
+}
+
 /**
  * Serialize structured [`DocPathSeg`] segments back to the canonical path
  * string: the inverse of `parseDocPath`. Throws on a segment array the

package/core/wasm_bg.wasm.d.ts

@@ -52,6 +52,7 @@ export const document_toMarkdown: (a: number, b: number) => void;
 export const document_toStored: (a: number, b: number) => void;
 export const document_warnings: (a: number, b: number) => void;
 export const exportMarkdown: (a: number, b: number) => void;
+export const formatDiagnostic: (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 mapMarks: (a: number, b: number, c: number) => void;

package/package.json

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

package/render/wasm.d.ts

@@ -452,6 +452,11 @@ export interface QuillFieldUi {
     /** Label for an `enum`'s blank option. Absent, the consumer supplies a
      *  conventional label of its own. */
     blank_title?: string;
+    /** The control the field asks for, where the shape admits more than one.
+     *  A request, not a contract: a consumer that cannot draw it falls back to
+     *  its own choice for the type. `"table"` is valid only on an `array`
+     *  whose `items` is an `object`. */
+    layout?: "table";
 }
 
 /** One entry in a card's `ui.groups` registry: a display-label override for the
@@ -503,7 +508,7 @@ export interface QuillCardBody {
  * gates render: an absent field blank-fills.
  */
 export interface QuillFieldSchema {
-    type: "string" | "number" | "integer" | "boolean" | "array" | "object" | "date" | "datetime" | "richtext" | "plaintext" | "enum";
+    type: "string" | "number" | "integer" | "boolean" | "array" | "object" | "date" | "datetime" | "richtext" | "plaintext" | "enum" | "matrix";
     description?: string;
     default?: unknown;
     example?: unknown;
@@ -515,14 +520,30 @@ export interface QuillFieldSchema {
      *  member. Declaring it makes the field rest as a container,
      *  `{value: <member>, …that member's fields}`, rather than a bare string. */
     variants?: Record<string, Record<string, QuillFieldSchema>>;
+    /** The roster of a `type: "matrix"` field, required there and valid
+     *  nowhere else: the closed vocabulary a document ticks, in display order.
+     *  Each member is an object of `held` plus the field's `properties`
+     *  (the columns), addressed as `<field>.<member id>.held`. */
+    members?: QuillMatrixGroup[];
     ui?: QuillFieldUi;
     properties?: Record<string, QuillFieldSchema>;
     items?: QuillFieldSchema;
+    /** The element count past which an `array` overflows the page it is laid
+     *  out on. Valid only on an `array`. Never gates render: a document over
+     *  the cap warns `validation::cardinality` and renders. */
+    max?: number;
     /** `true` on a `richtext` or `plaintext` field declared `inline`: the
      *  single-paragraph, container-free, island-free constraint. */
     inline?: boolean;
 }
 
+/** One block of a `type: "matrix"` roster: an optional display heading and the
+ * members under it, member id to display title. Key order is display order. */
+export interface QuillMatrixGroup {
+    group?: string;
+    values: Record<string, string>;
+}
+
 /** Schema entry for the main card or a named card kind. */
 export interface QuillCardSchema {
     description?: string;
@@ -1225,6 +1246,19 @@ export class Quillmark {
  */
 export function exportMarkdown(rt: Content): string;
 
+/**
+ * Render a diagnostic as the CLI and Python's `str(diagnostic)` render it:
+ * the severity tag and the message, the code parenthesised after them, then
+ * location, path and hint each on an indented line of its own. The engine
+ * owns the one printer, so a consumer surfacing diagnostics reads it here
+ * rather than keeping a copy of the layout that drifts from the CLI's.
+ *
+ * Takes the `Diagnostic` shape every read hands back. Throws on a value that
+ * is not one — a missing `severity` or `message`, or a `severity` outside the
+ * two-value ladder.
+ */
+export function formatDiagnostic(diagnostic: Diagnostic): string;
+
 /**
  * Serialize structured [`DocPathSeg`] segments back to the canonical path
  * string: the inverse of `parseDocPath`. Throws on a segment array the
@@ -1347,6 +1381,7 @@ export interface InitOutput {
     readonly document_toStored: (a: number, b: number) => void;
     readonly document_warnings: (a: number, b: number) => void;
     readonly exportMarkdown: (a: number, b: number) => void;
+    readonly formatDiagnostic: (a: number, b: number) => void;
     readonly formatDocPath: (a: number, b: number) => void;
     readonly importMarkdown: (a: number, b: number, c: number) => void;
     readonly livesession_backendId: (a: number, b: number) => void;

package/render/wasm.js

@@ -1965,6 +1965,44 @@ export function exportMarkdown(rt) {
     }
 }
 
+/**
+ * Render a diagnostic as the CLI and Python's `str(diagnostic)` render it:
+ * the severity tag and the message, the code parenthesised after them, then
+ * location, path and hint each on an indented line of its own. The engine
+ * owns the one printer, so a consumer surfacing diagnostics reads it here
+ * rather than keeping a copy of the layout that drifts from the CLI's.
+ *
+ * Takes the `Diagnostic` shape every read hands back. Throws on a value that
+ * is not one — a missing `severity` or `message`, or a `severity` outside the
+ * two-value ladder.
+ * @param {Diagnostic} diagnostic
+ * @returns {string}
+ */
+export function formatDiagnostic(diagnostic) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        wasm.formatDiagnostic(retptr, addHeapObject(diagnostic));
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+        var ptr1 = r0;
+        var len1 = r1;
+        if (r3) {
+            ptr1 = 0; len1 = 0;
+            throw takeObject(r2);
+        }
+        deferred2_0 = ptr1;
+        deferred2_1 = len1;
+        return getStringFromWasm0(ptr1, len1);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export4(deferred2_0, deferred2_1, 1);
+    }
+}
+
 /**
  * Serialize structured [`DocPathSeg`] segments back to the canonical path
  * string: the inverse of `parseDocPath`. Throws on a segment array the

package/render/wasm_bg.wasm.d.ts

@@ -54,6 +54,7 @@ export const document_toMarkdown: (a: number, b: number) => void;
 export const document_toStored: (a: number, b: number) => void;
 export const document_warnings: (a: number, b: number) => void;
 export const exportMarkdown: (a: number, b: number) => void;
+export const formatDiagnostic: (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 livesession_backendId: (a: number, b: number) => void;

package/runtime/runtime.d.ts

@@ -22,7 +22,8 @@ import type {
 	mapPos,
 	mapMarks,
 	parseDocPath,
-	formatDocPath
+	formatDocPath,
+	formatDiagnostic
 } from '../core/wasm.js';
 
 /**
@@ -42,6 +43,7 @@ export interface CoreSurface {
 	mapMarks: typeof mapMarks;
 	parseDocPath: typeof parseDocPath;
 	formatDocPath: typeof formatDocPath;
+	formatDiagnostic: typeof formatDiagnostic;
 }
 
 /**
@@ -106,6 +108,7 @@ export type {
 	QuillFieldUi,
 	QuillCardUi,
 	QuillGroupUi,
+	QuillMatrixGroup,
 	QuillMetadata
 } from '../core/wasm.js';
 

package/runtime/runtime.js

@@ -20,7 +20,7 @@ import initCore, { Quill, Document } from '../core/wasm.js';
 // Resolution-time, so `node:fs` never enters a browser graph.
 import { toModuleSource } from '#quillmark-env';
 import { importMarkdown, exportMarkdown, rebase, mapPos, mapMarks } from '../core/wasm.js';
-import { parseDocPath, formatDocPath } from '../core/wasm.js';
+import { parseDocPath, formatDocPath, formatDiagnostic } from '../core/wasm.js';
 
 // A `--target web` build exports its classes synchronously but carries no wasm
 // instance until something instantiates it. This module owns that for core,
@@ -50,7 +50,8 @@ const CORE_SURFACE = Object.freeze({
 	mapPos,
 	mapMarks,
 	parseDocPath,
-	formatDocPath
+	formatDocPath,
+	formatDiagnostic
 });
 
 /** The in-flight or settled core instantiation, resolving to `CORE_SURFACE`.