@quillmark/wasm 0.113.0 → 0.115.0

package/CHANGELOG.md

@@ -1,5 +1,302 @@
 # Changelog
 
+## v0.115.0 - 2026-09-22
+
+Upgrade path: [0.114 → 0.115](docs/migrations/0.114-to-0.115.md).
+
+### The quill authoring contract
+
+- feat(core)!: **a `matrix` member mapping takes the ordinary ladder.** Two
+  rules decided what a stored member spelling meant — a bare scalar is the tick,
+  and a mapping naming no `held` is held — and the second retires. A member is
+  an `object` of a synthesized `held: {type: boolean, default: false}` beside
+  its columns, so a mapping is the member object already and the tick it names
+  no key for resolves as every other absent cell does, to its `default:`. The
+  old rule overrode that ladder for one key in one type, and bought a spelling
+  convenience for it: two mappings one key apart meant opposite ticks, the
+  shorter one ticked, and any producer building the member object without
+  conforming — an editor writing a column before the tick, a serde-built
+  payload, `{}` — set a tick it never wrote. `{ detail: X }` is now unheld with
+  its detail retained, which is what `{ held: false, detail: X }` already meant;
+  the bare scalar and every mapping naming `held` are unchanged. What remains is
+  exactly `conform_variant`'s bare-scalar rule, so `SCHEMAS.md` §Matrix lists
+  three things as the type's own rather than four. The flip is silent — the
+  value is well-typed under both readings, and a defaultless column's
+  `validation::must_fill` leaves with the tick it was gated on — so the upgrade
+  guide leads with it. (#1860)
+- feat(core): **a typed dictionary's property opens a variant world.**
+  `variants:` was card-level, so a conditional block had to sit at the top of a
+  card even where the fields it governs belong to a dictionary. The rule was
+  never about depth: what stays one level deep is the gap between a field's
+  *declared* shape and its *live* one, and a dictionary's own shape is the
+  schema's — so a world opened there deepens the address and leaves the gap
+  alone. `header.classification` reads, binds, branches and strands exactly as
+  `classification` does, one step down. Every other position would deepen the
+  gap and still refuses one: an array element, whose liveness would vary per
+  index against a form bound once; a matrix column, inside a grid the page
+  prints in full; and another variant's cell, which would make the plate's one
+  branch a tree. `quill::variant_placement` now names the position carrying the
+  ban rather than restating the old rule, and the ban is **sticky** — an object
+  inside any of them inherits it instead of laundering a world into a position
+  that cannot hold one. The surfaces that dispatch on the container before
+  walking the type needed nothing (coercion, validation, the render floor,
+  conditional `must_fill`, the transform schema, `acroform` binding); the three
+  that scanned card fields now descend, so `validation::out_of_variant` finds a
+  strand at `main.header.classification.controlled_by`, the blueprint seats a
+  world's cells — live or commented — at the dictionary's indent, and the seed
+  resolves a nested discriminant before walking its field set.
+- feat(core)!: **`ui.layout: table` contracts its columns.** The key was checked
+  for its outer shape alone — `type: array` whose `items` is an `object` — so a
+  row holding a container loaded clean and no editor could draw it: the author
+  wrote a key, the loader took it, and a surface ignored it with no signal at
+  either end. A column that is not a leaf is now
+  `quill::table_column_not_flat`, naming the column (`appendices[].entries`)
+  rather than the field. This splits the key along a seam it always had: a
+  **contract** that every column is a leaf, settled at load, and a **request**
+  to draw a grid, which an editor still declines for a width or a cell renderer
+  it does not have. Shape leaves the decline list, since shape was never a
+  consumer's judgement to make. The boundary is containment, not height — prose
+  is a column whatever its `inline`, because how tall a cell renders is the
+  editor's call and what it contains is not. `FieldType::is_leaf` is the one
+  definition, an exhaustive match a new type cannot skip, and `acroform`'s
+  `is_scalar_or_prose` is gone in favor of it: the same question had two
+  answers in two crates. Part of #1859.
+- feat(core,wasm,python): **the empty document has a constructor.**
+  `Quill::empty_document()` is `Document::new` under the quill's own reference,
+  so the three canonical documents are three constructors beside
+  `QuillConfig::blueprint()` and `Quill::seed_document()`, and no caller spells
+  `name@version` to reach the one a plate is bound to render. `quiver_test.rs`
+  reads it rather than formatting the two-line markdown itself. The bindings
+  carry it as `Quill.emptyDocument()` / `Quill.empty_document()`.
+- feat(cli)!: **`quillmark validate` compiles the plate.** It renders the empty
+  document, the blueprint and the seed through the quill's backend at the
+  backend's first declared format, and reports each failure as a
+  `cli::canonical_document_failed` error naming which of the three it is,
+  followed by the backend's own diagnostics. The contract that a plate renders
+  the empty document was checked for the fixtures quiver alone, and `render`
+  with no input file renders the seed, the fullest of the three: a plate that
+  reads a blank badly passed both. A quill whose plate does not compile now
+  exits `1` where it exited `0`, and a backend that does not resolve is
+  `cli::backend_unresolved` followed by the engine's own diagnostic. A render's
+  warnings join the `-v` list, and `validate --no-render` is the configuration
+  read on its own. Closes #1844.
+
+### The content model
+
+- refactor(content)!: **an island stores its value, not its provenance.** `Loss`
+  had one minting rule — a table cell dropping an inline image's url — and no
+  reader: export dispatches on an island's `type`, the Typst emitter and the
+  acroform binder never looked, and an `islandOps` `set` stored whatever class
+  the op named. Two cells written `| a cat |` and `| ![a cat](cat.png) |` mint
+  equal `props` and differ only in the markdown behind them, which the
+  projection has no syntax to carry back out, so the class survived neither a
+  `to_markdown` → `from_markdown` hop nor re-derivation from the row holding it
+  — which is why the content fixed point had to be stated modulo it. An
+  island's canonical form is `{id, type, props}`, the fixed point is exact, and
+  the closed vocabularies cover the four discriminators a projection dispatches
+  on. `Loss`, `Island::loss`, `Island::with_loss`, `IslandType::default_loss`,
+  `ContentIsland.loss` and `ContentLossClass` are deleted; a stored row spelling
+  `loss` opens with the key ignored and absent from what comes back, and a
+  `loss` on an authored island or an `islandOps` entry is ignored rather than
+  refused. A host that surfaced the class surfaces the drop at the import
+  instead, where the markdown it is about is still in hand. Closes #1757.
+- refactor(content,core,wasm,python)!: **a block island's line is a `para`, and
+  `LineKind::Island` is gone.** The kind was a second copy of a fact the island
+  beside it already carried: markdown writes a `table` as a block and an `image`
+  inline, so `IslandType::block_only` settled which line a lone slot sat on and
+  `normalize` wrote that answer back over whatever was stored. Every read site
+  now asks the island — export already dispatched on the type, the Typst emitter
+  already lowered `Island` as `Para`, and the one fact the kind alone still
+  answered, "this block renders one line", moves to the new public
+  `Content::block_island_at`, which `normalize` reads beside
+  `takes_continuations` when it clears a stranded `continues`. Landing a block
+  island is two channels rather than three: the delta opens the line, the island
+  op fills it, and the `setKind` goes. The TS `ContentLineKind` loses its
+  `{ kind: "island" }` arm, so a host branching on it typechecks red; a `setKind`
+  still naming `island` lands as the `para` it would have settled to.
+- refactor(core)!: **the storage tag is `quillmark/document@0.115.0`.** The two
+  lines above move canonical bytes — the `loss` key for every document holding
+  an island, the line kind for every document holding a table — so content
+  hashes recompute once on those rows. `DocumentV0_112_0` freezes with a raw
+  `body` and the new `DocumentV0_115_0` carries the `CanonicalContent`; the hop
+  between them is that body's decode, and `V0_93_0 → V0_112_0` becomes a retag
+  now that both trees spell `body` raw. Stored rows need no migration: the
+  content decoder reads `island` as `para` wherever it meets it, permanently,
+  since the same spelling rests untagged inside every `richtext` field and
+  `$seed` overlay, where no hop reaches it. Closes #1647.
+
+### Schema, validation and the resolved view
+
+- refactor(core)!: **a schema is loaded, not deserialized.** `QuillConfig`,
+  `CardSchema` and `FieldSchema` serialize and no longer implement
+  `Deserialize`, and `FieldSchema::from_quill_value` is crate-internal. A field
+  arrives in two steps — the parse, which folds the sibling keys (`inline:`,
+  `values:`, `members:`, `max:`) into the type payload, and the shape walk,
+  which rejects an `object` without `properties`, an `array` without `items`,
+  an empty `properties` map, and the placements — and only `parse_fields` ran
+  both, so a config assembled through serde carried states no `Quill.yaml` can
+  reach, absorbed downstream without a diagnostic. Gating the serde path
+  instead would have duplicated the walk and collapsed its diagnostic codes
+  into `quill::field_parse_error` at that boundary. The way to a config is
+  `QuillConfig::from_yaml_with_warnings`, or a `Quill` read off a file tree;
+  serialization is untouched, so `schema()`, `schema_yaml()` and every emission
+  read the same loaded form they did. Closes #1836.
+- refactor(core,wasm)!: **a matrix roster is one flat mapping; group headings
+  are gone.** A block's `group:` was declared in the schema and absent from the
+  value, the address and the vocabulary — the blueprint emits
+  `matrix<a | b | c>` off one flat key space, so the partition reached the
+  visual editor and nowhere else, buying one shared `properties` map for a
+  schema concept, its load rules and a reserved key. `members:` is now
+  `{id: Title}` directly, `MatrixGroup`, `MATRIX_GROUP_KEY` and the TypeScript
+  `QuillMatrixGroup` are deleted, and `FieldType::Matrix` carries an
+  `IndexMap<String, String>` read through the new `FieldType::matrix_roster`,
+  which replaces `matrix_members`. The projection stops writing `group` onto
+  every member, which returns `group` to the column names a quill may declare,
+  and `quill::duplicate_matrix_member` retires: the roster is a mapping, so it
+  has one slot per id exactly as the stored value does and a duplicate is
+  unspellable on both sides. Closes #1851.
+
+### The blueprint
+
+- feat(core)!: **a dormant variant world is its own cells, commented out.** A
+  variant-bearing enum's blueprint named every world it could not show, one
+  `# when CUI: controlled_by, poc, category` line each — the one place on the
+  surface where a cell was named rather than shown, dropping the position,
+  obligation, type, description and example a cell carries. Every world now sits
+  under a `# when <MEMBER>:` header in declaration order: the selected world's
+  cells live, every other world's the same cells with a `# ` in front, at the
+  slot they would occupy live. A reader activates a world by setting the
+  discriminant and deleting `# `. One builder and one emitter serve both, so a
+  dormant line is byte-for-byte the live line, and the block round-trips through
+  `Document::parse` as the comments it is, reaching neither the validator nor
+  the render floor. Closes #1846.
+
+
+## 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/README.md

@@ -175,9 +175,9 @@ const doc = Document.storageVersionOf(content)
   : Document.fromMarkdown(content);
 ```
 
-The `schema` value (`quillmark/document@0.112.0`) is the **model version**,
+The `schema` value (`quillmark/document@0.115.0`) is the **model version**,
 not the running crate version. It is a hand-set constant, bumped only when
-the `Document` model itself changes, so every `0.112.x` patch release reads
+the `Document` model itself changes, so every `0.115.x` patch release reads
 and writes that same value.
 
 - **Upgrading is safe.** A newer build reads documents an older build's
@@ -187,8 +187,10 @@ and writes that same value.
   canonical on-disk format keeps loading across crate upgrades: there is no
   need to pin old wasm to read old data. The exception is a row a host
   authored a content construct of its own into — a line `kind`, container,
-  mark `type`, island `type` or `loss` outside the vocabulary. Those are
-  refused from 0.113 on; see that release's migration guide.
+  mark `type` or island `type` outside the vocabulary. Those are refused from
+  0.113 on; see that release's migration guide. An island `loss` is not one of
+  them: 0.115 drops the key, so a row spelling one opens whatever the class and
+  comes back without it.
 - **Downgrading is not.** `fromStored` rejects an *unknown* (i.e. newer)
   `schema` version rather than guessing at a format it predates. Don't feed
   documents written by a newer build back into an older one.

package/core/wasm.d.ts

@@ -73,9 +73,9 @@ export interface Content {
 }
 
 /** One `\n`-separated segment of `Content.text`, in order. `kind` is a closed
- * set: a role outside it is refused wherever content is decoded. Every role
- * spells its payload in `attrs`, so `kind === "heading"` narrows `attrs` to
- * `{ level: number }` with no guard. */
+ * set: `island` reads as `para`, and any other role outside it is refused
+ * wherever content is decoded. Every role spells its payload in `attrs`, so
+ * `kind === "heading"` narrows `attrs` to `{ level: number }` with no guard. */
 export type ContentLine = {
     containers: ContentContainer[];
     /** A within-block hard line break rather than a new block. Omitted (false) in the common case. */
@@ -87,7 +87,6 @@ export type ContentLineKind =
 | { kind: "para" }
 | { kind: "heading"; attrs: { level: number } }
 | { kind: "code"; attrs?: { lang?: string } }
-| { kind: "island" }
 | { kind: "rule" };
 
 /** An ancestor block a line nests inside, outermost first. Closed like
@@ -158,14 +157,10 @@ export interface ImageProps {
     alt: string;
 }
 
-/** How faithfully the markdown projection can carry an island. */
-export type ContentLossClass = "lossless" | "degraded" | "unrepresentable";
-
 /** A structured object occupying one island slot in `Content.text`. `type` is a
  * closed set, so `type === "table"` narrows `props` to `TableProps`. */
 export type ContentIsland = {
     id: string;
-    loss: ContentLossClass;
 } & (
 | { type: "table"; props: TableProps }
 | { type: "image"; props: ImageProps }
@@ -237,10 +232,12 @@ export type MarkOp =
  * metadata. `setContinues` sets or clears a line's within-block hard-break flag
  * (`ContentLine.continues`); `continues: true` lands as `false` on line 0, which
  * nothing precedes, on a line whose containers differ from the line above, and
- * on one following a heading, island or rule, each a block of one line.
- * `setKind` lands a kind the line's text contradicts — `island` or `rule` over
+ * on one following a heading, a rule or a block island's line, each a block of
+ * one line. `setKind` lands a kind the line's text contradicts — `rule` over
  * prose, `code` over a slot — as `para`, which is what re-importing the line's
- * own markdown yields. Read the content back to see where an op settled.
+ * own markdown yields, and reads an `island` the union does not offer as the
+ * `para` that spelling projects. Read the content back to see where an op
+ * settled.
  */
 export type LineOp =
 | { op: "split"; at: number }
@@ -264,22 +261,16 @@ export type LineOp =
  * one `insert` per slot.
  *
  * Deleting an island needs no op: a `delta` that removes its slot drops the
- * island whole, and a block island's line demotes to `para`. Re-landing it is an
- * `insert` of the full island under its original id; a pasted copy of a live
- * island mints a fresh one.
- *
- * A `set` stores the `loss` it is given; nothing re-derives the class from the
- * new `props`.
+ * island whole. Re-landing it is an `insert` of the full island under its
+ * original id; a pasted copy of a live island mints a fresh one.
  *
  * An island is *inline* (a slot inside a paragraph) or a **block** (that slot
- * alone on a line under `kind: "island"`), and for a slot alone on a line the
- * type settles which: markdown writes a `table` as a block and an image inline,
- * so the line's `kind` is read off the type and a `setKind` spelling it
- * otherwise does not survive. Landing a block island is one bundle of all three
- * channels, in the order they apply: `delta` inserts the `\n` that opens the
- * line, `islandOps` inserts the slot, `lineOps` tags the line
- * `{ op: "setKind", kind: "island" }`. `{ op: "split" }` cannot open that line,
- * since line ops run after island ops.
+ * alone on its own line), and the type settles which: markdown writes a `table`
+ * as a block and an image inline. Both lines read `kind: "para"` — the block is
+ * the slot's markup, not a role the line carries — so landing a block island is
+ * two channels: `delta` inserts the `\n` that opens the line, `islandOps`
+ * inserts the slot. `{ op: "split" }` cannot open that line, since line ops run
+ * after island ops.
  *
  * A `table` has no inline placement: markdown writes it as a block, so an
  * `insert` whose `at` is not an empty line throws, as does a `set` retyping an
@@ -397,6 +388,12 @@ 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.
+     *  `"table"` is valid only on an `array` whose `items` is an `object`.
+     *  Every column is a leaf, a contract refused at load as
+     *  `quill::table_column_not_flat`. Drawing the grid is a request: a
+     *  consumer that cannot falls back to its own choice for the type. */
+    layout?: "table";
 }
 
 /** One entry in a card's `ui.groups` registry: a display-label override for the
@@ -448,21 +445,31 @@ 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;
     /** 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. */
+    /** Per-member field sets on a `type: "enum"` field that is a card's own
+     *  field or a typed dictionary's property, 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>>;
+    /** The roster of a `type: "matrix"` field, required there and valid
+     *  nowhere else: member id to display title, key order the display order.
+     *  Each member is an object of `held` plus the field's `properties`
+     *  (the columns), addressed as `<field>.<member id>.held`. */
+    members?: Record<string, string>;
     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;
@@ -832,6 +839,14 @@ export class Quill {
      * mutation.
      */
     conform(doc: Document): Diagnostic[];
+    /**
+     * The empty document: a main card carrying this quill's `$quill` and
+     * `$kind: main`, no field committed, no composable card, no body. The
+     * type-minimal valid input, and the document a plate is bound to render
+     * (the quill authoring contract). `new Document(ref)` is the same document
+     * reached by spelling the reference.
+     */
+    emptyDocument(): Document;
     /**
      * Build a quill from a file tree. Pure: the declared backend is resolved
      * later, at render time. Accepts a `Map<string, Uint8Array>` or a plain
@@ -923,6 +938,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 +1071,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;
@@ -1052,6 +1081,7 @@ export interface InitOutput {
     readonly quill_backendId: (a: number, b: number) => void;
     readonly quill_blueprint: (a: number, b: number) => void;
     readonly quill_conform: (a: number, b: number, c: number) => void;
+    readonly quill_emptyDocument: (a: number) => number;
     readonly quill_fromTree: (a: number, b: number) => void;
     readonly quill_metadata: (a: number, b: number) => void;
     readonly quill_parse: (a: number, b: number, c: number, d: number) => void;

package/core/wasm.js

@@ -1297,6 +1297,18 @@ export class Quill {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
+    /**
+     * The empty document: a main card carrying this quill's `$quill` and
+     * `$kind: main`, no field committed, no composable card, no body. The
+     * type-minimal valid input, and the document a plate is bound to render
+     * (the quill authoring contract). `new Document(ref)` is the same document
+     * reached by spelling the reference.
+     * @returns {Document}
+     */
+    emptyDocument() {
+        const ret = wasm.quill_emptyDocument(this.__wbg_ptr);
+        return Document.__wrap(ret);
+    }
     /**
      * Build a quill from a file tree. Pure: the declared backend is resolved
      * later, at render time. Accepts a `Map<string, Uint8Array>` or a plain
@@ -1546,6 +1558,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;
@@ -61,6 +62,7 @@ export const quill__resolve: (a: number, b: number, c: number) => void;
 export const quill_backendId: (a: number, b: number) => void;
 export const quill_blueprint: (a: number, b: number) => void;
 export const quill_conform: (a: number, b: number, c: number) => void;
+export const quill_emptyDocument: (a: number) => number;
 export const quill_fromTree: (a: number, b: number) => void;
 export const quill_metadata: (a: number, b: number) => void;
 export const quill_parse: (a: number, b: number, c: number, d: number) => void;

package/package.json

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

package/render/wasm.d.ts

@@ -73,9 +73,9 @@ export interface Content {
 }
 
 /** One `\n`-separated segment of `Content.text`, in order. `kind` is a closed
- * set: a role outside it is refused wherever content is decoded. Every role
- * spells its payload in `attrs`, so `kind === "heading"` narrows `attrs` to
- * `{ level: number }` with no guard. */
+ * set: `island` reads as `para`, and any other role outside it is refused
+ * wherever content is decoded. Every role spells its payload in `attrs`, so
+ * `kind === "heading"` narrows `attrs` to `{ level: number }` with no guard. */
 export type ContentLine = {
     containers: ContentContainer[];
     /** A within-block hard line break rather than a new block. Omitted (false) in the common case. */
@@ -87,7 +87,6 @@ export type ContentLineKind =
 | { kind: "para" }
 | { kind: "heading"; attrs: { level: number } }
 | { kind: "code"; attrs?: { lang?: string } }
-| { kind: "island" }
 | { kind: "rule" };
 
 /** An ancestor block a line nests inside, outermost first. Closed like
@@ -158,14 +157,10 @@ export interface ImageProps {
     alt: string;
 }
 
-/** How faithfully the markdown projection can carry an island. */
-export type ContentLossClass = "lossless" | "degraded" | "unrepresentable";
-
 /** A structured object occupying one island slot in `Content.text`. `type` is a
  * closed set, so `type === "table"` narrows `props` to `TableProps`. */
 export type ContentIsland = {
     id: string;
-    loss: ContentLossClass;
 } & (
 | { type: "table"; props: TableProps }
 | { type: "image"; props: ImageProps }
@@ -237,10 +232,12 @@ export type MarkOp =
  * metadata. `setContinues` sets or clears a line's within-block hard-break flag
  * (`ContentLine.continues`); `continues: true` lands as `false` on line 0, which
  * nothing precedes, on a line whose containers differ from the line above, and
- * on one following a heading, island or rule, each a block of one line.
- * `setKind` lands a kind the line's text contradicts — `island` or `rule` over
+ * on one following a heading, a rule or a block island's line, each a block of
+ * one line. `setKind` lands a kind the line's text contradicts — `rule` over
  * prose, `code` over a slot — as `para`, which is what re-importing the line's
- * own markdown yields. Read the content back to see where an op settled.
+ * own markdown yields, and reads an `island` the union does not offer as the
+ * `para` that spelling projects. Read the content back to see where an op
+ * settled.
  */
 export type LineOp =
 | { op: "split"; at: number }
@@ -264,22 +261,16 @@ export type LineOp =
  * one `insert` per slot.
  *
  * Deleting an island needs no op: a `delta` that removes its slot drops the
- * island whole, and a block island's line demotes to `para`. Re-landing it is an
- * `insert` of the full island under its original id; a pasted copy of a live
- * island mints a fresh one.
- *
- * A `set` stores the `loss` it is given; nothing re-derives the class from the
- * new `props`.
+ * island whole. Re-landing it is an `insert` of the full island under its
+ * original id; a pasted copy of a live island mints a fresh one.
  *
  * An island is *inline* (a slot inside a paragraph) or a **block** (that slot
- * alone on a line under `kind: "island"`), and for a slot alone on a line the
- * type settles which: markdown writes a `table` as a block and an image inline,
- * so the line's `kind` is read off the type and a `setKind` spelling it
- * otherwise does not survive. Landing a block island is one bundle of all three
- * channels, in the order they apply: `delta` inserts the `\n` that opens the
- * line, `islandOps` inserts the slot, `lineOps` tags the line
- * `{ op: "setKind", kind: "island" }`. `{ op: "split" }` cannot open that line,
- * since line ops run after island ops.
+ * alone on its own line), and the type settles which: markdown writes a `table`
+ * as a block and an image inline. Both lines read `kind: "para"` — the block is
+ * the slot's markup, not a role the line carries — so landing a block island is
+ * two channels: `delta` inserts the `\n` that opens the line, `islandOps`
+ * inserts the slot. `{ op: "split" }` cannot open that line, since line ops run
+ * after island ops.
  *
  * A `table` has no inline placement: markdown writes it as a block, so an
  * `insert` whose `at` is not an empty line throws, as does a `set` retyping an
@@ -452,6 +443,12 @@ 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.
+     *  `"table"` is valid only on an `array` whose `items` is an `object`.
+     *  Every column is a leaf, a contract refused at load as
+     *  `quill::table_column_not_flat`. Drawing the grid is a request: a
+     *  consumer that cannot falls back to its own choice for the type. */
+    layout?: "table";
 }
 
 /** One entry in a card's `ui.groups` registry: a display-label override for the
@@ -503,21 +500,31 @@ 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;
     /** 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. */
+    /** Per-member field sets on a `type: "enum"` field that is a card's own
+     *  field or a typed dictionary's property, 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>>;
+    /** The roster of a `type: "matrix"` field, required there and valid
+     *  nowhere else: member id to display title, key order the display order.
+     *  Each member is an object of `held` plus the field's `properties`
+     *  (the columns), addressed as `<field>.<member id>.held`. */
+    members?: Record<string, string>;
     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;
@@ -1108,6 +1115,14 @@ export class Quill {
      * mutation.
      */
     conform(doc: Document): Diagnostic[];
+    /**
+     * The empty document: a main card carrying this quill's `$quill` and
+     * `$kind: main`, no field committed, no composable card, no body. The
+     * type-minimal valid input, and the document a plate is bound to render
+     * (the quill authoring contract). `new Document(ref)` is the same document
+     * reached by spelling the reference.
+     */
+    emptyDocument(): Document;
     /**
      * Build a quill from a file tree. Pure: the declared backend is resolved
      * later, at render time. Accepts a `Map<string, Uint8Array>` or a plain
@@ -1225,6 +1240,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 +1375,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;
@@ -1368,6 +1397,7 @@ export interface InitOutput {
     readonly quill_backendId: (a: number, b: number) => void;
     readonly quill_blueprint: (a: number, b: number) => void;
     readonly quill_conform: (a: number, b: number, c: number) => void;
+    readonly quill_emptyDocument: (a: number) => number;
     readonly quill_fromTree: (a: number, b: number) => void;
     readonly quill_metadata: (a: number, b: number) => void;
     readonly quill_parse: (a: number, b: number, c: number, d: number) => void;

package/render/wasm.js

@@ -1620,6 +1620,18 @@ export class Quill {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
+    /**
+     * The empty document: a main card carrying this quill's `$quill` and
+     * `$kind: main`, no field committed, no composable card, no body. The
+     * type-minimal valid input, and the document a plate is bound to render
+     * (the quill authoring contract). `new Document(ref)` is the same document
+     * reached by spelling the reference.
+     * @returns {Document}
+     */
+    emptyDocument() {
+        const ret = wasm.quill_emptyDocument(this.__wbg_ptr);
+        return Document.__wrap(ret);
+    }
     /**
      * Build a quill from a file tree. Pure: the declared backend is resolved
      * later, at render time. Accepts a `Map<string, Uint8Array>` or a plain
@@ -1965,6 +1977,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;
@@ -75,6 +76,7 @@ export const quill__resolve: (a: number, b: number, c: number) => void;
 export const quill_backendId: (a: number, b: number) => void;
 export const quill_blueprint: (a: number, b: number) => void;
 export const quill_conform: (a: number, b: number, c: number) => void;
+export const quill_emptyDocument: (a: number) => number;
 export const quill_fromTree: (a: number, b: number) => void;
 export const quill_metadata: (a: number, b: number) => void;
 export const quill_parse: (a: number, b: number, c: number, d: 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;
 }
 
 /**
@@ -179,9 +181,9 @@ export declare function isQuillmarkError(e: unknown): e is QuillmarkError;
 
 import type { ContentContainer } from '../core/wasm.js';
 
-// `ContentIsland.type`, `ContentMark.type`, `ContentLine.kind`,
-// `ContentContainer.container` and an island's `loss` are closed sets, so a
-// bare discriminant check narrows the payload on its own:
+// `ContentIsland.type`, `ContentMark.type`, `ContentLine.kind` and
+// `ContentContainer.container` are closed sets, so a bare discriminant check
+// narrows the payload on its own:
 // `line.kind === 'heading'` reaches `line.attrs.level`, with no guard to call.
 
 /**

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`.
@@ -173,7 +174,7 @@ const HANDLE_KINDS = {
 	},
 	Document: {
 		code: 'runtime::not_a_document',
-		hint: 'Pass a Document built by Document.fromMarkdown / fromStored or quill.seedDocument. A Document from another copy of @quillmark/wasm is refused too — each copy is its own WASM linear memory and its own class — so run `npm ls @quillmark/wasm` and dedupe to one.'
+		hint: 'Pass a Document built by Document.fromMarkdown / fromStored or quill.seedDocument / emptyDocument. A Document from another copy of @quillmark/wasm is refused too — each copy is its own WASM linear memory and its own class — so run `npm ls @quillmark/wasm` and dedupe to one.'
 	}
 };
 
@@ -218,9 +219,15 @@ function requireLocalQuill(quill, method) {
 // WELD_KEYS is the rule `Container::same_weld` owns upstream: which `attrs`
 // entries two adjacent runs must share for the markdown projection to read them
 // as one. `start` is not among them, since CommonMark reads only a list's first
-// number — a subset, which is why every container needs its own entry. A table
-// rather than a switch, so `tests/known_names_drift.rs` can pin it against the
-// Rust predicate.
+// number — a subset, which is why every container needs its own entry.
+//
+// Re-spelled here rather than called, because `assignInstances` answers before
+// wasm initializes (`prose/canon/BINDINGS.md` § "WebAssembly"). What holds the
+// two spellings equal is running the rule, not comparing their sources:
+// `runtime.test.js` § "container run boundaries" stamps a pair and re-imports
+// it, where `Content::normalize` re-mints against the Rust predicate. A tag the
+// table omits welds with nothing, so `tests/known_names_drift.rs` pins that
+// every container has an entry.
 
 const WELD_KEYS = { list_item: ['ordered'], quote: [] };