@quillmark/wasm 0.110.0 → 0.112.0

package/CHANGELOG.md

@@ -1,5 +1,327 @@
 # Changelog
 
+## v0.112.0 - 2026-09-01
+
+- feat(content)!: **every vocabulary member spells its payload in `attrs`.** The
+  canonical content had two spellings for one thing: a built-in put its payload
+  in named siblings (`{"kind":"heading","level":1}`), an unknown put it in one
+  opaque bag, and which a document used depended on whether the build that wrote
+  it happened to know the name. Promoting a name from unknown to built-in was
+  therefore an encoding change, and five mechanisms existed to bridge the split.
+  Now `Heading{level}` ⇄ `attrs.level`, `Code{lang}` ⇄ `attrs.lang`, `Link{url}`
+  ⇄ `attrs.url`, `Anchor{id}` ⇄ `attrs.id`, and `ListItem`'s
+  `ordered`/`start`/`ordinal` ⇄ the same three under `attrs`, with the envelope
+  keys (`kind`/`type`/`container`, `containers`, `continues`, `start`/`end`,
+  `instance`) staying siblings and an empty bag omitted. The Rust types are
+  unchanged — typed in memory, uniform on the wire. `fold_legacy_attrs`, the
+  `reject_*_attrs` family, `MarkKind::ord` and its placement rule, and
+  `RESERVED_*`'s wire role are all deleted; the canonical mark tie-break becomes
+  `MarkKind::sort_key`, the `(type, attrs)` pair the wire carries, which two
+  builds compute identically whether or not either knows the member. **Stored
+  documents need no migration**: the decoder reads the old spelling wherever the
+  `attrs` bag is absent. That is the load-bearing half — a `richtext` field
+  rests as a content object inside an opaque payload value carrying no schema
+  tag, so most stored content reaches no migration and a walk cannot safely find
+  it (`$ext` is arbitrary host data by contract). The fallback is frozen: unlike
+  the fold, a promotion neither grows it nor inherits it. The **break is at the
+  seam**: a host reading `line.level` / `line.lang` / `mark.url` / `mark.id` or a
+  list item's shape reads them under `attrs` (the TS narrowing types move too, so
+  `typecheck` reports it), and the authored lane — `overwrite`, `install`,
+  `CardInput.body`, and the op wire — *rejects* the old spelling rather than
+  reading it, so a stale write throws instead of landing somewhere it did not
+  aim. A foreign bag beside a built-in becomes legal in exchange, dropping unread
+  as it always did in effect. Canonical bytes move (`attrs` on built-ins, and
+  coincident marks reorder on the new tie-break), so **content hashes recompute
+  once**; generated Typst nests coincident wraps the other way for identical
+  glyphs, and `exportMarkdown` nests them the same way (`**~~x~~**` becomes
+  `~~**x**~~`, parsing back to the same content), so goldens and any hash over
+  either projection move too. A consumer holding bare seam JSON outside a
+  stored document gets a hard break, having no tag to dispatch on. The storage
+  tag becomes `quillmark/document@0.112.0`; `@0.93.0` rows migrate forward on
+  read. See [0.111 → 0.112](docs/migrations/0.111-to-0.112.md).
+- feat(core)!: **`fieldAt` and `positionAt` take a pointer tolerance, and
+  resolve to the nearest ink rather than the first containing it.** A glyph's
+  box is its run's ink height by its own advance, so a text column answers over
+  a fraction of the area it occupies: the boxes of one line abut, but the
+  leading between two lines is inside the paragraph and on no glyph. An 11pt
+  paragraph is live over about two thirds of its own height at default leading
+  and under half of it double-spaced, which is the whole of why clicking the
+  preview to place a caret misses. Both queries now take `tol` in PDF points
+  (`tolPt`, optional, on the WASM seam) and answer with the nearest placement
+  within it, a radius in both axes. The caller derives it from the scale it drew
+  the page at, slack being a property of the pointer rather than of the
+  document: a tolerance fixed in points shrinks under the cursor exactly as the
+  target does. Ranking by distance rather than growing each rect is what keeps
+  the answer the nearer item's — outset boxes overlap, and a first match over
+  them decides by paint order — and makes the tolerance a pure widening:
+  containment is distance zero, so no point that resolves exactly changes answer
+  however high `tol` goes, and later-painted still wins a tie.
+  `RenderedRegion::distance` is the measure, and `contains` is now stated in
+  terms of it. The break is the added argument on
+  `SessionHandle::{field_at,position_at}` and their `LiveSession` forwarders,
+  which a type checker reports; `0.0` is the previous behaviour exactly. The
+  WASM argument is optional and defaults to `0`, so no JS caller changes.
+- fix(content): **markdown export escapes what markdown strips at a line's
+  edges.** A line's leading and trailing space/tab crossed verbatim, so
+  `from_markdown(to_markdown(rt))` dropped it — and where the leading run
+  opened an indented code block, or hid a `- ` / `# ` / `> ` / `N. ` marker
+  from the position-0 escapes, the re-import rewrote the line's kind and
+  containers with it: `"    foo"` returned as `"foo"` under `Code`, and
+  `"   - item"` as `"item"` inside a `ListItem` nobody wrote. Neither takes
+  adversarial input, since `apply_text_delta` and `from_plaintext` both mint
+  edge whitespace: a `Codec::Plaintext` field holding an indented sample was
+  corrupted by `Document::to_markdown`. The verify-and-drop net could not catch
+  it, being gated on flanking marks — a mark-free line never reaches it, and
+  the `,…,` probe wrapping the lines that do blocks every leading-block
+  construct by design, so it reads such a line as safe while the `**` ships
+  into the text. Space and tab at an edge now cross as character references
+  (` ` / `	`), markdown having no backslash escape for whitespace. A
+  literal `&` still escapes, so text authored as ` ` returns as itself. An
+  image `alt` is the one edge run a reference cannot carry — the parser trims
+  alt after decoding it — and joins the module's documented codec limits.
+  Emitted markdown moves for content holding an edge run.
+- fix(content): **a `=` run on a continuation line stays text.** It underlined
+  the paragraph line above it into a setext heading, taking the hard break's
+  `\` into the text with it: `"abc\n==="` returned as an H1 reading `"abc\"`.
+  `\=` joins the block starters escaped at position 0.
+- fix(content): **an unknown island's type cannot leave its placeholder.**
+  `emit_island` wrote `island_type` — an open wire string no lane constrains —
+  raw into `<!-- island:… -->`, where a `-->` closes the comment early and a
+  line break ends the HTML block, either way leaking the rest as content text.
+  At column zero that opens whatever the rest spells, a `~~~` card fence
+  included, which the document layer reads as another card. The type crosses
+  with `<` / `>` as entities and control characters as spaces; nothing reads it
+  back out of markdown.
+- fix(content): **an inline unknown island keeps its line whole.**
+  `fix_html_comment_fences` inserted a newline after any `-->` carrying text
+  behind it, but only a comment opening a line — at most three spaces of indent
+  — starts an HTML block. One reached mid-line is inline HTML and swallows
+  nothing, so an inline island turned `ab` into `"a b"`. The repair fires for
+  the block-opening case alone.
+- fix(core): **the payload ingresses refuse what no parse can produce.** The
+  wire `TryFrom`, the storage DTO and `push_card` / `insert_card` each admitted
+  a payload whose markdown does not read back: a duplicate field key, more
+  fields than `MAX_FIELD_COUNT`, a repeated `$` entry, a comment whose text
+  spans lines, and a composable card carrying `$quill` or `$seed`. The comment
+  is the one that fails quietly — `#` opens a single line, so a text of
+  `"hi\ninjected: pwned"` emits bare YAML after the first line and re-reads as
+  a field nobody wrote. The rest emit markdown the parser rejects, and a
+  composable `$quill` also trips the `debug_assert` in `from_main_and_cards`,
+  which the rebuild behind `compile_data` runs: a render panicked on a debug
+  build where it owed an error. `PayloadViolation` carries the verdict —
+  `FieldViolation`'s seam one level up, reading the item list rather than one
+  item — which the wire maps to `WireError::InvalidPayload` and the DTO to
+  `StorageError::Malformed`, so both boundaries share one message. The
+  `$quill` / `$seed` half is positional, since a `CardWire` is equally how the
+  main card is read back, so it sits at placement beside the `$kind` gate as
+  `EditError::RootOnlyEntry` (`edit::root_only_entry`). The DTO refuses a root
+  `$kind` other than `main` and synthesises an absent one, as the parser does.
+  Additive: `validate_payload`, `PayloadViolation`, `MetaKey::ALL`. Both error
+  enums are `#[non_exhaustive]`, so no compiling caller changes, and no
+  document the format calls readable is refused.
+- fix(cli): **`render -f svg` / `-f png` writes every page.** The Typst backend
+  emits one artifact per page and the command wrote `artifacts.first()`,
+  discarding the rest with no warning, so a multi-page document produced a
+  single-page file that looked complete. A multi-page render now writes one
+  numbered file per page: `out.svg` becomes `out-1.svg`, `out-2.svg`, ….  Page
+  one is numbered too, so no unnumbered file claims to be the whole document.
+  `--stdout` carries one artifact and refuses a multi-page render.
+- fix(core): **a `!must_fill` marker on a mapping is refused at every ingress,
+  not just at parse.** `Card::store_fill`, the `CardWire` boundary and the
+  `@0.92.0` storage DTO took `fill: true` against an object and emitted
+  `x: a: 1`, which `Document::parse` then refuses — breaking the emit round
+  trip. The rule the parser enforces now sits beside the other field invariants
+  as `edit::validate_fill_targets`, raising `edit::fill_on_mapping`. A canonical
+  content object stays legal: emit projects it to its markdown scalar first,
+  which is the shape `!must_fill` emits against.
+- fix(core): **a comment after a nested key that needs quoting keeps its
+  position.** A comment's position is its index among its mapping's children,
+  and the prescan matched only a bare `[A-Za-z_][A-Za-z0-9_]*` nested key. So
+  `"a b": 1`, which the emitter writes itself, was not counted, and every comment
+  after it in that mapping round-tripped one slot early. The prescan reads a
+  nested key in both spellings the emitter writes at depth: quoted, and plain
+  with characters the bare form excludes.
+- fix(pdfform): **an array-bound text widget is multiline.** `resolve::coerce_text`
+  joins an array's elements with newlines unconditionally while the widget took
+  `multiline` from `ui`, defaulting to false: a viewer collapsed the `/V` at its
+  first line while the flattened SVG/PNG stacked every line, so the interactive
+  PDF and the raster disagreed.
+- fix(core): **a version segment is plain digits, and a `$quill` `@` carries a
+  selector.** `u32::from_str` accepts a leading `+`, so `memo@+2.+1` parsed as
+  `Minor(2, 1)` and `version: "+1.0"` loaded, though `quill_ref_hint` promises
+  digits and neither spelling re-`Display`s to itself; and `memo@` yielded an
+  empty selector silently read as `latest`. An absent selector still means
+  latest.
+- fix(core): **an unquoted numeric `version:` keeps its fraction.** The loader
+  accepts a YAML number by intent but converted it through `f64::to_string`,
+  which drops the fraction: `version: 1.0` became `"1"` and failed validation
+  with a hint naming the `'1.0'` the author had written. An unquoted `1.10` is
+  the YAML number `1.1` before the loader sees it, so VERSIONING.md's quote-it
+  rule now names that rather than the `x.0` case.
+- fix(python): **a value with no JSON form raises instead of storing its
+  `repr`.** `py_to_json_at` fell through to `str()`, so a tuple stored
+  `"('a', 'b')"`, a `bytes` stored `"b'...'"` and a `set` stored `"{'x'}"` —
+  silently, surfacing as garbage at render or read-back. `datetime.date`,
+  `datetime.datetime` and `datetime.time` keep the stringified form the
+  fallback existed for; everything else is a `ValueError`, which is what the
+  WASM lane already refuses.
+- fix(python): **the type stub declares `Diagnostic.args`**, the localization
+  channel the class exposes. Under a type checker `diag.args` was an attribute
+  error on a `@final` class.
+- docs(python): **the error contract names both classes the binding raises.**
+  `errors.rs` claimed every raised exception is `QuillmarkError` carrying
+  diagnostics, while an argument the binding cannot convert raises `ValueError`
+  — the behavior the binding's own tests pin. Engine refusals carry diagnostics;
+  an unconvertible argument raises `ValueError` before the engine is called.
+  Stated in the module doc and in the error-handling guide.
+- fix(wasm): **`new Document(ref)` refuses an invalid reference with the code
+  and hint `setQuillRef` attaches.** The same input was classified two ways by
+  one binding: `parse::invalid_quill_reference` plus the canonical grammar hint,
+  or a bare message. Both doors mint it through one helper now.
+- fix(typst): **a literal `;` after emitted inline markup survives to the
+  page.** Typst's markup parser reads a semicolon directly after an embedded
+  code expression as that expression's terminator and renders nothing, so
+  ``Use `--force`; otherwise`` lowered to `#raw("--force"); otherwise` and
+  dropped the character. `continues_expr` guarded `(` and `.ident` for the same
+  reason; it guards `;` now, and the emitter writes the same `\` before it.
+- fix(typst): **document text reaches the page as the characters it holds, not
+  Typst's substitutions for them.** `escape_markup` escaped `~`, whose lexer
+  shorthand is a non-breaking space, and left the rest of that class active:
+  `pages 3--5` rendered an en dash, `wait...` an ellipsis, `-5` a minus sign,
+  and `-?` an invisible soft hyphen, taking both authored characters off the
+  page. A mark decided it too, since Typst reads the text behind one as a fresh
+  token: `x-5` stayed literal but `**x**-5` lowered to `#strong[x]-5`, a minus
+  sign the content never held. Each shorthand's head is escaped now, which is
+  enough — what one leaves behind is too short to re-form it. **Smart quotes
+  stay.** `'` and `"` are an element with a set rule, not a lexer shorthand, so
+  a quill picks its own typography with `#set smartquote(enabled: false)`; the
+  emitter escaping them would settle that for every quill with no way back.
+  Documents holding a dash pair, an ellipsis or a signed number render
+  differently.
+- fix(typst): **an island that renders as nothing no longer joins the text
+  either side of it.** An island type this build does not know, and an empty
+  table island, emit no markup, so the two text runs their slot separated abut
+  in the output — where the escapers, which run per text run, see one side of
+  the join at a time. `a/`, such an island, `/b` wrote `a//b`: a Typst comment
+  that swallowed the rest of the paragraph. The emitter guards that seam with
+  the same `\` it writes at a line anchor and an expression tail.
+- fix(typst): **the caret one past a field's last character resolves to the last
+  glyph, not the paragraph's first.** `Scan::locate` admits the end position but
+  `forward_pos` matched runs half-open, so the most common caret position while
+  typing fell through to the segment's generated start. A position no run
+  contains now resolves against the nearest preceding run.
+- fix(typst): **a vendored package whose manifest declares a non-semver
+  `version` or an unusable `entrypoint` path warns instead of failing the
+  session.** Both aborted `QuillWorld::new` even when the plate never imports
+  that package, where an unparseable manifest, an unusable asset path, and a
+  missing entrypoint already warn and carry on. A non-semver `version` skips the
+  package; an unusable `entrypoint` path keeps the files already loaded and
+  skips only the check that the entrypoint is among them.
+- fix(wasm): **`RenderResult` crosses a diagnostic's `args` as the
+  `Record<string, unknown>` it declares.** It returns through tsify's ABI, whose
+  default serializer emits a `Map` for a map-typed field, where every
+  hand-serialized diagnostic path passes `serialize_maps_as_objects(true)`.
+  `RenderResult.warnings` puts the document's parse warnings ahead of the
+  render's own, and a `plate::unsupported_construct` parse warning carries
+  `args`: a quill declining a construct its body still holds renders
+  successfully, and `args.construct` read back `undefined`. `RenderResult` and
+  `Diagnostic` declare `hashmap_as_object`, and a `const` assertion holds each
+  to it.
+- fix(content): **a table island whose `aligns` or a row is not an array
+  normalizes to one the store can reload.** `normalize_table_props` repaired a
+  non-array `header` but fell through for the other two, while `table_shape_error`
+  read them as width 0 — so an island op carrying `{"aligns": "bogus"}` was
+  accepted and serialized, and the exact bytes then failed to reopen with
+  `TableAlignsMismatch`. Normalizing a table now makes its shape check pass, as
+  `KnownIslandType::normalize_props` promises.
+- fix(content): **a code block's `lang` is reduced to an identifier on the
+  storage lane and refused on the authored one.** `sanitize_lang` ran on import
+  only, so the storage decode and the `setKind` op wire took any string and
+  `emit_code` wrote it onto the fence header verbatim: a `lang` of
+  `"rust\ninjected line"` exported a content line the document never had, and a
+  backtick made the fence illegal. The storage decode sanitizes, so a blob
+  written that way still opens; the authored wire raises a shape error, since
+  the host is writing now and the repair would be silent.
+- fix(core): **a variant-bearing enum refuses a non-string `default:` at load,
+  as a plain enum already does.** The scalar branch applied the render floor's
+  leniency to a schema literal, so `default: 1` against `values: ["1"]` loaded
+  clean and then selected nothing: `selected_member`, `resolve_variant_sourced`
+  and the absent-discriminant fallback all read the default through `as_str`, so
+  the field compiled to the blank world instead.
+- fix(core): **a seeded variant container commits at its resting form.**
+  `seed_parts` runs every other field through the strict write, but
+  `seed_variant` pushed its assembled container straight through, so a `$seed`
+  overlay for a richtext cell rested as raw markdown and the next `conform`
+  rewrote bytes on a document nobody edited — the divergence the shared write
+  exists to prevent.
+
+## 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

package/README.md

@@ -173,9 +173,9 @@ discriminates the two formats without exceptions as control flow:
 const doc = Document.tryFromJson(content) ?? Document.fromMarkdown(content);
 ```
 
-The `schema` value (`quillmark/document@0.93.0`) is the **model version**,
+The `schema` value (`quillmark/document@0.112.0`) is the **model version**,
 not the running crate version. It is a hand-set constant, bumped only when
-the `Document` model itself changes, so every `0.93.x` patch release reads
+the `Document` model itself changes, so every `0.112.x` patch release reads
 and writes that same value.
 
 - **Upgrading is safe.** A newer build always reads documents written by an

package/backends/pdfform/wasm.d.ts

@@ -74,8 +74,9 @@ export interface Content {
 
 /** One `\n`-separated segment of `Content.text`, in order. `kind` is an open set:
  * an unknown role round-trips with opaque `attrs` and renders as a paragraph.
- * The open arm blocks discriminant narrowing, so read `level`/`lang` behind a
- * check of the arm you want. */
+ * Every role spells its payload in `attrs`, known or not, so promoting one moves
+ * no bytes. The open arm blocks discriminant narrowing, so read
+ * `attrs.level`/`attrs.lang` behind a check of the arm you want. */
 export type ContentLine = {
     containers: ContentContainer[];
     /** A within-block hard line break rather than a new block. Omitted (false) in the common case. */
@@ -85,11 +86,11 @@ export type ContentLine = {
 /** A line's block role, shared by `ContentLine` and the `setKind` op. */
 export type ContentLineKind =
 | { kind: "para" }
-| { kind: "heading"; level: number }
-| { kind: "code"; lang?: string }
+| { kind: "heading"; attrs: { level: number } }
+| { kind: "code"; attrs?: { lang?: string } }
 | { kind: "island" }
 | { kind: "rule" }
-| { kind: string; attrs: unknown };
+| { kind: string; attrs?: unknown };
 
 /** An ancestor block a line nests inside, outermost first. Open like
  * `ContentLine.kind`: an unrecognized container round-trips with opaque `attrs`
@@ -118,22 +119,26 @@ export type ContentLineKind =
  * 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: "list_item";
+    attrs: { ordered: boolean; start: number; ordinal: number };
+    instance: number;
+}
 | { container: "quote"; instance: number }
-| { container: string; attrs: unknown; 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
+ * guard: `isLinkMark` (`attrs.url`) / `isAnchorMark` (`attrs.id`), from
  * `@quillmark/wasm/runtime`. An `anchor`'s `id` is a caller-supplied opaque
  * handle, unique per `Content` and invariant while the mark lives (positions
  * rebase, the id never does); it has no markdown projection and survives only
  * through the edit lane. */
 export type ContentMark = { start: number; end: number } & (
 | { type: "strong" | "emph" | "underline" | "strike" | "code" }
-| { type: "link"; url: string }
-| { type: "anchor"; id: string }
-| { type: string; attrs: unknown }
+| { type: "link"; attrs: { url: string } }
+| { type: "anchor"; attrs: { id: string } }
+| { type: string; attrs?: unknown }
 );
 
 /** A cell in a `TableProps`. `marks` rides the prose `ContentMark` shape, but
@@ -290,6 +295,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;
@@ -548,7 +565,7 @@ export interface ContentHit {
      */
     field: string;
     /**
-     * USV offset into the field\'s `Content`.
+     * USV offset into the field's `Content`.
      */
     pos: number;
     /**
@@ -565,12 +582,12 @@ export interface ContentHit {
  * (paragraph, heading, whole code fence) and per page each touches, a scalar
  * referenced at several plate sites surfaces each site, and tracked content
  * plus a `field:`-bound widget yields both. Group by `field`. The whole-field
- * highlight is the union of a page\'s `span`-bearing rects, so inter-paragraph
+ * highlight is the union of a page's `span`-bearing rects, so inter-paragraph
  * whitespace stays uncovered; `LiveSession.fieldBoxes(field)` owns that union.
  */
 export interface FieldRegion {
     /**
-     * Canonical `DocPath` field address (e.g. `\"cards.indorsement[1].from\"`):
+     * Canonical `DocPath` field address (e.g. `"cards.indorsement[1].from"`):
      * the grammar `parseDocPath` reads and `Diagnostic.path` carries. Feed it
      * back to `fieldBoxes` / `locate`.
      */
@@ -584,7 +601,7 @@ export interface FieldRegion {
      */
     rect: [number, number, number, number];
     /**
-     * The slice this box covers: USV `[start, end)` into the field\'s `Content`
+     * The slice this box covers: USV `[start, end)` into the field's `Content`
      * for one content segment, `undefined` for a scalar site or widget.
      */
     span?: [number, number];
@@ -599,7 +616,7 @@ export interface Diagnostic {
     message: string;
     location?: Location;
     /**
-     * Document-model path anchor (e.g. `\"cards.indorsement[0].signature_block\"`),
+     * Document-model path anchor (e.g. `"cards.indorsement[0].signature_block"`),
      * set on schema validation diagnostics and `undefined` otherwise.
      */
     path?: string;
@@ -720,6 +737,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;
     /**
@@ -1056,8 +1077,14 @@ export class LiveSession {
      * `FieldRegion.rect`, so from a canvas click use
      * `x = clickPx.x / renderScale`, `y = pageHeightPt - clickPx.y / renderScale`.
      * Unlike `regions()`, *every* placement answers, not just the first.
+     *
+     * `tolPt` is how far off the ink a click still counts, in the same points,
+     * and defaults to `0` — exact. Convert the pointer slack a surface wants
+     * from CSS pixels at the scale it drew the page (`slackPx / renderScale`),
+     * so it stays the same size under the cursor as the page zooms. The
+     * nearest placement answers, so raising it only fills a miss.
      */
-    fieldAt(page: number, x: number, y: number): string | undefined;
+    fieldAt(page: number, x: number, y: number, tol_pt?: number | null): string | undefined;
     /**
      * The whole-field highlight boxes for `field`: one union rect per page over
      * the field's `span`-bearing content segments, the union `regions()` leaves
@@ -1097,11 +1124,15 @@ export class LiveSession {
     /**
      * A point → **content position**: the field *and* a USV offset into its
      * `Content`, for placing a caret or mapping a selection into the content
-     * model, or `undefined` off all content ink. `x`/`y` are PDF points,
-     * bottom-left origin, as in `fieldAt`. The offset is cluster-exact and
-     * degrades to the containing segment's start on origin-less ink.
+     * model, or `undefined` off all content ink. `x`/`y`/`tolPt` are PDF
+     * points, bottom-left origin, as in `fieldAt`. The offset is cluster-exact
+     * and degrades to the containing segment's start on origin-less ink.
+     *
+     * `tolPt` earns the most here: the leading between two lines lies inside a
+     * paragraph and on no glyph, and under `tolPt` such a point takes the
+     * nearer line.
      */
-    positionAt(page: number, x: number, y: number): ContentHit | undefined;
+    positionAt(page: number, x: number, y: number, tol_pt?: number | null): ContentHit | undefined;
     /**
      * Schema-field geometry for this compiled session: each content field's
      * **first placement** (one region per page it touches) plus widget and
@@ -1296,11 +1327,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;
 
@@ -1394,18 +1445,19 @@ export interface InitOutput {
     readonly formatDocPath: (a: number, b: number) => void;
     readonly importMarkdown: (a: number, b: number, c: number) => void;
     readonly livesession_backendId: (a: number, b: number) => void;
-    readonly livesession_fieldAt: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly livesession_fieldAt: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
     readonly livesession_fieldBoxes: (a: number, b: number, c: number, d: number) => void;
     readonly livesession_locate: (a: number, b: number, c: number, d: number) => number;
     readonly livesession_pageCount: (a: number) => number;
     readonly livesession_pageSize: (a: number, b: number, c: number) => void;
     readonly livesession_paint: (a: number, b: number, c: number, d: number, e: number) => void;
-    readonly livesession_positionAt: (a: number, b: number, c: number, d: number) => number;
+    readonly livesession_positionAt: (a: number, b: number, c: number, d: number, e: number) => number;
     readonly livesession_regions: (a: number, b: number) => void;
     readonly livesession_render: (a: number, b: number, c: number) => void;
     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;