@quillmark/wasm 0.109.0 → 0.109.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 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.
+
+<!-- seed: commits since v0.109.0, confirm the entries above cover them, then delete this comment
+- docs: dense-prose pass over the branch
+- fix(typst): a marker's label is not a space in the inline flow
+- refactor(wasm): keep the weld rule internal, and pin what states it
+- docs: dense-prose pass over the branch
+- docs: classify 0.109's container break by consumer role
+- feat(wasm)!: make a written container path spell its instance
+- feat(content): name the rule a container's discriminator is minted against
+-->
+
+
 ## v0.109.0 - 2026-08-24
 
 - **breaking** content: **`Normalized` is the precondition the projections
@@ -159,8 +181,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 +202,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 +283,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,17 +95,42 @@ 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 it.** Give adjacent sibling runs of one shape distinct
+ * values, or they arrive as one: a second list's items come back as
+ * continuation paragraphs of the first, markers gone. Nothing reports that,
+ * since the flat form cannot tell a boundary you meant from one you did not. A
+ * codec flattening a tree stamps the field with `assignInstances` from
+ * `@quillmark/wasm/runtime` rather than by hand. Any distinct pair of values
+ * works; a write is canonicalized to `0`/`1`.
+ *
+ * Reading is not the mirror of writing. The field is absent where it is `0`,
+ * and it appears 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 a discriminator anyway, because Markdown reads
+ * only a list's first number. */
 export type ContentContainer =
 | { container: "list_item"; ordered: boolean; start: number; ordinal: number; instance?: number }
 | { container: "quote"; instance?: number }
 | { container: string; attrs: unknown; instance?: number };
 
+/** A container path on a lane that only ever carries host-built values:
+ * `ContentContainer` with `instance` spelled out rather than defaulted. The
+ * field that decides whether two adjacent runs weld cannot be omitted by
+ * accident here. `assignInstances` returns this shape, and a path copied off a
+ * line carries its own instance through — `{ ...c, instance: c.instance ?? 0 }`.
+ *
+ * `Content` itself keeps the optional field: it is a read shape as much as a
+ * write one, and the wire omits a zero. */
+export type ContentContainerInput =
+| { 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
  * guard: `isLinkMark` (`url`) / `isAnchorMark` (`id`), from
@@ -231,7 +256,7 @@ export type LineOp =
 | { op: "split"; at: number }
 | { op: "join"; line: number }
 | ({ op: "setKind"; line: number } & ContentLineKind)
-| { op: "setContainers"; line: number; containers: ContentContainer[] }
+| { op: "setContainers"; line: number; containers: ContentContainerInput[] }
 | { op: "setContinues"; line: number; continues: boolean };
 
 /**

package/backends/typst/wasm.d.ts

@@ -95,17 +95,42 @@ 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 it.** Give adjacent sibling runs of one shape distinct
+ * values, or they arrive as one: a second list's items come back as
+ * continuation paragraphs of the first, markers gone. Nothing reports that,
+ * since the flat form cannot tell a boundary you meant from one you did not. A
+ * codec flattening a tree stamps the field with `assignInstances` from
+ * `@quillmark/wasm/runtime` rather than by hand. Any distinct pair of values
+ * works; a write is canonicalized to `0`/`1`.
+ *
+ * Reading is not the mirror of writing. The field is absent where it is `0`,
+ * and it appears 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 a discriminator anyway, because Markdown reads
+ * only a list's first number. */
 export type ContentContainer =
 | { container: "list_item"; ordered: boolean; start: number; ordinal: number; instance?: number }
 | { container: "quote"; instance?: number }
 | { container: string; attrs: unknown; instance?: number };
 
+/** A container path on a lane that only ever carries host-built values:
+ * `ContentContainer` with `instance` spelled out rather than defaulted. The
+ * field that decides whether two adjacent runs weld cannot be omitted by
+ * accident here. `assignInstances` returns this shape, and a path copied off a
+ * line carries its own instance through — `{ ...c, instance: c.instance ?? 0 }`.
+ *
+ * `Content` itself keeps the optional field: it is a read shape as much as a
+ * write one, and the wire omits a zero. */
+export type ContentContainerInput =
+| { 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
  * guard: `isLinkMark` (`url`) / `isAnchorMark` (`id`), from
@@ -231,7 +256,7 @@ export type LineOp =
 | { op: "split"; at: number }
 | { op: "join"; line: number }
 | ({ op: "setKind"; line: number } & ContentLineKind)
-| { op: "setContainers"; line: number; containers: ContentContainer[] }
+| { op: "setContainers"; line: number; containers: ContentContainerInput[] }
 | { op: "setContinues"; line: number; continues: boolean };
 
 /**

package/core/wasm.d.ts

@@ -95,17 +95,42 @@ 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 it.** Give adjacent sibling runs of one shape distinct
+ * values, or they arrive as one: a second list's items come back as
+ * continuation paragraphs of the first, markers gone. Nothing reports that,
+ * since the flat form cannot tell a boundary you meant from one you did not. A
+ * codec flattening a tree stamps the field with `assignInstances` from
+ * `@quillmark/wasm/runtime` rather than by hand. Any distinct pair of values
+ * works; a write is canonicalized to `0`/`1`.
+ *
+ * Reading is not the mirror of writing. The field is absent where it is `0`,
+ * and it appears 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 a discriminator anyway, because Markdown reads
+ * only a list's first number. */
 export type ContentContainer =
 | { container: "list_item"; ordered: boolean; start: number; ordinal: number; instance?: number }
 | { container: "quote"; instance?: number }
 | { container: string; attrs: unknown; instance?: number };
 
+/** A container path on a lane that only ever carries host-built values:
+ * `ContentContainer` with `instance` spelled out rather than defaulted. The
+ * field that decides whether two adjacent runs weld cannot be omitted by
+ * accident here. `assignInstances` returns this shape, and a path copied off a
+ * line carries its own instance through — `{ ...c, instance: c.instance ?? 0 }`.
+ *
+ * `Content` itself keeps the optional field: it is a read shape as much as a
+ * write one, and the wire omits a zero. */
+export type ContentContainerInput =
+| { 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
  * guard: `isLinkMark` (`url`) / `isAnchorMark` (`id`), from
@@ -231,7 +256,7 @@ export type LineOp =
 | { op: "split"; at: number }
 | { op: "join"; line: number }
 | ({ op: "setKind"; line: number } & ContentLineKind)
-| { op: "setContainers"; line: number; containers: ContentContainer[] }
+| { op: "setContainers"; line: number; containers: ContentContainerInput[] }
 | { op: "setContinues"; line: number; continues: boolean };
 
 /**

package/package.json

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

package/runtime/runtime.d.ts

@@ -130,6 +130,7 @@ export type {
 	ContentLine,
 	ContentLineKind,
 	ContentContainer,
+	ContentContainerInput,
 	ContentMark,
 	ContentIsland,
 	TableProps,
@@ -204,7 +205,8 @@ import type {
 	ImageProps,
 	ContentMark,
 	ContentLine,
-	ContentContainer
+	ContentContainer,
+	ContentContainerInput
 } from '../core/wasm.js';
 
 /** Narrow a {@link ContentIsland} to the pinned `table` arm (`props: TableProps`). */
@@ -278,6 +280,41 @@ export declare function isUnknownIsland(
 	island: ContentIsland
 ): island is ContentIsland & { type: string; props: unknown };
 
+// `ContentContainer.instance` is a field a writer owes and, outside
+// `ContentContainerInput`, no checker asks for. Adjacent runs of one shape that
+// share it arrive welded. Nothing reports that: 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)[]
+): (ContentContainerInput | 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').ContentContainerInput | 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.
  *