@quillmark/wasm 0.106.0 → 0.107.0

package/CHANGELOG.md

@@ -1,5 +1,271 @@
 # Changelog
 
+## v0.107.0 - 2026-08-17
+
+- fix(typst): `display(field, ..)` validates its address against the schema, the
+  assert `form-field` and `field-region` already carry. It is the one helper keyed
+  by address rather than by value, and it was the one accepting an address the
+  schema does not have: `display("issed", "[year]")` compiled, drew nothing, and
+  reported nothing — the failure a plate author is least placed to see, a card
+  address being a string the plate builds by concatenating `$path`. `_qm-display`
+  cannot catch it, carrying an entry per *present* date, so a blank date and a
+  typo are absent from it alike; `_qm-known-path` answers about the schema and
+  tells the two apart. A known address carrying no date still returns `none`, so
+  a `== none` fallback is unchanged: the assert is about the address, the `none`
+  about the value.
+- fix: **a container's own `default:` reaches the plate as content.** The render
+  floor read `default_content` only for a `richtext`/`plaintext` leaf. An
+  `object` or `array` carrying its `default:` on the container fell through to
+  the raw literal instead, crossing as unimported markdown where every other
+  content position delivers a canonical content object. The companion was
+  already cached and never read. The floor now keys off the cache — present is
+  the form to commit, absent over a content-bearing tree blank-fills — which
+  covers leaf and container alike and drops the type test. `usaf_memo`'s
+  `references` (`array<richtext(inline)>`, `default: []`) carried the same
+  defect, invisible only because the list was empty.
+- **breaking** a container-shaped `default:`/`example:` on a variant-bearing
+  enum is a load error (`quill::default_type_mismatch`,
+  `quill::example_type_mismatch`). A quill declaring one loaded before, so the
+  upgrade reads as a quill that stopped loading rather than as a fix.
+  The container is the shape a *document* writes. As a schema literal it cached
+  no content form and yielded no discriminant, so the field blank-filled in
+  silence as if nothing were declared. The diagnostic names the discriminant
+  spelling instead, which is where a world's cells carry their own literals.
+  Scalar literals are unaffected.
+
+- feat: **every type nests at every depth**. A property or an element is an
+  ordinary field, so it carries whatever a card-level field carries, itself
+  included: `object<array<string>>`, `array<array<integer>>`, a typed table whose
+  row holds a typed dictionary, and a variant cell holding either.
+  `quill::nested_object_not_supported` and `quill::nested_array_not_supported`
+  are gone, and `ShapePosition`'s three positions collapse to the one question
+  the walk still asks — is this card level, where `variants:` and `ui.group` are
+  the two keys that live. A widening: every quill that loaded before loads
+  unchanged.
+  The depth budget was what the flat address tables existed for.
+  `SchemaMeta` carried six name-keyed tables (`array_fields`, `object_fields`
+  and their card twins) so the helper's `_qm-known-path` could enumerate two
+  suffix steps rather than derive a grammar; they are replaced by one address
+  tree — the schema pruned to the steps it offers — that the helper and the span
+  scan both walk, converging on the unbounded descent `pdfform::bind` always
+  had. Three components deriving an address become one walk each side of the
+  seam, and `quillmark/tests/address_grammar.rs` pins the two against the deep
+  shapes as well as the shallow ones.
+  `variants:` stays card-level, now on its own reasoning rather than by
+  inheriting the depth ban: a variant's shape is a function of the schema *and*
+  the discriminant, and the union projection, the once-bound form, the plate's
+  single branch and `validation::out_of_variant` each hold because that gap is
+  one level deep ([SCHEMAS.md](prose/canon/SCHEMAS.md) §"Enum variants"). An
+  array-valued variant cell used to report `nested_array_not_supported`, whose
+  message named array elements and object properties — neither the situation;
+  the shape is now legal and `quill::variant_placement` is left saying only what
+  it means.
+- fix: `blueprint()` expands a container at every depth. `build_property_mapping`
+  spent each property through the scalar builder, so a nested `object` or typed
+  table rendered as `key: null # object` — its own properties, their markers and
+  their annotations absent — where the same shape one level up expanded. It now
+  recurses, and the card-level and nested paths are one implementation, so a
+  `default:` covers its subtree identically wherever it is declared. No
+  document changes shape: the shapes this fixes could not be declared before.
+- fix: a content leaf's `default:` reaches the plate from **every** position it
+  can be declared in, not only card level. The load pass that imports each
+  richtext/plaintext literal into its companion cache walked the card's field
+  map, so an `object` property, a typed-table row property and a variant cell
+  each kept their authored `default:` and cached nothing; the render floor read
+  the leaf's empty companion and blank-filled. A document authoring only the
+  container (`dict: {}`, `rows: [{}]`, `c: {value: CUI}`) rendered correctly
+  with the author's default missing, and nothing upstream had anything to
+  report. The walk now recurses `properties` / `items` / `variants`, the shapes
+  `field_contains_content` already descended, so such a document now renders
+  **with** the author's default — a render-output change for any quill that
+  declared one. Importing a literal is also what checks it, so a nested
+  `richtext(inline)` violation — in a `default:` or an `example:` — now fails
+  load as a card-level one always has, naming the leaf's declaration path.
+  **Breaking on that second count**: the literal loaded before, so a quill
+  carrying one stops loading. Nested `example:` *surfacing* was never broken:
+  the blueprint prints the raw literal at every depth.
+- **breaking** typst: a plate's direct read of a typed-table row cell regions on
+  the cell (`refs.0.org`), where it regioned on the whole array before — a
+  *wrong* address, not a missing one, routing a click on the org cell to the
+  entire table. The span scan was the third component deriving a schema address
+  and the one left at the one-level ceiling: 0.106 lifted the lowering walk and
+  `_qm-known-path` to the row property, so the three no longer agreed, and the
+  scan is the one that decides what a *read* is attributed to. It now takes the
+  index step (`.at(n)`, the only spelling Typst has for an array index) and then
+  the row property, gated on the `array_fields` table. Each step is its own
+  address, so a whole-row read names the row (`refs.0`) and a primitive
+  element's read names the element (`tags.0`); a negative index and an
+  undeclared row key mint nothing and fall back as before. Consumers keying on
+  the array's address for element ink see the narrower address instead. Explicit
+  `field-region` / `form-field` claims are unchanged, and the alias lane keeps
+  parity: `#let row = data.refs.at(0)` … `#row.org` regions on `refs.0.org`.
+- test: one table pins the schema address grammar on both backends
+  (`quillmark/tests/address_grammar.rs`), covering every position the nesting
+  contract admits, each position's card twin, and the rejects that bound each
+  step. `PLATE_DATA.md` promises a plate author that one address binds on
+  either backend, and the grammar is written twice to keep it — an unbounded
+  schema walk in `pdfform::bind`, an enumeration of the suffix forms in the
+  Typst helper's `_qm-known-path` — reading two different projections of the
+  same `QuillConfig`, so either side can move alone. `pdfform` exports
+  `resolves_schema_address` (`#[doc(hidden)]`) so the pin can ask both the same
+  question. A body address is the plate grammar's alone and is pinned as such.
+
+- **breaking** typst: lowering dispatches on the schema node beside each value
+  rather than on tables of top-level field names, so a declared type means the
+  same thing wherever it is declared. A `date`, `richtext` or `plaintext`
+  declared inside an `object` or an `array` row reached the plate as its raw
+  wire value before — a bare string for a date, and for a rich field the
+  *internal canonical-content JSON*, rendered as a Typst dict — while the same
+  type one level up lowered correctly. Ten of the twelve nested positions the
+  schema admits degraded that way, silently: core coerced and validated the
+  value correctly, so nothing upstream had anything to report. `contact.note`
+  is now a markup block, `contact.reply_by` and `rows.0.on` are `datetime`s,
+  and `_qm-plaintext` gains the nested entries that closed the
+  `plaintext(field)` escape hatch. The walk is the inverse of the one
+  `build_transform_schema` builds the node with, so it cannot be shallower than
+  the schema is.
+- **breaking** typst: a `date` / `datetime` field lowers to a **native**
+  `datetime`, not the `(value:, display:)` wrapper. `data.issued.year()`,
+  `data.issued < data.due` and handing the field to a datetime-consuming
+  package are ordinary Typst; `.value` and the paren form `(data.issued.display)(..)`
+  are hard Typst compile errors, never a silent degrade, and all consumers are
+  first party. A date has no canonical rendering the way authored text does —
+  every rendering of `2026-01-02` is a typographic decision the plate owns — so
+  it lowers to its value and reaches ink by address instead.
+- feat(typst): `display(field, ..args)`, a date field's content projection,
+  keyed by schema address rather than carried on the value. It places rendered
+  ink whose glyphs are born in generated source, so a date formatted through a
+  `#let` binding, a per-card loop variable, or a vendored package keeps a
+  region on its schema field — the affordance the value-object existed to buy,
+  now available to any date at any depth without shaping the value. `none` for
+  a blank date, so a `== none` fallback still fires. The rule plates follow:
+  want a value → `data.<field>`; want clickable ink → `display("<field>", ..)`.
+- feat: a variant cell may carry **any type a card field may**, prose and dates
+  included — `quill::variant_field_type` is gone. The load error existed because
+  lowering read flat top-level name tables that could not descend into a
+  container, so a `date` or `richtext` cell inside a variant would have loaded
+  clean and reached the plate as its raw wire value; the schema-node walk reads
+  the cell's own declaration, leaving the ceiling nothing to protect. Every value
+  surface already descended per live-world cell — coercion through
+  `conform_value`, validation through `validate_value`, the render floor through
+  `resolve_value` — so the widening needed one real fix:
+  `field_contains_content` returned `false` for a variant container on the
+  strength of this very guard, which would have silently skipped the content
+  companion caches, the resting-form conversion and the seed path for a variant
+  content cell. It now answers on the union of the worlds' cells. Containers
+  are included: "every type nests at every depth" lands in this same release, so
+  a variant cell holds a typed table or a typed dictionary like any other
+  position. `variants:` itself stays card-level (`quill::variant_placement`) on
+  the reasoning stated there.
+
+- **breaking** typst: the `plaintext(field)` helper and its `_qm-plaintext`
+  table are removed. Shipped in 0.94 as the sanctioned content→`str` coercion,
+  it never acquired a caller: no plate, no vendored package, and no binding
+  surface referenced it, and the `create-auto-grid` consumer its own docstring
+  cited passes an `array<string>` rather than a content field, so the only
+  things exercising it were its three tests. It also carried a three-way name
+  collision with the `plaintext` field type and that type's document-layer
+  resting shape, which took a standing caveat in canon and the template to hold
+  down. A plate that needs a `str` from a content field now has no route, which
+  is the honest state of the requirement: reinstating it is additive and cheap
+  when a plate actually asks.
+- feat(typst): a typed table's row property (`refs.0.org`) is a writable
+  schema address. `form-field(field:)` and `field-region` capped at one suffix
+  step while pdfform's resolver descended unboundedly, so a shape
+  `ShapePosition` explicitly admits bound on one backend only, against
+  `PLATE_DATA.md`'s claim that one address binds on either. `array_fields` now
+  carries each array's row property names, the same shape `object_fields`
+  already had.
+- fix(typst): a non-blank date the shared parsers reject raises
+  `backend::invalid_date` from codegen rather than a pre-pass over top-level
+  name tables, so the check covers every depth. Only a direct `apply` can
+  deliver one; coercion parses the same way.
+- feat(typst): a scalar read through a `let` alias regions on the address the
+  chain it names would carry, so `#let c = data.classification` … `#c.poc`
+  surfaces `classification.poc` where it surfaced nothing at all — not the
+  container's address, absent. Binding a container once and stepping into it
+  three times is the refactor 0.106's property addressing invites, and it cost
+  the address silently, the document still rendering correctly. An alias holds
+  only where the plate binds the name exactly once to one whole `data` chain: a
+  name a second `let`, a closure parameter, a loop pattern, an import, or an
+  assignment could rebind is dropped rather than risk attributing another
+  value's ink to the field, and a wildcard import disqualifies every alias.
+  Which name is followed is half the rule; which *occurrence* is the other half,
+  since a schema field name collides freely with the parameter names of a callee
+  the plate never defines (`date`, `title`, `caption`, `align`, `subject`). Only
+  an occurrence that reads the binding anchors: an identifier spelling the alias
+  as a named argument (`#text(size: 12pt)`), a dict key, another value's field
+  (`#styles.subject`) or an imported item's path draws no ink off the field, and
+  a window minted over one would carry a *wrong* address rather than a missing
+  one.
+  Laundering past that — a function parameter, a destructured binding, a
+  per-card loop variable — is unchanged and still needs a `field-region` claim,
+  now stated for plate authors under "Which Reads Get Regions" in the Typst
+  backend guide. Content and date fields are unaffected: their ink is born in
+  generated code.
+
+- feat(wasm): `VARIANT_DISCRIMINANT_KEY` joins the runtime's static exports,
+  beside `MAIN_CARD_ADDR`. v0.106.0 announced the constant as new API but shipped
+  it to Rust only, leaving a JS consumer reading or writing a variant container
+  to spell `"value"` itself — a hardcoded copy of the one value whose purpose is
+  to not be hardcoded, at the seam where the two can drift unobserved, since the
+  key crosses the boundary inside untyped container data. The `.d.ts` types it as
+  the string *literal*, which `string` would stop narrowing an index into the
+  container. `known_names_drift.rs` pins both spellings against the Rust
+  constant, the guard the hand-spelled name tables beside it already carry.
+  `VariantFields` stays Rust-only: it is a type alias the TypeScript surface
+  already inlines as `QuillFieldSchema.variants`, naming no shape a consumer
+  builds.
+- docs: `0.105-to-0.106.md`, the migration guide v0.106.0 shipped without. It
+  leads with the region-address shift rather than the three `!` entries: the
+  changelog is organized by feature, and the address step is one clause inside a
+  long entry while being the item most likely to break a working consumer, since
+  `FieldRegion.field` is a bare `string` that no type checker reports a grammar
+  change under. The guide states both gates on the step, and points a consumer at
+  `doc.pathFor` for the prefix grammar it would otherwise match as a literal —
+  with that helper's limit stated, a field name passing through it verbatim.
+  `CONTRIBUTING.md` gains the two rules that would have caught the gap: `!` marks
+  an observable-contract shift even where no type changes, and a release carrying
+  one ships its guide.
+- docs: `0.106-to-0.107.md`, this release's guide, under the rule the entry above
+  adds. It leads with the region-address index step — `main.refs[0].org` where
+  `main.refs` stood, a wrong address rather than a missing one — and then with
+  the two schema literals that stop a quill loading, since those read as a build
+  that broke rather than as a fix. `ERROR.md` names `display(..)` as the
+  address-keyed template-author contract, `plaintext(..)` having been removed
+  here.
+
+<!-- seed: commits since v0.106.0, confirm the entries above cover them, then delete this comment
+- fix: a container's own `default:` crosses as content, or is refused
+- fix(typst): anchor a `let` alias only where the name is read
+- fix(typst): display validates its schema address
+- fix(docs): point the variants cross-reference at this page's own anchor
+- fix(docs): link canon by URL, not by a path outside the docs tree
+- docs: dense-prose pass over the nesting collapse
+- feat: every type nests at every depth
+- docs: dense-prose pass over the two address walks
+- feat(typst)!: the span scan takes the index step, so a row cell read anchors on the cell
+- fix: a nested content leaf's `default:` reaches the plate
+- docs: dense-prose pass over the address-grammar pin
+- test: pin the schema address grammar across both backends
+- Carry the prose style in CLAUDE.md at minimum size
+- Drop two CLAUDE.md lines that steer toward defaults
+- Cut the rules that steer toward defaults
+- docs: dense-prose pass over the lowering walk
+- Cut two lines that restated defaults
+- Rewrite dense-prose as a project-agnostic skill
+- feat!: a variant carries any leaf type, prose and dates included
+- refactor(typst)!: delete the `plaintext(field)` projection
+- feat(typst)!: depth-invariant lowering, and `date` as a native `datetime`
+- docs: dense-prose pass over the alias pass
+- docs: a bound read keeps its address, and what still needs a claim
+- fix(typst): disqualify aliases on a wildcard import in either order
+- feat(typst): follow a single-assignment `let` alias to its schema address
+- feat(wasm): export VARIANT_DISCRIMINANT_KEY to the runtime surface
+- docs: the 0.105 → 0.106 migration guide, and the rules that missed it
+-->
+
+
 ## v0.106.0 - 2026-08-16
 
 - feat(typst,pdfform): a schema address may step one property into a declared
@@ -122,22 +388,6 @@
   names, which PyPI rejected the sdist for lacking. v0.104.0 and v0.105.0 are
   wheels only.
 
-<!-- seed: commits since v0.105.0, confirm the entries above cover them, then delete this comment
-- chore(repo): union-merge CHANGELOG.md
-- feat: migrate usaf_memo to enum variants, document the axis
-- feat(core): enum variants — fields that exist only for one enum value
-- fix(fixtures): drop the rule under the indorsement date
-- fix(fixtures): size the indorsement date widget in ems, not inches
-- fix(fixtures): set the memo's indorsement date widget like a date
-- feat(typst,pdf): font, size, and align on injected form fields
-- Make the usaf_memo indorsement's blank date a bound fill-in widget
-- Compress the field-region prose
-- Add `field-region` so plates can tie composed content to a field
-- fix(python): declare license-files so the sdist ships its LICENSE
-- Anchor an undeclared property at the property, not at a bare name
--->
-
-
 ## v0.105.0 - 2026-08-14
 
 - feat(core,wasm,python)!: a `Content` nested inside a composite field is

package/package.json

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

package/runtime/runtime.d.ts

@@ -84,6 +84,16 @@ import type { CardAddr } from '../core/wasm.js';
  */
 export declare const MAIN_CARD_ADDR: CardAddr;
 
+/**
+ * The key carrying the discriminant inside a variant-bearing enum's value. A
+ * field declaring `variants:` rests as `{value: <member>, …that member's
+ * fields}`, so reading or writing one means naming this key; it crosses the
+ * boundary inside untyped container data, with no type to read it off.
+ * Reserved: no variant may declare a field under it, and
+ * {@link QuillFieldSchema.variants}, keyed by member, never contains it.
+ */
+export declare const VARIANT_DISCRIMINANT_KEY: 'value';
+
 // Core-build types consumers read off `Quill`/`Document`.
 export type {
 	Card,

package/runtime/runtime.js

@@ -206,6 +206,23 @@ async function instantiateCore(source) {
  */
 export const MAIN_CARD_ADDR = Object.freeze({});
 
+// ── The variant discriminant key ────────────────────────────────────────────
+/**
+ * The key carrying the discriminant inside a variant-bearing enum's value.
+ *
+ * A field declaring `variants:` rests as a container, `{value: <member>, …that
+ * member's fields}`, so reading or writing one means naming this key:
+ * `doc.storeFields(MAIN_CARD_ADDR, { classification: { [VARIANT_DISCRIMINANT_KEY]: 'CUI' } })`.
+ * It crosses the boundary inside untyped container data, with no type to read
+ * it off.
+ *
+ * Reserved: no variant may declare a field under it
+ * (`quill::variant_reserved_field_name`), and `QuillFieldSchema.variants`,
+ * keyed by member, never contains it.
+ * @type {'value'}
+ */
+export const VARIANT_DISCRIMINANT_KEY = 'value';
+
 /**
  * Narrow an unknown caught value to a `QuillmarkError`, the error every
  * fallible method in this package throws: a real `Error` with a non-empty