@quillmark/wasm 0.114.0 → 0.115.0

package/CHANGELOG.md

@@ -1,5 +1,177 @@
 # 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

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
@@ -398,9 +389,10 @@ export interface QuillFieldUi {
      *  conventional label of its own. */
     blank_title?: string;
     /** The control the field asks for, where the shape admits more than one.
-     *  A request, not a contract: a consumer that cannot draw it falls back to
-     *  its own choice for the type. `"table"` is valid only on an `array`
-     *  whose `items` is an `object`. */
+     *  `"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";
 }
 
@@ -460,16 +452,17 @@ 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. */
+    /** 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: the closed vocabulary a document ticks, in display order.
+     *  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?: QuillMatrixGroup[];
+    members?: Record<string, string>;
     ui?: QuillFieldUi;
     properties?: Record<string, QuillFieldSchema>;
     items?: QuillFieldSchema;
@@ -482,13 +475,6 @@ export interface QuillFieldSchema {
     inline?: boolean;
 }
 
-/** One block of a `type: "matrix"` roster: an optional display heading and the
- * members under it, member id to display title. Key order is display order. */
-export interface QuillMatrixGroup {
-    group?: string;
-    values: Record<string, string>;
-}
-
 /** Schema entry for the main card or a named card kind. */
 export interface QuillCardSchema {
     description?: string;
@@ -853,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
@@ -1087,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

package/core/wasm_bg.wasm.d.ts

@@ -62,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.114.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
@@ -453,9 +444,10 @@ export interface QuillFieldUi {
      *  conventional label of its own. */
     blank_title?: string;
     /** The control the field asks for, where the shape admits more than one.
-     *  A request, not a contract: a consumer that cannot draw it falls back to
-     *  its own choice for the type. `"table"` is valid only on an `array`
-     *  whose `items` is an `object`. */
+     *  `"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";
 }
 
@@ -515,16 +507,17 @@ 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. */
+    /** 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: the closed vocabulary a document ticks, in display order.
+     *  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?: QuillMatrixGroup[];
+    members?: Record<string, string>;
     ui?: QuillFieldUi;
     properties?: Record<string, QuillFieldSchema>;
     items?: QuillFieldSchema;
@@ -537,13 +530,6 @@ export interface QuillFieldSchema {
     inline?: boolean;
 }
 
-/** One block of a `type: "matrix"` roster: an optional display heading and the
- * members under it, member id to display title. Key order is display order. */
-export interface QuillMatrixGroup {
-    group?: string;
-    values: Record<string, string>;
-}
-
 /** Schema entry for the main card or a named card kind. */
 export interface QuillCardSchema {
     description?: string;
@@ -1129,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
@@ -1403,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

package/render/wasm_bg.wasm.d.ts

@@ -76,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

@@ -108,7 +108,6 @@ export type {
 	QuillFieldUi,
 	QuillCardUi,
 	QuillGroupUi,
-	QuillMatrixGroup,
 	QuillMetadata
 } from '../core/wasm.js';
 
@@ -182,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

@@ -174,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.'
 	}
 };
 
@@ -219,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: [] };