@quillmark/wasm 0.109.1 → 0.111.0

package/CHANGELOG.md

@@ -1,5 +1,120 @@
 # Changelog
 
+## v0.111.0 - 2026-08-30
+
+- feat(wasm): **`mapMarks(content, bundle)` answers where a `ChangeBundle`'s
+  text-moving channels leave a field's marks**, the coordinates its `markOps`
+  are written in. Each of `delta`, `islandOps` and `lineOps` rebases the marks
+  already in the field — a range's `start` takes assoc `after` and its `end`
+  `before`, a zero-width mark takes `before` — and that rule reached the
+  boundary only as a comment on a private method, so an editor deciding which
+  `markOps` to emit had to reimplement it, and one that read the range rule as
+  the whole rule drifted an anchor a character on text typed at the anchor's own
+  position. `Content::map_marks` and `Content::apply_field_change` walk one
+  channel list, so the prediction and the store cannot answer a position
+  differently, and the answer is normalized as the store's is, so a bundle
+  carrying no `markOps` names the marks the field will hold. The rule is stated
+  on `ChangeBundle` and in `BINDINGS.md`.
+
+- fix(core): **a `plaintext` field declared `inline: true` keeps the flag on the
+  declaration wire.** `FieldSchema::serialize` projected the flag back out of
+  the type enum with a `RichText { inline: true }` match only, so
+  `type: plaintext, inline: true` serialized as `{"type":"plaintext"}` — WASM
+  `quill.schema()`, the Python binding, and the CLI `schema` command all lost
+  the single-line constraint, and a serde round-trip degraded the field to
+  `inline: false`.
+- fix(core): **a comment on a CRLF line no longer carries its `\r` into the
+  emitted document.** The prescan splits on `\n`, so a trailing- or own-line
+  comment slice ran to end-of-line including the `\r`; it rode through the DTO
+  and wire and was written back verbatim, against `to_markdown`'s "line endings:
+  `\n` only". Field values were never affected. A `\r` *inside* a comment still
+  reaches emit.
+- fix(facade): **loading a path that names no directory says so.** The walk
+  answered a missing root with an empty tree, so `quill_from_path("/typo")`
+  failed later with `Quill.yaml not found in file tree`, pointing at the
+  bundle's contents instead of the path. Python's `Quill.from_path` surfaced
+  that directly; the CLI's pre-checks are gone but for `validate`'s
+  missing-`Quill.yaml` one, gated on the directory existing so it names the
+  bundle a real directory lacks without shadowing the loader's answer for a
+  typo. `validate`'s load-failure summary names no file, that branch covering a
+  missing directory too.
+- fix(content): **`LineOp::SetKind` refuses a heading level outside `1..=6`.**
+  The arm checked kind/text agreement but not the level, so a Rust caller could
+  apply `Heading { level: 9 }` and leave a content whose `validate()` fails and
+  whose export emits `#########` — read back as a literal-hash paragraph on the
+  next import. The JSON wires already range-checked it. New
+  `ApplyError::BadHeadingLevel`.
+- fix(typst): **diagnostic columns count characters, not bytes.** Any multi-byte
+  character earlier on the source line inflated the reported column, which an
+  editor reads as a jump target.
+- fix(pdf): **a non-finite widget `/Rect` is refused (`pdf::bad_rect`) rather
+  than written.** `form.json` rect values deserialize as plain `f32` and
+  saturate to `inf`, and `flip_rect` arithmetic can reach `NaN`; pdf-writer
+  prints a non-finite float verbatim, so `stamp` returned `Ok` with `inf`/`NaN`
+  tokens in the output — no PDF number grammar admits them. `flatten` guards the
+  geometry it draws. Matches the posture `font_size` already took. `regions_of`
+  is still unguarded.
+- fix(pdf): **a base PDF that already carries an `/AcroForm` is refused
+  (`pdf::existing_acroform`).** The catalog rewrite appended a second
+  `/AcroForm` key without looking, leaving a dict the spec does not define and
+  the old form's widgets live in the preserved page `/Annots`. Stripping was
+  already the documented authoring rule; it is now checked.
+- fix(pdf): **`fonts_used` registers only the faces a `/DA` names.** Only `Text`
+  and `Choice` widgets write one, so a checkbox or signature spec carrying
+  `Times`/`Courier` emitted an unreferenced Type1 object and a dead `/DR /Font`
+  entry into every stamped PDF.
+- refactor(core): the unreachable null arm in the `Date`/`DateTime` coercion is
+  deleted (`conform_value` returns on any null before the type match), and
+  `Version` derives the ordering its field order already spells.
+
+## 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
@@ -11,17 +126,6 @@
   `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

package/backends/pdfform/wasm.d.ts

@@ -100,33 +100,24 @@ export type ContentLineKind =
  * 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`.
+ * **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. 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 }`.
+ * 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` 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 =
+ * 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 };
@@ -256,7 +247,7 @@ export type LineOp =
 | { op: "split"; at: number }
 | { op: "join"; line: number }
 | ({ op: "setKind"; line: number } & ContentLineKind)
-| { op: "setContainers"; line: number; containers: ContentContainerInput[] }
+| { op: "setContainers"; line: number; containers: ContentContainer[] }
 | { op: "setContinues"; line: number; continues: boolean };
 
 /**
@@ -299,6 +290,18 @@ export type IslandOp =
  * Within each channel ops apply in sequence against the state the earlier ones
  * left: an island `insert`'s `at` counts earlier ops' slots, and `lineOps`
  * positions and indices renumber through earlier `split`/`join`.
+ *
+ * **Mark rebase.** `delta`, `islandOps` and `lineOps` each move text, and each
+ * rebases the marks already in the field by one rule: a range mark's `start`
+ * takes assoc `after` and its `end` `before`, so an insertion at either edge
+ * grows text *outside* the span; a **zero-width** mark takes `before`, so an
+ * insertion at its own position leaves it put. That last case is the one
+ * position where the two assocs differ, and where an anchor most often sits.
+ *
+ * `markOps` name the result, so a caller emitting them predicts this rebase.
+ * `mapMarks(content, bundle)` runs it instead: pass the bundle's text-moving
+ * channels, diff the marks it returns against the ones you intend, and emit
+ * only the difference. Reproducing the rule by hand is a second copy to drift.
  */
 export interface ChangeBundle {
     delta?: Delta;
@@ -729,6 +732,10 @@ export class Document {
      * Throws on an out-of-range card, a field that is not richtext, a malformed
      * bundle, or an op that applies out of bounds; the value is unchanged on a
      * failed apply.
+     *
+     * Each text-moving channel rebases the marks already in the field, by the
+     * rule on `ChangeBundle`; `mapMarks` answers where they land, so a caller
+     * building `markOps` need not predict it.
      */
     applyChange(addr: Addr | string, bundle: ChangeBundle): void;
     /**
@@ -818,6 +825,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;
     /**
@@ -1301,11 +1312,31 @@ export function formatDocPath(segs: DocPathSeg[]): string;
  */
 export function importMarkdown(markdown: string): Content;
 
+/**
+ * Where `bundle`'s text-moving channels (`delta`, then `islandOps`, then
+ * `lineOps`) leave `content`'s marks: the final-text coordinates the bundle's
+ * `markOps` are written in, under the rebase rule stated on `ChangeBundle`.
+ * The document-free read an editor diffs against to decide which `markOps` to
+ * emit, rather than reproducing that rule in its own language.
+ *
+ * `bundle.markOps` are ignored. The answer is normalized, as the store's is:
+ * marks a text move drops (out of range, zero-width formatting) are absent,
+ * and same-kind runs a move left adjacent arrive already unioned, so a bundle
+ * carrying no `markOps` names the marks the field will hold.
+ * Throws on a non-content `content`, a malformed bundle, or an op that applies
+ * out of bounds: `applyChange`'s errors on the same ops.
+ */
+export function mapMarks(content: Content, bundle: ChangeBundle): ContentMark[];
+
 /**
  * Map a base content position (a USV index into `Content.text`, not a UTF-16
  * offset) through a `delta` to its new position, holding a caret stable across
  * a `revise`. `assoc` decides the side of a same-position insertion (`"after"`
  * moves past it). Throws on a malformed `delta`.
+ *
+ * This maps a position the *caller* holds. For the marks already in a field,
+ * `mapMarks` applies the store's own assoc rule across every channel of a
+ * `ChangeBundle`.
  */
 export function mapPos(delta: Delta, pos: number, assoc: Assoc): number;
 
@@ -1411,6 +1442,7 @@ export interface InitOutput {
     readonly livesession_supportsCanvas: (a: number) => number;
     readonly livesession_update: (a: number, b: number, c: number) => void;
     readonly livesession_warnings: (a: number, b: number) => void;
+    readonly mapMarks: (a: number, b: number, c: number) => void;
     readonly mapPos: (a: number, b: number, c: number, d: number) => void;
     readonly parseDocPath: (a: number, b: number, c: number) => void;
     readonly quill_backendId: (a: number, b: number) => void;

package/backends/pdfform/wasm.js

@@ -279,6 +279,10 @@ export class Document {
      * Throws on an out-of-range card, a field that is not richtext, a malformed
      * bundle, or an op that applies out of bounds; the value is unchanged on a
      * failed apply.
+     *
+     * Each text-moving channel rebases the marks already in the field, by the
+     * rule on `ChangeBundle`; `mapMarks` answers where they land, so a caller
+     * building `markOps` need not predict it.
      * @param {Addr | string} addr
      * @param {ChangeBundle} bundle
      */
@@ -608,6 +612,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}
      */
@@ -2150,11 +2158,48 @@ export function importMarkdown(markdown) {
     }
 }
 
+/**
+ * Where `bundle`'s text-moving channels (`delta`, then `islandOps`, then
+ * `lineOps`) leave `content`'s marks: the final-text coordinates the bundle's
+ * `markOps` are written in, under the rebase rule stated on `ChangeBundle`.
+ * The document-free read an editor diffs against to decide which `markOps` to
+ * emit, rather than reproducing that rule in its own language.
+ *
+ * `bundle.markOps` are ignored. The answer is normalized, as the store's is:
+ * marks a text move drops (out of range, zero-width formatting) are absent,
+ * and same-kind runs a move left adjacent arrive already unioned, so a bundle
+ * carrying no `markOps` names the marks the field will hold.
+ * Throws on a non-content `content`, a malformed bundle, or an op that applies
+ * out of bounds: `applyChange`'s errors on the same ops.
+ * @param {Content} content
+ * @param {ChangeBundle} bundle
+ * @returns {ContentMark[]}
+ */
+export function mapMarks(content, bundle) {
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        wasm.mapMarks(retptr, addHeapObject(content), addHeapObject(bundle));
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        if (r2) {
+            throw takeObject(r1);
+        }
+        return takeObject(r0);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+    }
+}
+
 /**
  * Map a base content position (a USV index into `Content.text`, not a UTF-16
  * offset) through a `delta` to its new position, holding a caret stable across
  * a `revise`. `assoc` decides the side of a same-position insertion (`"after"`
  * moves past it). Throws on a malformed `delta`.
+ *
+ * This maps a position the *caller* holds. For the marks already in a field,
+ * `mapMarks` applies the store's own assoc rule across every channel of a
+ * `ChangeBundle`.
  * @param {Delta} delta
  * @param {number} pos
  * @param {Assoc} assoc

package/backends/pdfform/wasm_bg.wasm.d.ts

@@ -76,6 +76,7 @@ export const livesession_render: (a: number, b: number, c: number) => void;
 export const livesession_supportsCanvas: (a: number) => number;
 export const livesession_update: (a: number, b: number, c: number) => void;
 export const livesession_warnings: (a: number, b: number) => void;
+export const mapMarks: (a: number, b: number, c: number) => void;
 export const mapPos: (a: number, b: number, c: number, d: number) => void;
 export const parseDocPath: (a: number, b: number, c: number) => void;
 export const quill_backendId: (a: number, b: number) => void;

package/backends/typst/wasm.d.ts

@@ -100,33 +100,24 @@ export type ContentLineKind =
  * 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`.
+ * **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. 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 }`.
+ * 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` 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 =
+ * 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 };
@@ -256,7 +247,7 @@ export type LineOp =
 | { op: "split"; at: number }
 | { op: "join"; line: number }
 | ({ op: "setKind"; line: number } & ContentLineKind)
-| { op: "setContainers"; line: number; containers: ContentContainerInput[] }
+| { op: "setContainers"; line: number; containers: ContentContainer[] }
 | { op: "setContinues"; line: number; continues: boolean };
 
 /**
@@ -299,6 +290,18 @@ export type IslandOp =
  * Within each channel ops apply in sequence against the state the earlier ones
  * left: an island `insert`'s `at` counts earlier ops' slots, and `lineOps`
  * positions and indices renumber through earlier `split`/`join`.
+ *
+ * **Mark rebase.** `delta`, `islandOps` and `lineOps` each move text, and each
+ * rebases the marks already in the field by one rule: a range mark's `start`
+ * takes assoc `after` and its `end` `before`, so an insertion at either edge
+ * grows text *outside* the span; a **zero-width** mark takes `before`, so an
+ * insertion at its own position leaves it put. That last case is the one
+ * position where the two assocs differ, and where an anchor most often sits.
+ *
+ * `markOps` name the result, so a caller emitting them predicts this rebase.
+ * `mapMarks(content, bundle)` runs it instead: pass the bundle's text-moving
+ * channels, diff the marks it returns against the ones you intend, and emit
+ * only the difference. Reproducing the rule by hand is a second copy to drift.
  */
 export interface ChangeBundle {
     delta?: Delta;
@@ -729,6 +732,10 @@ export class Document {
      * Throws on an out-of-range card, a field that is not richtext, a malformed
      * bundle, or an op that applies out of bounds; the value is unchanged on a
      * failed apply.
+     *
+     * Each text-moving channel rebases the marks already in the field, by the
+     * rule on `ChangeBundle`; `mapMarks` answers where they land, so a caller
+     * building `markOps` need not predict it.
      */
     applyChange(addr: Addr | string, bundle: ChangeBundle): void;
     /**
@@ -818,6 +825,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;
     /**
@@ -1301,11 +1312,31 @@ export function formatDocPath(segs: DocPathSeg[]): string;
  */
 export function importMarkdown(markdown: string): Content;
 
+/**
+ * Where `bundle`'s text-moving channels (`delta`, then `islandOps`, then
+ * `lineOps`) leave `content`'s marks: the final-text coordinates the bundle's
+ * `markOps` are written in, under the rebase rule stated on `ChangeBundle`.
+ * The document-free read an editor diffs against to decide which `markOps` to
+ * emit, rather than reproducing that rule in its own language.
+ *
+ * `bundle.markOps` are ignored. The answer is normalized, as the store's is:
+ * marks a text move drops (out of range, zero-width formatting) are absent,
+ * and same-kind runs a move left adjacent arrive already unioned, so a bundle
+ * carrying no `markOps` names the marks the field will hold.
+ * Throws on a non-content `content`, a malformed bundle, or an op that applies
+ * out of bounds: `applyChange`'s errors on the same ops.
+ */
+export function mapMarks(content: Content, bundle: ChangeBundle): ContentMark[];
+
 /**
  * Map a base content position (a USV index into `Content.text`, not a UTF-16
  * offset) through a `delta` to its new position, holding a caret stable across
  * a `revise`. `assoc` decides the side of a same-position insertion (`"after"`
  * moves past it). Throws on a malformed `delta`.
+ *
+ * This maps a position the *caller* holds. For the marks already in a field,
+ * `mapMarks` applies the store's own assoc rule across every channel of a
+ * `ChangeBundle`.
  */
 export function mapPos(delta: Delta, pos: number, assoc: Assoc): number;
 
@@ -1411,6 +1442,7 @@ export interface InitOutput {
     readonly livesession_supportsCanvas: (a: number) => number;
     readonly livesession_update: (a: number, b: number, c: number) => void;
     readonly livesession_warnings: (a: number, b: number) => void;
+    readonly mapMarks: (a: number, b: number, c: number) => void;
     readonly mapPos: (a: number, b: number, c: number, d: number) => void;
     readonly parseDocPath: (a: number, b: number, c: number) => void;
     readonly quill_backendId: (a: number, b: number) => void;

package/backends/typst/wasm.js

@@ -279,6 +279,10 @@ export class Document {
      * Throws on an out-of-range card, a field that is not richtext, a malformed
      * bundle, or an op that applies out of bounds; the value is unchanged on a
      * failed apply.
+     *
+     * Each text-moving channel rebases the marks already in the field, by the
+     * rule on `ChangeBundle`; `mapMarks` answers where they land, so a caller
+     * building `markOps` need not predict it.
      * @param {Addr | string} addr
      * @param {ChangeBundle} bundle
      */
@@ -608,6 +612,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}
      */
@@ -2150,11 +2158,48 @@ export function importMarkdown(markdown) {
     }
 }
 
+/**
+ * Where `bundle`'s text-moving channels (`delta`, then `islandOps`, then
+ * `lineOps`) leave `content`'s marks: the final-text coordinates the bundle's
+ * `markOps` are written in, under the rebase rule stated on `ChangeBundle`.
+ * The document-free read an editor diffs against to decide which `markOps` to
+ * emit, rather than reproducing that rule in its own language.
+ *
+ * `bundle.markOps` are ignored. The answer is normalized, as the store's is:
+ * marks a text move drops (out of range, zero-width formatting) are absent,
+ * and same-kind runs a move left adjacent arrive already unioned, so a bundle
+ * carrying no `markOps` names the marks the field will hold.
+ * Throws on a non-content `content`, a malformed bundle, or an op that applies
+ * out of bounds: `applyChange`'s errors on the same ops.
+ * @param {Content} content
+ * @param {ChangeBundle} bundle
+ * @returns {ContentMark[]}
+ */
+export function mapMarks(content, bundle) {
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        wasm.mapMarks(retptr, addHeapObject(content), addHeapObject(bundle));
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        if (r2) {
+            throw takeObject(r1);
+        }
+        return takeObject(r0);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+    }
+}
+
 /**
  * Map a base content position (a USV index into `Content.text`, not a UTF-16
  * offset) through a `delta` to its new position, holding a caret stable across
  * a `revise`. `assoc` decides the side of a same-position insertion (`"after"`
  * moves past it). Throws on a malformed `delta`.
+ *
+ * This maps a position the *caller* holds. For the marks already in a field,
+ * `mapMarks` applies the store's own assoc rule across every channel of a
+ * `ChangeBundle`.
  * @param {Delta} delta
  * @param {number} pos
  * @param {Assoc} assoc

package/backends/typst/wasm_bg.wasm.d.ts

@@ -76,6 +76,7 @@ export const livesession_render: (a: number, b: number, c: number) => void;
 export const livesession_supportsCanvas: (a: number) => number;
 export const livesession_update: (a: number, b: number, c: number) => void;
 export const livesession_warnings: (a: number, b: number) => void;
+export const mapMarks: (a: number, b: number, c: number) => void;
 export const mapPos: (a: number, b: number, c: number, d: number) => void;
 export const parseDocPath: (a: number, b: number, c: number) => void;
 export const quill_backendId: (a: number, b: number) => void;

package/core/wasm.d.ts

@@ -100,33 +100,24 @@ export type ContentLineKind =
  * 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`.
+ * **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. 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 }`.
+ * 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` 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 =
+ * 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 };
@@ -256,7 +247,7 @@ export type LineOp =
 | { op: "split"; at: number }
 | { op: "join"; line: number }
 | ({ op: "setKind"; line: number } & ContentLineKind)
-| { op: "setContainers"; line: number; containers: ContentContainerInput[] }
+| { op: "setContainers"; line: number; containers: ContentContainer[] }
 | { op: "setContinues"; line: number; continues: boolean };
 
 /**
@@ -299,6 +290,18 @@ export type IslandOp =
  * Within each channel ops apply in sequence against the state the earlier ones
  * left: an island `insert`'s `at` counts earlier ops' slots, and `lineOps`
  * positions and indices renumber through earlier `split`/`join`.
+ *
+ * **Mark rebase.** `delta`, `islandOps` and `lineOps` each move text, and each
+ * rebases the marks already in the field by one rule: a range mark's `start`
+ * takes assoc `after` and its `end` `before`, so an insertion at either edge
+ * grows text *outside* the span; a **zero-width** mark takes `before`, so an
+ * insertion at its own position leaves it put. That last case is the one
+ * position where the two assocs differ, and where an anchor most often sits.
+ *
+ * `markOps` name the result, so a caller emitting them predicts this rebase.
+ * `mapMarks(content, bundle)` runs it instead: pass the bundle's text-moving
+ * channels, diff the marks it returns against the ones you intend, and emit
+ * only the difference. Reproducing the rule by hand is a second copy to drift.
  */
 export interface ChangeBundle {
     delta?: Delta;
@@ -545,6 +548,10 @@ export class Document {
      * Throws on an out-of-range card, a field that is not richtext, a malformed
      * bundle, or an op that applies out of bounds; the value is unchanged on a
      * failed apply.
+     *
+     * Each text-moving channel rebases the marks already in the field, by the
+     * rule on `ChangeBundle`; `mapMarks` answers where they land, so a caller
+     * building `markOps` need not predict it.
      */
     applyChange(addr: Addr | string, bundle: ChangeBundle): void;
     /**
@@ -634,6 +641,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;
     /**
@@ -980,11 +991,31 @@ export function formatDocPath(segs: DocPathSeg[]): string;
  */
 export function importMarkdown(markdown: string): Content;
 
+/**
+ * Where `bundle`'s text-moving channels (`delta`, then `islandOps`, then
+ * `lineOps`) leave `content`'s marks: the final-text coordinates the bundle's
+ * `markOps` are written in, under the rebase rule stated on `ChangeBundle`.
+ * The document-free read an editor diffs against to decide which `markOps` to
+ * emit, rather than reproducing that rule in its own language.
+ *
+ * `bundle.markOps` are ignored. The answer is normalized, as the store's is:
+ * marks a text move drops (out of range, zero-width formatting) are absent,
+ * and same-kind runs a move left adjacent arrive already unioned, so a bundle
+ * carrying no `markOps` names the marks the field will hold.
+ * Throws on a non-content `content`, a malformed bundle, or an op that applies
+ * out of bounds: `applyChange`'s errors on the same ops.
+ */
+export function mapMarks(content: Content, bundle: ChangeBundle): ContentMark[];
+
 /**
  * Map a base content position (a USV index into `Content.text`, not a UTF-16
  * offset) through a `delta` to its new position, holding a caret stable across
  * a `revise`. `assoc` decides the side of a same-position insertion (`"after"`
  * moves past it). Throws on a malformed `delta`.
+ *
+ * This maps a position the *caller* holds. For the marks already in a field,
+ * `mapMarks` applies the store's own assoc rule across every channel of a
+ * `ChangeBundle`.
  */
 export function mapPos(delta: Delta, pos: number, assoc: Assoc): number;
 
@@ -1075,6 +1106,7 @@ export interface InitOutput {
     readonly exportMarkdown: (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;
     readonly mapPos: (a: number, b: number, c: number, d: number) => void;
     readonly parseDocPath: (a: number, b: number, c: number) => void;
     readonly quill_backendId: (a: number, b: number) => void;

package/core/wasm.js

@@ -279,6 +279,10 @@ export class Document {
      * Throws on an out-of-range card, a field that is not richtext, a malformed
      * bundle, or an op that applies out of bounds; the value is unchanged on a
      * failed apply.
+     *
+     * Each text-moving channel rebases the marks already in the field, by the
+     * rule on `ChangeBundle`; `mapMarks` answers where they land, so a caller
+     * building `markOps` need not predict it.
      * @param {Addr | string} addr
      * @param {ChangeBundle} bundle
      */
@@ -608,6 +612,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}
      */
@@ -1745,11 +1753,48 @@ export function importMarkdown(markdown) {
     }
 }
 
+/**
+ * Where `bundle`'s text-moving channels (`delta`, then `islandOps`, then
+ * `lineOps`) leave `content`'s marks: the final-text coordinates the bundle's
+ * `markOps` are written in, under the rebase rule stated on `ChangeBundle`.
+ * The document-free read an editor diffs against to decide which `markOps` to
+ * emit, rather than reproducing that rule in its own language.
+ *
+ * `bundle.markOps` are ignored. The answer is normalized, as the store's is:
+ * marks a text move drops (out of range, zero-width formatting) are absent,
+ * and same-kind runs a move left adjacent arrive already unioned, so a bundle
+ * carrying no `markOps` names the marks the field will hold.
+ * Throws on a non-content `content`, a malformed bundle, or an op that applies
+ * out of bounds: `applyChange`'s errors on the same ops.
+ * @param {Content} content
+ * @param {ChangeBundle} bundle
+ * @returns {ContentMark[]}
+ */
+export function mapMarks(content, bundle) {
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        wasm.mapMarks(retptr, addHeapObject(content), addHeapObject(bundle));
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        if (r2) {
+            throw takeObject(r1);
+        }
+        return takeObject(r0);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+    }
+}
+
 /**
  * Map a base content position (a USV index into `Content.text`, not a UTF-16
  * offset) through a `delta` to its new position, holding a caret stable across
  * a `revise`. `assoc` decides the side of a same-position insertion (`"after"`
  * moves past it). Throws on a malformed `delta`.
+ *
+ * This maps a position the *caller* holds. For the marks already in a field,
+ * `mapMarks` applies the store's own assoc rule across every channel of a
+ * `ChangeBundle`.
  * @param {Delta} delta
  * @param {number} pos
  * @param {Assoc} assoc

package/core/wasm_bg.wasm.d.ts

@@ -61,6 +61,7 @@ export const document_warnings: (a: number, b: number) => void;
 export const exportMarkdown: (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;
 export const mapPos: (a: number, b: number, c: number, d: number) => void;
 export const parseDocPath: (a: number, b: number, c: number) => void;
 export const quill_backendId: (a: number, b: number) => void;

package/package.json

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

package/runtime/runtime.d.ts

@@ -24,6 +24,7 @@ import type {
 	exportMarkdown,
 	rebase,
 	mapPos,
+	mapMarks,
 	parseDocPath,
 	formatDocPath
 } from '../core/wasm.js';
@@ -42,6 +43,7 @@ export interface CoreSurface {
 	exportMarkdown: typeof exportMarkdown;
 	rebase: typeof rebase;
 	mapPos: typeof mapPos;
+	mapMarks: typeof mapMarks;
 	parseDocPath: typeof parseDocPath;
 	formatDocPath: typeof formatDocPath;
 }
@@ -130,7 +132,6 @@ export type {
 	ContentLine,
 	ContentLineKind,
 	ContentContainer,
-	ContentContainerInput,
 	ContentMark,
 	ContentIsland,
 	TableProps,
@@ -205,8 +206,7 @@ import type {
 	ImageProps,
 	ContentMark,
 	ContentLine,
-	ContentContainer,
-	ContentContainerInput
+	ContentContainer
 } from '../core/wasm.js';
 
 /** Narrow a {@link ContentIsland} to the pinned `table` arm (`props: TableProps`). */
@@ -247,7 +247,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
@@ -280,11 +280,11 @@ 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.
+// `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,
@@ -313,7 +313,7 @@ export declare function isUnknownIsland(
  */
 export declare function assignInstances(
 	runs: (ContentContainer | null)[]
-): (ContentContainerInput | 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.

package/runtime/runtime.js

@@ -40,7 +40,7 @@ import initCore, { Quill, Document } from '../core/wasm.js';
 // itself), a `node:fs` read under Node, whose `fetch` rejects `file:` URLs.
 // Resolution-time, so `node:fs` never enters a browser graph.
 import { toModuleSource } from '#quillmark-env';
-import { importMarkdown, exportMarkdown, rebase, mapPos } from '../core/wasm.js';
+import { importMarkdown, exportMarkdown, rebase, mapPos, mapMarks } from '../core/wasm.js';
 import { parseDocPath, formatDocPath } from '../core/wasm.js';
 
 // ── Initialization ──────────────────────────────────────────────────────────
@@ -90,6 +90,7 @@ const CORE_SURFACE = Object.freeze({
 	exportMarkdown,
 	rebase,
 	mapPos,
+	mapMarks,
 	parseDocPath,
 	formatDocPath
 });
@@ -553,7 +554,7 @@ function weldsWith(a, b) {
 
 /**
  * @param {(import('../core/wasm.js').ContentContainer | null)[]} runs
- * @returns {(import('../core/wasm.js').ContentContainerInput | null)[]}
+ * @returns {(import('../core/wasm.js').ContentContainer | null)[]}
  */
 export function assignInstances(runs) {
 	let prev = null;