@quillmark/wasm 0.85.0 → 0.87.0

package/CHANGELOG.md

@@ -0,0 +1,175 @@
+# Changelog
+
+## v0.87.0 - 2026-06-01
+
+Arrays become first-class typed fields via a required `items` element
+schema, datetime is unified under a single `type: datetime` accepting the
+full YAML-1.1-style timestamp range (`FieldType::Date` is gone), and object
+zero values are now shape-valid. This release tightens schema-load
+validation in several places — empty `properties` maps and deeper array
+nesting are now rejected — and consolidates the example/default conformance
+checks behind one shared primitive. Documentation now ships from GitHub
+Pages instead of Read the Docs.
+
+### Breaking changes
+
+These are schema-load cutovers for `Quill.yaml` authors; full before/after
+steps are in `docs/migrations/0.86-to-0.87.md`.
+
+- **Array fields now require an `items` element schema** (#672). Arrays
+  previously carried a single untyped `Array` type; scalar arrays were
+  never coerced or validated element-wise and were always annotated
+  `array<string>`. Every array field must now declare `items`, and schema
+  load rejects arrays without it. The bare-`properties`-on-an-array form
+  (the old "typed table") is **removed** in favor of
+  `items: { type: object, properties: … }`. Migration for a typed table:
+
+  ```yaml
+  # before
+  rows:
+    type: array
+    properties: { name: { type: string }, qty: { type: integer } }
+  # after
+  rows:
+    type: array
+    items:
+      type: object
+      properties: { name: { type: string }, qty: { type: integer } }
+  ```
+
+  A scalar array adds `items` directly, e.g.
+  `counts: { type: array, items: { type: integer } }`. Elements now coerce
+  and validate against `items` (failing at the indexed path, e.g.
+  `counts[1]`), and blueprint annotations reflect the element type
+  (`array<integer>`, `array<markdown>`, …). Bundled quills and the
+  `usaf_memo` golden schema are migrated.
+- **`FieldType::Date` removed; use `type: datetime`** (#679). `type: date`
+  no longer exists. `type: datetime` now accepts the full range from a bare
+  `YYYY-MM-DD` date through RFC 3339 with offset (seconds optional, `T` or
+  space separator). Datetime values gain calendar validation (e.g. Feb 30
+  is now rejected), and JSON Schema output emits `format: date-time` for
+  all datetime fields. The WASM `FieldType` union drops `"date"`. The
+  blueprint hint is now `datetime<YYYY-MM-DD[Thh:mm:ss]>`.
+- **Empty `properties: {}` on an object field is rejected** (#678). An
+  empty properties map carries no information (the only conforming value is
+  `{}`) and is almost always a mistake. It is now treated like a missing
+  `properties` key and surfaces `quill::object_empty_properties`.
+- **Deeper array nesting is rejected** (#673). The documented "one level of
+  nesting" contract is now enforced in a single recursive pass, closing a
+  gap where `array<object<array>>` and `object<array>` were silently
+  accepted. A typed table row and a typed dictionary may carry scalar
+  columns/properties only; deeper shapes fail with
+  `quill::nested_array_not_supported`.
+
+### Behavioral changes
+
+- **Object zero values are now shape-valid** (#677). `zero_value` returned
+  a bare `{}` for every object field, which failed validation on any object
+  with `properties` (each absent property reported as `MustFillUnset`), so
+  the zero-filled render path broke for object fields. An object with
+  `properties` now recurses, zero-filling each property to its own
+  type-empty leaf. `{}` remains the zero only for the property-less edge
+  case.
+- **`example:` values are now validated** (#680). The conformance check for
+  `example`/`default` literals recurses into array items and object
+  properties and validates datetime format — capabilities the old
+  load-time path lacked, so previously-unvalidated `example:` values are
+  now caught.
+
+### Documentation & infrastructure
+
+- **Docs hosting moved from Read the Docs to GitHub Pages** (#671). A new
+  `docs.yml` workflow builds MkDocs (strict build as a PR check) and
+  deploys to Pages on a published release; RCs are skipped. `.readthedocs.yaml`
+  is removed and homepage/User Guide links point at the Pages URL.
+- **Canon + docs: partial documents are first-class citizens** (#670). The
+  docs and binding READMEs no longer claim Must Fill fields must be supplied
+  before shipping. The only hard render gate is well-formedness (values
+  coerce, no surviving `<must-fill>` sentinel); completeness is a hint
+  surfaced by the form view. The `format-designer/` docs tree is renamed to
+  `quills/`.
+- A Migration section overview page was added and wired into the nav (#674).
+
+### Internal
+
+- Example/default validation is consolidated behind a single
+  `validate_schema_literal` conformance core shared by `quillmark-core`
+  config loading and the CLI `validate` command, with author-friendly
+  diagnostics preserved (#680).
+- Array and markdown handling collapse into recursive passes over the
+  schema in both schema-shape validation and the Typst markdown transform
+  (#673).
+- Doc/comment fixes from the array-items review (#675).
+
+
+## v0.86.0 - 2026-05-31
+
+Documents now render even when incomplete, the canonical card-yaml fence
+becomes a bare `~~~`, and the way placeholder/illustrative values are
+produced is reworked. This release also fixes two markdown→Typst
+conversion bugs and stamps a PDF `/Producer` field.
+
+### Breaking changes
+
+- **Bare `~~~` is now the canonical card-yaml fence** (was `~~~card-yaml`)
+  (#662). Existing `~~~card-yaml` documents still parse, but `to_markdown`
+  re-emits the bare `~~~` form, so a document's canonical bytes change on
+  its first re-emit (relevant if you content-hash or byte-compare emitted
+  markdown, or store blueprint goldens). A side effect: a column-zero
+  `~~~` fence in a prose body is now read as a card-yaml block — use a
+  backtick fence or a non-`card-yaml` info string (e.g. `~~~rust`) for a
+  literal code block. Full details and corpus-migration steps:
+  `docs/migrations/0.85-to-0.86.md`.
+- **`fill_blueprint()` removed** from `quillmark_core` and `quillmark`,
+  along with its re-exports (#657, #665). Callers no longer post-process a
+  blueprint string: fillable/illustrative documents come from
+  `QuillConfig::example()`, and the render path fills placeholders itself
+  (see below).
+
+### Behavioral changes
+
+- **Incomplete documents render instead of erroring** (#665). An absent
+  Must Fill field is no longer a render error. On the render path each
+  schema field resolves to its authored value, else its `default:`, else a
+  type-empty zero value — applied to the plate projection only, never
+  persisted to the document. Only malformed input stays fatal: a surviving
+  `<must-fill>` sentinel, or a value that won't coerce/validate.
+  `quill.form(doc)` still reports completeness independently of the render
+  gate.
+- **`default` vs `example` clarified** (#665, #663, #658). `default` is the
+  value most authors want and is interpolated when a field is omitted (an
+  authored value always wins); `example` documents a field's shape only and
+  never renders into output. Preview and illustrative fills now draw from a
+  field's `example:` when present, falling back to the leanest type-valid
+  value (`""`, `0`, `false`, `[]`, `{}`, first enum variant, empty body).
+
+### Markdown → Typst fixes (#661)
+
+- Code is now emitted as `#raw(...)` with a string literal instead of a
+  backtick fence. This fixes fenced or inline code whose content contained
+  a run of three-or-more backticks, which previously closed the block early
+  and rendered as markup.
+- Ordered-list start numbers are preserved — a list written `3.` / `4.` now
+  renders starting at 3 instead of restarting at 1.
+
+### New API
+
+- `QuillConfig::example()`, plus `example` getters on the Python and WASM
+  bindings (#665).
+- `quillmark_core::zero_value` — the single source of truth for a field's
+  type-minimal value, shared by blueprint emission and the render path
+  (#665).
+- `RenderOptions.producer` on the core, WASM, and Python render APIs (#656)
+  — overrides the PDF `/Info` `/Producer` string, which now defaults to
+  `Quillmark <version>` on every Typst-rendered PDF.
+
+### Other fixes
+
+- PDF rendering folds the `/Producer` stamp and the signature-field
+  AcroForm injection into a single incremental-update pass, preserving
+  Typst's `/Creator` (#656).
+- `usaf_memo`: the signature widget is now overlaid at the 4.5in signature
+  block (AFH 33-337) instead of the 1in left margin, and no longer consumes
+  layout flow that could push the block out of position (#660); empty
+  signature fields no longer carry the `APPEND_ONLY` flag (#654).
+

package/README.md

@@ -34,7 +34,7 @@ import { Document, Quillmark } from "@quillmark-test/wasm";
 const engine = new Quillmark();
 const quill = engine.quill(tree);
 
-const markdown = `~~~card-yaml
+const markdown = `~~~
 $quill: my_quill
 $kind: main
 title: My Document
@@ -249,10 +249,11 @@ canvas.style.height = `${result.layoutHeight}px`;
 A field's *cell* is inferred from whether its schema declares a `default:`:
 
 - **Must Fill** (no `default:`) — `quill.blueprint` renders `<must-fill>`
-  in the value cell, and `quill.render(doc)` throws with
-  `validation::must_fill_absent` when the field is absent at
-  validate time, or `validation::must_fill_sentinel` when the
-  `<must-fill>` sentinel survives into the document.
+  in the value cell. An absent Must Fill field is a non-fatal signal
+  (`validation::must_fill_absent`) — the render path zero-fills it
+  silently. A surviving `<must-fill>` sentinel is fatal
+  (`validation::must_fill_sentinel`). Partial documents are
+  first-class; `quill.render(doc)` only throws for malformed input.
 - **Endorsed** (with `default:`) — `quill.blueprint` renders the
   default value followed by a `; delete-ok` annotation, and the default
   is used when the document omits the field.
@@ -316,12 +317,19 @@ try {
 
 ## Notes
 
-- Parsed markdown requires a root `~~~card-yaml` block with a
-  `$quill` system-metadata line. Empty input surfaces a dedicated
+- Parsed markdown requires a root `~~~` block (a bare three-tilde fence;
+  the legacy `~~~card-yaml` opener is still accepted but non-canonical)
+  with a `$quill` system-metadata line. Empty input surfaces a dedicated
   "Empty markdown input cannot be parsed" message.
 - QUILL mismatch during `quill.render(parsed)` is a warning (`quill::ref_mismatch`), not an error.
 - Output schema APIs are no longer engine-level in WASM.
 
+## Changelog
+
+See the [changelog](https://github.com/quillmark-org/quillmark/blob/main/CHANGELOG.md)
+and the [GitHub Releases](https://github.com/quillmark-org/quillmark/releases) page for
+release notes and version history.
+
 ## License
 
 Apache-2.0

package/bundler/wasm.d.ts

@@ -113,10 +113,11 @@ export interface QuillCardBody {
  * without a `default` is **Must Fill** (the blueprint carries a
  * `<must-fill>` sentinel and validation reports
  * `validation::must_fill_absent` if the field is absent at validate
- * time). There is no separate `required` axis.
+ * time — a non-fatal signal, since the render path zero-fills an absent
+ * field). There is no separate `required` axis.
  */
 export interface QuillFieldSchema {
-    type: "string" | "number" | "integer" | "boolean" | "array" | "object" | "date" | "datetime" | "markdown";
+    type: "string" | "number" | "integer" | "boolean" | "array" | "object" | "datetime" | "markdown";
     description?: string;
     default?: unknown;
     example?: unknown;
@@ -234,6 +235,7 @@ export interface RenderOptions {
     format?: OutputFormat;
     ppi?: number;
     pages?: number[];
+    producer?: string;
 }
 
 export interface RenderResult {
@@ -427,6 +429,13 @@ export class Quill {
      */
     readonly backendId: string;
     readonly blueprint: string;
+    /**
+     * The `example` reference document — the illustrative "show me a
+     * filled-out one." Each field renders its `example:`, else its
+     * `default:`, else the type-empty zero value, with no `<must-fill>`
+     * sentinels. See `prose/canon/BLUEPRINT.md`.
+     */
+    readonly example: string;
     /**
      * Identity snapshot of the `quill:` section of `Quill.yaml`, plus
      * `supportedFormats` and any extra `quill:` keys.

package/bundler/wasm_bg.js

@@ -664,6 +664,29 @@ export class Quill {
             wasm.__wbindgen_export4(deferred1_0, deferred1_1, 1);
         }
     }
+    /**
+     * The `example` reference document — the illustrative "show me a
+     * filled-out one." Each field renders its `example:`, else its
+     * `default:`, else the type-empty zero value, with no `<must-fill>`
+     * sentinels. See `prose/canon/BLUEPRINT.md`.
+     * @returns {string}
+     */
+    get example() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.quill_example(retptr, this.__wbg_ptr);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            deferred1_0 = r0;
+            deferred1_1 = r1;
+            return getStringFromWasm0(r0, r1);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+            wasm.__wbindgen_export4(deferred1_0, deferred1_1, 1);
+        }
+    }
     /**
      * The schema-aware form view of `doc`. Read-only snapshot at call time;
      * subsequent edits to `doc` require calling `form` again.

package/bundler/wasm_bg.wasm.d.ts

@@ -40,6 +40,7 @@ export const quill_backendId: (a: number, b: number) => void;
 export const quill_blankCard: (a: number, b: number, c: number, d: number) => void;
 export const quill_blankMain: (a: number, b: number) => void;
 export const quill_blueprint: (a: number, b: number) => void;
+export const quill_example: (a: number, b: number) => void;
 export const quill_form: (a: number, b: number, c: number) => void;
 export const quill_metadata: (a: number) => number;
 export const quill_open: (a: number, b: number, c: number) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quillmark/wasm",
-  "version": "0.85.0",
+  "version": "0.87.0",
   "description": "WebAssembly bindings for quillmark",
   "type": "module",
   "license": "MIT OR Apache-2.0",
@@ -16,7 +16,8 @@
     "bundler/wasm_bg.js",
     "bundler/wasm_bg.wasm.d.ts",
     "bundler/wasm.js",
-    "bundler/wasm.d.ts"
+    "bundler/wasm.d.ts",
+    "CHANGELOG.md"
   ],
   "main": "./bundler/wasm.js",
   "module": "./bundler/wasm.js",