@quillmark/wasm 0.109.0 → 0.110.0

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## v0.110.0 - 2026-08-26
+
+- **breaking** wasm: **the seam spells a container's `instance`, so the read
+  type can require it and every write lane reports an omission.** 0.109 gave
+  `Container` the discriminator that tells one container from an adjacent
+  sibling of identical shape, and left it an obligation no checker asked for;
+  the op lane got a requirement, the whole-`Content` lane — `overwrite`,
+  `CardInput.body`, the one a codec flattening a tree writes through — did not.
+  It could not: one encoder served storage and the bindings, writing the key
+  only where it was non-zero, and a field a read may omit is a field a write
+  cannot require. `serial::to_seam_value` is that encoder with every `instance`
+  spelled, and the bindings take it on every lane typed `Content`
+  (`reader.getContent{,At}`, `getStored` on a body, `importMarkdown`, `rebase`,
+  and the card wire behind `document.main` / `cards` / `card(i)` / `removeCard`
+  / `makeCard` / `seedMain` / `seedCard`). `ContentContainer.instance` becomes
+  required, `ContentContainerInput` is deleted, and `LineOp.setContainers` takes
+  `ContentContainer` — a net-smaller surface than 0.109's. The break is every
+  hand-built container literal, which is the one a type checker does report.
+  A checker still cannot report a `0` stamped on every run, which is the write
+  that welds them: `assignInstances` is the rule, not the type. Storage keeps
+  the omission and stored blobs re-encode byte for byte; so do the render lanes,
+  and so does what the seam types `unknown` (`getStored` on a field,
+  `PayloadItem.value`), which answers with the stored bytes verbatim. Content
+  parsed from a stored document is the one shape that needs a cast.
+  [Guide](docs/migrations/0.109-to-0.110.md)
+- fix(core): **`Quill::validate` refuses only what the render floor refuses.**
+  Validation ran its own read-side type dispatch over the authored value while
+  the render door validated the *coerced* one, so five of seven types had values
+  that rendered and were fatally `validation::type_mismatch` at once — a bare
+  scalar for an `array`, `"3"` for an `integer`, `1` for a `boolean`, a
+  length-1 array for a `string` or `date`. `airmark`'s `usaf_memo@0.2` declares
+  `letterhead_caption` as an `array`, and the bare scalar a starter template
+  spells it with — a valid spelling of a one-element list — audited as fatally
+  invalid across every document seeded from it, each rendering correctly.
+
+  `validate_value` now conforms each document value through `conform_value` at
+  `Leniency::Render` before judging it, so a type has one predicate and **a
+  fatal `validation::*` diagnostic means the document does not render**.
+  Conforming runs per node, so one refused element no longer mistypes its
+  siblings: `counts: [true, "abc"]` under `integer` items is one mismatch, at
+  `counts[1]`. Two consequences for a consumer routing on codes: a value the
+  floor adopts raises nothing where it previously raised
+  `validation::type_mismatch`, and a bare scalar the floor stringifies into an
+  `enum` field is now domain-checked on that string, so `grade: 5` against
+  `values: [alpha, beta]` is `validation::enum_violation` where it was
+  previously silent — the diagnostic the render door already raised. Schema
+  literals (`example:`, `default:`) stay strict.
+
+## v0.109.1 - 2026-08-24
+
+- fix(typst): **a `field-region` claim around inline content no longer widens
+  the line.** Each of the helper's two bracketing markers was written
+  `#metadata(..) <__qm_region__>`, and the space before the label survived into
+  the inline flow. It cost 2.715pt per marker at a 12pt body size, so a claim
+  on a date or any mid-paragraph composition shifted the text around it by
+  5.43pt, against the layout-neutral contract the helper documents.
+  `form-field`'s marker carries the same shape and drops the space too, rather
+  than keep depending on the `box` that follows it.
+
 ## v0.109.0 - 2026-08-24
 
 - **breaking** content: **`Normalized` is the precondition the projections
@@ -159,8 +218,18 @@
   that needs no discriminator — nearly all of them — keeps its exact bytes and
   its content hash. **Breaking for Rust consumers** that match `Container`
   exhaustively: `Quote` is now a struct variant, and `ListItem`/`Unknown` carry
-  the extra field. On the TypeScript surface `instance` is optional; a consumer
-  that never writes adjacent same-shape siblings needs no change.
+  the extra field.
+
+  On the TypeScript surface `instance` is optional — the wire omits a zero, so a
+  read shape cannot require it — and nothing there stops compiling. A consumer
+  that only reads needs no change. **A consumer that writes container paths owes
+  the field**, which is every codec flattening a tree: two `bullet_list` nodes in
+  a row are adjacent same-shape siblings, and omitting the discriminator lands
+  them welded. Such a host keeps producing what it produced on 0.108, so the
+  four defects above stay open for it until its codec stamps the discriminator.
+  Nothing reports the omission. Two adjacent lines with equal paths are one
+  container, which is also how a two-paragraph quote is spelled: the model
+  cannot tell a boundary a writer meant from one it did not.
 
   The block census counts what the projections see, so two adjacent runs of one
   shape now count two where they counted one: a quill declining `list` or
@@ -170,10 +239,13 @@
   A blob written here carries `instance` only where a document holds adjacent
   same-shape siblings, and a reader that predates the field ignores the key —
   so such a blob loads on 0.108 with the two runs welded, and re-saving there
-  drops the boundary for good. The `@0.93.0` tag is unchanged because every
-  blob written before this release re-encodes byte for byte; the forward
-  direction is the one that costs, and only for the documents that spend the
-  key.
+  drops the boundary for good. A 0.109 host whose codec drops the key on
+  write-back loses it the same way, with no version skew involved. The boundary
+  is written by whatever produced the row — `from_markdown`, the CLI, any Rust
+  caller — and survives only as far as the next writer that carries it.
+  The `@0.93.0` tag is unchanged because every blob written before this release
+  re-encodes byte for byte; the forward direction is the one that costs, and
+  only for the documents that spend the key.
 
 - fix(blueprint): **a variant's `object` or `array<object>` cell expands per
   property.** The cell went through the scalar path, so it rendered as
@@ -248,25 +320,6 @@
   `island_to_value`, now emit their own keys in a different order. An unknown's `attrs` bag is
   untouched, as in 0.99, and nothing hashes the op wire.
 
-<!-- seed: commits since v0.108.3, confirm the entries above cover them, then delete this comment
-- docs: the 0.108 → 0.109 release record, and two misattached doc comments
-- docs: dense-prose pass over the branch
-- docs: dense-prose pass over the branch
-- fix: close the rest of the normalized-is-not-validated gap
-- fix(typst): open every block at the enclosing list indent
-- fix(content): walk export's block tree on a frame stack
-- docs: dense-prose pass over the branch
-- fix: hold the token's guarantee on error paths, and walk census iteratively
-- feat(content): make "normalized" a type the projections require
-- refactor: consume the shared container traversal
-- feat(content): one traversal for container runs and items
-- fix(content): an item boundary is a parent boundary
-- fix(content): clear a `continues` that crosses a container boundary
-- fix(content): give a container the instance its identity was missing
-- Bulk PR integration: #1347–#1356 (#1358)
--->
-
-
 ## v0.108.3 - 2026-08-21
 
 - fix(typst): **a paragraph holding one bare `/` renders instead of failing the

package/backends/pdfform/wasm.d.ts

@@ -95,16 +95,32 @@ export type ContentLineKind =
  * `ContentLine.kind`: an unrecognized container round-trips with opaque `attrs`
  * and renders transparently (its lines sit at the enclosing level).
  *
- * Two adjacent lines sit in the same container iff their whole path matches.
+ * Two adjacent lines sit in the same container iff their whole path matches, so
  * `instance` is what tells one container from an adjacent sibling of identical
- * shape — two consecutive quotes, or two consecutive lists — which contiguity
- * alone reads as one. Omit it (or write `0`) unless a path immediately above or
- * below is otherwise identical; a write is canonicalized to `0`/`1` on the way
- * in, so any distinct pair of values works. */
+ * shape — two consecutive quotes, two consecutive lists — which contiguity
+ * alone reads as one.
+ *
+ * **A writer owes a distinct value per adjacent sibling run**, not merely a
+ * value. Runs of one shape sharing one arrive as one: a second list's items come
+ * back as continuation paragraphs of the first, markers gone. The field is
+ * required, so a checker reports the omission; it cannot report a `0` stamped on
+ * both, which is the same write. A codec flattening a tree takes them from
+ * `assignInstances` in `@quillmark/wasm/runtime` rather than by hand. Any
+ * distinct pair works; a write is canonicalized to `0`/`1`.
+ *
+ * Reading is not the mirror of writing. Every read spells the field, the `0` on
+ * a container with nothing to be told apart from included. A read also carries a
+ * discriminator on pairs no writer had to spell: `1.` beside a list starting at
+ * `3` differs by `start`, so those runs arrive apart with nothing written, and
+ * the canonical form spends one anyway because Markdown reads only a list's
+ * first number.
+ *
+ * Content parsed from a stored document is the one shape that arrives without
+ * it — storage omits a zero — and needs a cast. */
 export type ContentContainer =
-| { container: "list_item"; ordered: boolean; start: number; ordinal: number; instance?: number }
-| { container: "quote"; instance?: number }
-| { container: string; attrs: unknown; instance?: number };
+| { container: "list_item"; ordered: boolean; start: number; ordinal: number; instance: number }
+| { container: "quote"; instance: number }
+| { container: string; attrs: unknown; instance: number };
 
 /** A mark over char range `[start, end)` into `Content.text`. The open `type`
  * arm blocks discriminant narrowing, so read a payload-carrying arm behind its
@@ -793,6 +809,10 @@ export class Document {
      * is at rest; one from the transport door may rest as authored until it is
      * conformed, and this read reports what is there. For the `Content` either
      * way use `reader.getContent`.
+     *
+     * The body arm is typed `Content` and answers in the seam form, spelling
+     * every `ContentContainer.instance`. A field arm echoes the stored bytes,
+     * which omit a zero: verbatim is the contract, and is why it is `unknown`.
      */
     getStored(addr: Addr | string): unknown;
     /**

package/backends/pdfform/wasm.js

@@ -608,6 +608,10 @@ export class Document {
      * is at rest; one from the transport door may rest as authored until it is
      * conformed, and this read reports what is there. For the `Content` either
      * way use `reader.getContent`.
+     *
+     * The body arm is typed `Content` and answers in the seam form, spelling
+     * every `ContentContainer.instance`. A field arm echoes the stored bytes,
+     * which omit a zero: verbatim is the contract, and is why it is `unknown`.
      * @param {Addr | string} addr
      * @returns {unknown}
      */

package/backends/typst/wasm.d.ts

@@ -95,16 +95,32 @@ export type ContentLineKind =
  * `ContentLine.kind`: an unrecognized container round-trips with opaque `attrs`
  * and renders transparently (its lines sit at the enclosing level).
  *
- * Two adjacent lines sit in the same container iff their whole path matches.
+ * Two adjacent lines sit in the same container iff their whole path matches, so
  * `instance` is what tells one container from an adjacent sibling of identical
- * shape — two consecutive quotes, or two consecutive lists — which contiguity
- * alone reads as one. Omit it (or write `0`) unless a path immediately above or
- * below is otherwise identical; a write is canonicalized to `0`/`1` on the way
- * in, so any distinct pair of values works. */
+ * shape — two consecutive quotes, two consecutive lists — which contiguity
+ * alone reads as one.
+ *
+ * **A writer owes a distinct value per adjacent sibling run**, not merely a
+ * value. Runs of one shape sharing one arrive as one: a second list's items come
+ * back as continuation paragraphs of the first, markers gone. The field is
+ * required, so a checker reports the omission; it cannot report a `0` stamped on
+ * both, which is the same write. A codec flattening a tree takes them from
+ * `assignInstances` in `@quillmark/wasm/runtime` rather than by hand. Any
+ * distinct pair works; a write is canonicalized to `0`/`1`.
+ *
+ * Reading is not the mirror of writing. Every read spells the field, the `0` on
+ * a container with nothing to be told apart from included. A read also carries a
+ * discriminator on pairs no writer had to spell: `1.` beside a list starting at
+ * `3` differs by `start`, so those runs arrive apart with nothing written, and
+ * the canonical form spends one anyway because Markdown reads only a list's
+ * first number.
+ *
+ * Content parsed from a stored document is the one shape that arrives without
+ * it — storage omits a zero — and needs a cast. */
 export type ContentContainer =
-| { container: "list_item"; ordered: boolean; start: number; ordinal: number; instance?: number }
-| { container: "quote"; instance?: number }
-| { container: string; attrs: unknown; instance?: number };
+| { container: "list_item"; ordered: boolean; start: number; ordinal: number; instance: number }
+| { container: "quote"; instance: number }
+| { container: string; attrs: unknown; instance: number };
 
 /** A mark over char range `[start, end)` into `Content.text`. The open `type`
  * arm blocks discriminant narrowing, so read a payload-carrying arm behind its
@@ -793,6 +809,10 @@ export class Document {
      * is at rest; one from the transport door may rest as authored until it is
      * conformed, and this read reports what is there. For the `Content` either
      * way use `reader.getContent`.
+     *
+     * The body arm is typed `Content` and answers in the seam form, spelling
+     * every `ContentContainer.instance`. A field arm echoes the stored bytes,
+     * which omit a zero: verbatim is the contract, and is why it is `unknown`.
      */
     getStored(addr: Addr | string): unknown;
     /**

package/backends/typst/wasm.js

@@ -608,6 +608,10 @@ export class Document {
      * is at rest; one from the transport door may rest as authored until it is
      * conformed, and this read reports what is there. For the `Content` either
      * way use `reader.getContent`.
+     *
+     * The body arm is typed `Content` and answers in the seam form, spelling
+     * every `ContentContainer.instance`. A field arm echoes the stored bytes,
+     * which omit a zero: verbatim is the contract, and is why it is `unknown`.
      * @param {Addr | string} addr
      * @returns {unknown}
      */

package/core/wasm.d.ts

@@ -95,16 +95,32 @@ export type ContentLineKind =
  * `ContentLine.kind`: an unrecognized container round-trips with opaque `attrs`
  * and renders transparently (its lines sit at the enclosing level).
  *
- * Two adjacent lines sit in the same container iff their whole path matches.
+ * Two adjacent lines sit in the same container iff their whole path matches, so
  * `instance` is what tells one container from an adjacent sibling of identical
- * shape — two consecutive quotes, or two consecutive lists — which contiguity
- * alone reads as one. Omit it (or write `0`) unless a path immediately above or
- * below is otherwise identical; a write is canonicalized to `0`/`1` on the way
- * in, so any distinct pair of values works. */
+ * shape — two consecutive quotes, two consecutive lists — which contiguity
+ * alone reads as one.
+ *
+ * **A writer owes a distinct value per adjacent sibling run**, not merely a
+ * value. Runs of one shape sharing one arrive as one: a second list's items come
+ * back as continuation paragraphs of the first, markers gone. The field is
+ * required, so a checker reports the omission; it cannot report a `0` stamped on
+ * both, which is the same write. A codec flattening a tree takes them from
+ * `assignInstances` in `@quillmark/wasm/runtime` rather than by hand. Any
+ * distinct pair works; a write is canonicalized to `0`/`1`.
+ *
+ * Reading is not the mirror of writing. Every read spells the field, the `0` on
+ * a container with nothing to be told apart from included. A read also carries a
+ * discriminator on pairs no writer had to spell: `1.` beside a list starting at
+ * `3` differs by `start`, so those runs arrive apart with nothing written, and
+ * the canonical form spends one anyway because Markdown reads only a list's
+ * first number.
+ *
+ * Content parsed from a stored document is the one shape that arrives without
+ * it — storage omits a zero — and needs a cast. */
 export type ContentContainer =
-| { container: "list_item"; ordered: boolean; start: number; ordinal: number; instance?: number }
-| { container: "quote"; instance?: number }
-| { container: string; attrs: unknown; instance?: number };
+| { container: "list_item"; ordered: boolean; start: number; ordinal: number; instance: number }
+| { container: "quote"; instance: number }
+| { container: string; attrs: unknown; instance: number };
 
 /** A mark over char range `[start, end)` into `Content.text`. The open `type`
  * arm blocks discriminant narrowing, so read a payload-carrying arm behind its
@@ -609,6 +625,10 @@ export class Document {
      * is at rest; one from the transport door may rest as authored until it is
      * conformed, and this read reports what is there. For the `Content` either
      * way use `reader.getContent`.
+     *
+     * The body arm is typed `Content` and answers in the seam form, spelling
+     * every `ContentContainer.instance`. A field arm echoes the stored bytes,
+     * which omit a zero: verbatim is the contract, and is why it is `unknown`.
      */
     getStored(addr: Addr | string): unknown;
     /**

package/core/wasm.js

@@ -608,6 +608,10 @@ export class Document {
      * is at rest; one from the transport door may rest as authored until it is
      * conformed, and this read reports what is there. For the `Content` either
      * way use `reader.getContent`.
+     *
+     * The body arm is typed `Content` and answers in the seam form, spelling
+     * every `ContentContainer.instance`. A field arm echoes the stored bytes,
+     * which omit a zero: verbatim is the contract, and is why it is `unknown`.
      * @param {Addr | string} addr
      * @returns {unknown}
      */

package/package.json

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

package/runtime/runtime.d.ts

@@ -245,7 +245,7 @@ export declare function isListItemContainer(
 	ordered: boolean;
 	start: number;
 	ordinal: number;
-	instance?: number;
+	instance: number;
 };
 
 // The guards above answer "is this arm X". These four answer "is this a value
@@ -278,6 +278,41 @@ export declare function isUnknownIsland(
 	island: ContentIsland
 ): island is ContentIsland & { type: string; props: unknown };
 
+// `ContentContainer.instance` is required, so a checker reports an omission; it
+// cannot report a `0` stamped on every run, which is the same write. Adjacent
+// runs of one shape sharing a value arrive welded, and nothing reports that
+// either: the flat `containers` form cannot tell it from one container spanning
+// two paragraphs. This carries the rule a codec would otherwise re-derive.
+
+/**
+ * Stamp `instance` across one parent's blocks at one depth, in document order,
+ * returning containers ready to write.
+ *
+ * One entry per container RUN — a list, not a list item — and `null` for a
+ * block carrying no container at this depth. A bare paragraph between two lists
+ * is such a block, and separates them on its own. Every line of a run then
+ * carries that run's returned container, `ordinal` varying per item and
+ * `instance` held.
+ *
+ * The `instance` it stamps is canonical, so a document reads back the value it
+ * was written. `ordinal` stays the caller's, and a write is renumbered to a
+ * gapless index within its run.
+ *
+ * Which fields decide a weld is coarser than equality for a list: CommonMark
+ * reads only a list's first number, so `1. a` beside `3. b` welds despite the
+ * differing `start`.
+ *
+ * ```js
+ * const [outer, , inner] = assignInstances([listA, null, listB]);
+ * // outer.instance === 0, inner.instance === 0 — the paragraph parts them
+ * const [a, b] = assignInstances([listA, listB]);
+ * // a.instance === 0, b.instance === 1 — adjacent, one shape
+ * ```
+ */
+export declare function assignInstances(
+	runs: (ContentContainer | null)[]
+): (ContentContainer | null)[];
+
 // The backend-neutral render contract, defined here rather than re-exported from
 // one private backend because no single backend owns the canonical API's types.
 // Every backend build must satisfy these shapes; `runtime.types.test-d.ts` keeps

package/runtime/runtime.js

@@ -510,6 +510,64 @@ export function isUnknownIsland(island) {
 	return typeof island?.type === 'string' && !KNOWN_ISLAND_TYPES.has(island.type);
 }
 
+// ── Container run boundaries ────────────────────────────────────────────────
+// `ContentContainer.instance` is what keeps two adjacent runs of one shape
+// apart, and only a writer knows where a boundary is: the flat `containers`
+// form cannot tell a list ending beside another from one list of two items, so
+// an omitted discriminator welds them and nothing reports it.
+//
+// WELD_KEYS is the rule `Container::same_weld` owns upstream: which fields two
+// adjacent runs must share for the markdown projection to read them as one, and
+// therefore for the canonical form to have to spend a discriminator. `start` is
+// not among them, since CommonMark reads only a list's first number. A table
+// rather than a switch, so `tests/known_names_drift.rs` can pin it against the
+// Rust predicate.
+
+const WELD_KEYS = { list_item: ['ordered'], quote: [] };
+
+function sameJson(a, b) {
+	if (a === b) return true;
+	if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false;
+	if (Array.isArray(a) !== Array.isArray(b)) return false;
+	const ka = Object.keys(a);
+	return (
+		ka.length === Object.keys(b).length &&
+		ka.every((k) => Object.hasOwn(b, k) && sameJson(a[k], b[k]))
+	);
+}
+
+/**
+ * @param {import('../core/wasm.js').ContentContainer} a
+ * @param {import('../core/wasm.js').ContentContainer} b
+ * @returns {boolean}
+ */
+function weldsWith(a, b) {
+	// A malformed value welds with nothing. The membership guards' posture:
+	// answer rather than throw.
+	if (typeof a?.container !== 'string' || a.container !== b?.container) return false;
+	// `hasOwn`, so a tag colliding with an `Object.prototype` member reaches the
+	// unknown branch rather than a function.
+	if (!Object.hasOwn(WELD_KEYS, a.container)) return sameJson(a.attrs, b.attrs);
+	return WELD_KEYS[a.container].every((k) => a[k] === b[k]);
+}
+
+/**
+ * @param {(import('../core/wasm.js').ContentContainer | null)[]} runs
+ * @returns {(import('../core/wasm.js').ContentContainer | null)[]}
+ */
+export function assignInstances(runs) {
+	let prev = null;
+	return runs.map((run) => {
+		if (run == null) {
+			prev = null;
+			return null;
+		}
+		const instance = prev && weldsWith(prev, run) ? 1 - prev.instance : 0;
+		prev = { ...run, instance };
+		return prev;
+	});
+}
+
 /**
  * Build a `load` thunk: dynamic-import a backend build, then instantiate it.
  *