@quillmark/wasm 0.105.0 → 0.107.0

package/CHANGELOG.md

@@ -1,5 +1,393 @@
 # 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
+  container, so `form-field(field: "classification.poc")` and
+  `field-region("address.city")` name a cell rather than the container holding
+  it. Two generated address tables gate the step the way `array_fields` gates
+  the index step, and a typed dictionary and a variant container reach both
+  alike: `classification.value` addresses the discriminant, `classification.poc`
+  a variant cell in any world. The pdfform binder descends a variant container
+  to match, so one address binds on either backend where `address.city` bound
+  only on pdfform and asserted on Typst. **Region addresses shift** for a plate
+  that reads a container property directly: `#data.classification.poc` regions
+  as `classification.poc` where it regioned as `classification`, and `fieldAt`
+  answers the same. A container read whole is unchanged, as is a read of a key
+  the container does not declare.
+- feat(core,wasm)!: an `enum` may declare `variants:`, a per-member field set
+  that exists only in the world where the discriminant holds that member. This
+  is the DSL's first cross-field shape, and it replaces the `cui_`-prefix
+  convention with one the engine checks: `must_fill` inside a variant keeps its
+  ordinary `default:`-presence derivation, so it reads *required in this world* —
+  a `poc` obliged on a CUI memo and silent on every other one, the thing
+  `must_fill` alone could not say. **Breaking**: declaring `variants:` changes
+  the field's resting shape at every projection, from a bare string to a
+  container, `{value: <member>, …that member's fields}`; the bare scalar
+  (`classification: CUI`) is still accepted as the spelling of a world carrying
+  no answers, and coercion normalizes both. The wire carries exactly the live
+  world, so a plate reads a variant field inside the `values ∪ blank` branch it
+  already owes the enum, and inside that branch every declared field is present
+  and needs no guard. A value stranded by a discriminant flip is kept and warned
+  (`validation::out_of_variant`), never dropped at coercion or gated at render.
+  The ceiling is enforced at load, not discovered at render: a variant carries
+  plain data only, sits at card level only, and cannot declare `value`. The
+  transform schema projects the container with every world's fields flattened
+  under `properties`, since a binding built once against a schema must address a
+  field today's document has not selected; member scoping stays on the
+  declaration view, where `schema()` emits `variants:` keyed by member.
+  `FieldSchema` gains `variants` and `variant_field` (the cell a name declares
+  under any world); `VariantFields` and `VARIANT_DISCRIMINANT_KEY` are new.
+- feat(fixtures)!: `usaf_memo`'s four `cui_*` fields move under
+  `classification`'s `CUI` variant as `controlled_by`, `poc`, `category`, and
+  `limited_dissemination`. `controlled_by` and `poc` drop their `default: ""`
+  and are therefore obliged — on a CUI memo only, which is what DoDM 5200.48
+  actually requires and what the flat spelling could state only in
+  `description:` prose. A document writes `classification: {value: CUI, …}` and
+  a plate reads `data.classification.value`.
+- feat(typst): `field-region(field, body)` claims the ink `body` draws for a
+  schema field, so a plate can tie content it *composes* — a banner keyed on a
+  field, a package-built block, a computed table — to `session.regions()` and
+  `session.fieldAt(..)`. Layout-neutral: `body` is returned untouched between two
+  invisible `metadata` markers. It is a **fallback** claim, never an override:
+  ink already tracked to a field keeps that field, so wrapping is purely
+  additive and cannot retarget. Each *call* claims independently, so a wrapper
+  invoked once per card yields one region per card — the way a card's scalar
+  fields get regions at all, reading as they do from a loop variable that carries
+  no per-instance identity. The marker stack persists across pages so a claim can
+  span a page break, which leaves a claim whose closing marker never reaches a
+  frame bounded by nothing: it would take every unattributed piece of ink to the
+  end of the document. Those are found before the scan and suppressed in both the
+  region and point queries — an unbounded claim yields nothing rather than
+  everything — and reported as a `typst::unclosed_field_region` warning naming
+  the field, since only the plate author can act on it. Typst does not separate
+  the two markers on its own — they are siblings in content flow — but a plate
+  emitting the call's return value in parts can.
+- feat(typst,pdf): `form-field` takes `font`, `size`, and `align`, so an
+  injected widget's value can be set to match the type around it. A widget was
+  fixed at Helvetica, auto-size, left: auto-size makes the rendered size a
+  function of both box height and how much the user has typed, and left
+  justification cannot be overcome by geometry, because a fillable box is sized
+  for the longest plausible value rather than the value in it. A right-aligned
+  fill-in — a USAF memo's date, say — was unreachable. `font` is one of
+  `"helvetica"`/`"times"`/`"courier"`, a widget being unable to carry a font
+  program; `size` is an absolute length or `auto` for the old behavior; `align`
+  is `"left"`/`"center"`/`"right"` and lands in `/Q`. All three are rejected on
+  `"checkbox"` and `"signature"`, which carry no variable text. `FieldSpec`
+  gains `font`, `font_size`, and `align` (`FormFont` and `TextAlign` are new).
+  A field that sets none of them stamps byte-identically to before, and
+  `pdfform` is untouched: `form.json` still carries no styling, so the flatten
+  path and canvas preview are unchanged.
+- fix(fixtures): the `usaf_memo` indorsement date widget is set in the memo's
+  own 12pt Times and ends on the right margin, where the date it stands in for
+  would have ended. It was auto-sized Helvetica starting at the fill-in rule's
+  left end. Sizing it exposed that the rule-width box clips a real date — "28
+  September 2026" sets 93pt at 12pt Times against a 72pt box, and a fixed size
+  clips where auto-size had silently shrunk — so the widget is now 10em wide
+  and hangs off the rule's right edge, overrunning leftwards into the
+  whitespace a printed date grows into. Sized in ems of its own face rather
+  than inches because `font_size` is a document field with no ceiling: an inch
+  width would stay put while the text inside it grew. 10em clears both
+  orderings at any body size (DAF's "September 28, 2026" is the widest at
+  8.03em; USAF's "28 September 2026" is 7.78em). `date-placeholder-line` seats
+  it with a measured `dx` rather than `place(bottom + right)`, Typst clamping
+  an overflowing alignment back to zero, which leaves `right` indistinguishable
+  from `left`. That helper draws no rule now and is named `date-placeholder`
+  rather than `date-placeholder-line`: the widget carries the date, and a rule
+  under a widget wider than it underlines only the fraction of the value narrow
+  enough to sit over it. It is package-internal, not exported from `lib.typ`.
+- fix(core): a name two variants declare *differently* is a load error,
+  `quill::variant_field_collision`. The name is one cell of the container
+  whichever world brings it into play — neither the coercion lookup nor the
+  transform schema consults the discriminant to fill it — so two readings of it
+  coerced a live value under the other world's type: a document selecting a
+  world whose `note` is `integer` had its `42` coerced to `"42"` by a sibling
+  world's `string` and then failed `validation::type_mismatch`, undraftable and
+  blamed for a string it never wrote. Identical declarations, which is what
+  repeating a shared field set or sharing a YAML anchor produces, collapse to
+  that one cell without loss and stay legal.
+- fix(core,wasm,python)!: `EditError::UnknownField` carries the in-field path
+  `FieldDecode` and `FieldNotContent` carry. A property an `object` field does
+  not declare — `get_content_at("address", [Key("zip")])` against an `address`
+  with no `zip` — reported `field 'zip' is not declared in the schema`, which
+  reads as a claim about a top-level field and collides outright when a real
+  top-level field shares the name. It now reports
+  `field 'address.zip' is not declared in the schema` and anchors the
+  diagnostic at `main.address.zip`, so the caller can tell an undeclared
+  property from an undeclared field. **Breaking**: the variant is a struct
+  variant, `UnknownField { field, at }`, matching the two siblings; `field`
+  stays a bare field name, and the `edit::unknown_field` code, its `field` arg
+  and the whole-field message are unchanged.
+- fix(python): declaring `license-files` ships the `LICENSE` the sdist metadata
+  names, which PyPI rejected the sdist for lacking. v0.104.0 and v0.105.0 are
+  wheels only.
+
 ## v0.105.0 - 2026-08-14
 
 - feat(core,wasm,python)!: a `Content` nested inside a composite field is

package/backends/pdfform/wasm.d.ts

@@ -462,6 +462,11 @@ export interface QuillFieldSchema {
     /** The closed set of allowed values. Required on `type: "enum"`, and valid
      *  nowhere else. */
     values?: string[];
+    /** Per-member field sets on a card-level `type: "enum"` field, keyed by
+     *  member: the fields that exist only where the discriminant holds that
+     *  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>>;
     /** Whether a human must author the field. Absent, it derives from
      *  `default`: a defaulted field is unobliged, a defaultless one obliged. */
     must_fill?: boolean;

package/backends/typst/wasm.d.ts

@@ -462,6 +462,11 @@ export interface QuillFieldSchema {
     /** The closed set of allowed values. Required on `type: "enum"`, and valid
      *  nowhere else. */
     values?: string[];
+    /** Per-member field sets on a card-level `type: "enum"` field, keyed by
+     *  member: the fields that exist only where the discriminant holds that
+     *  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>>;
     /** Whether a human must author the field. Absent, it derives from
      *  `default`: a defaulted field is unobliged, a defaultless one obliged. */
     must_fill?: boolean;

package/core/wasm.d.ts

@@ -407,6 +407,11 @@ export interface QuillFieldSchema {
     /** The closed set of allowed values. Required on `type: "enum"`, and valid
      *  nowhere else. */
     values?: string[];
+    /** Per-member field sets on a card-level `type: "enum"` field, keyed by
+     *  member: the fields that exist only where the discriminant holds that
+     *  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>>;
     /** Whether a human must author the field. Absent, it derives from
      *  `default`: a defaulted field is unobliged, a defaultless one obliged. */
     must_fill?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quillmark/wasm",
-  "version": "0.105.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