@quillmark/wasm 0.123.0 → 0.124.0

package/CHANGELOG.md

@@ -1,5 +1,147 @@
 # Changelog
 
+## v0.124.0 - 2026-10-10
+
+Upgrade path: [0.123 → 0.124](docs/migrations/0.123-to-0.124.md).
+
+### Elements
+
+- feat(content,typst)!: **a `qm-<name>` element is stored content**, where its
+  tags dropped. A pair of tag lines wraps the blocks between them and keeps its
+  attributes as strings, and a line holding only `qm-*` tags is a tag line
+  wherever it stands outside a heading, a mark or a link. Export writes each
+  tag on its own line, and an element around nothing as its pair on one line.
+  An element left open, self-closing or inside a line of text drops and warns
+  `parse::dropped_construct` as `qm-<name>`. (#2096, #2141)
+- feat(typst)!: **a Typst quill renders an element through the renderer its
+  plate registers in the helper's `elements` state**, called `(attrs, body)`,
+  and the built-in `keep` holds its run on one page. An element no renderer
+  takes, `keep` aside, warns `typst::unregistered_element` at its field, and
+  `quillmark validate` fails an `example.md` holding one. (#2096, #2140)
+- feat(core,wasm)!: **the content types gain an element member**:
+  `Container::Element` and `Invariant::BadElement` in Rust, and `{ container:
+  "element" }` in WASM. (#2096)
+
+### Tables
+
+- feat(typst)!: **a `qm-table` wrapper lays out its table**: `widths` weights
+  the columns, `align` places the table, and a bare `headless` draws the first
+  row as a body row, with no `table.header`. (#2096, #2142)
+- feat(content,typst)!: **a `qm-cell` pair around a table cell's whole content
+  aligns that cell** through `align` and `valign`, and a stored cell's `align`
+  or `valign` renders. (#2134, #2139)
+- fix(content)!: **a `|` in a table cell's code span or link destination stays
+  in its cell**; export escapes it, where it split the cell on re-import.
+  (#2134)
+
+### Task lists and footnotes
+
+- feat(content,typst)!: **`- [ ]` and `- [x]` render a box**, ticked for
+  `[x]`, and import as the list item's `checked`, where the brackets were text.
+  A plate restyles the box through the helper's `tasks` state; `\[ ]` keeps the
+  text. (#2135)
+- feat(content)!: **a footnote definition drops with its note and warns
+  `parse::dropped_construct` (`footnote`)**, where it silently defined a link.
+  (#2135)
+
+### Raw HTML
+
+- feat(content)!: **a markdown import reports what it drops**: a raw tag, the
+  block CommonMark runs it to, and a `<u>` left open each warn
+  `parse::dropped_construct`, at the body or at a `richtext` field, and
+  `quillmark validate` fails an `example.md` holding one. (#2096)
+- fix(content)!: **an inline `<u>` pairs as HTML pairs it**, closing the
+  innermost open `<u>` and never a `**`. (#2096)
+- fix(content)!: **a fenced block holding `<!-- a --> b` keeps its line, text
+  after a block nested in a tight list item opens its own line, and a line of
+  tags after a table's rows ends the table.** (#2096)
+
+### Whitespace
+
+- fix(typst): **typed spaces keep their width on the page**: a line's leading
+  spaces indent it, and a run of spaces inside a line, a mark's close between
+  them included, is as wide as the spaces in it. (#2143, #2144)
+- fix(content)!: **a paragraph whose first line holds only tags that drop opens
+  without a leading space.** (#2141)
+
+### Revise
+
+- feat(core,wasm,python): **`reviseDocument` / `revise_document` replace a
+  whole document with markdown and keep its comment anchors, island ids and
+  `$ext` where they match**, and `toAnnotatedMarkdown` /
+  `to_markdown_annotated` show where each anchor sits. (#2096)
+- fix(content)!: **every revise keeps the island ids it can match**, and mints
+  past the field's highest, where it re-minted each by position. (#2096, #2144)
+- feat(core,wasm,python)!: **an import and a revise return their warnings**:
+  `from_markdown` returns `Imported`, a revise `Revised { delta, warnings }`,
+  and `addCard` / `add_card` a list of diagnostics. (#2096)
+- fix(core): **a revise keeps the YAML comments nested in a field it
+  revises.** (#2144)
+
+### Validation and rendering
+
+- feat(core)!: **`Quill::validate` warns `validation::declined_construct` at a
+  field holding a construct the backend will not draw**, and the acroform
+  backend warns `backend::declined_construct` at render. (#2096)
+- fix(wasm,python)!: **a one-shot render carries the render's warnings
+  alone**, not the document's parse and conform warnings. (#2096)
+- fix(typst,cli)!: **`quillmark validate` reads `typst.plate_file` as a render
+  does**, refusing it with the render's own `typst::plate_*` diagnostic. (#2096)
+
+### Storage
+
+- feat(core)!: **a save writes `quillmark/document@0.124.0`**, the first tag
+  that holds an element or a task item's `checked`. Every older row loads as
+  before; a 0.123 build refuses a 0.124 row. (#2135)
+
+### Card YAML
+
+- fix(core)!: **text after a card-yaml block's root value, and a mapping
+  holding two keys of one text, fail the parse** at the offending line, where
+  they dropped or overwrote. A tag inside a merge's value warns at the value's
+  path. (#2096)
+- fix(core): **the colon hint names the field whose `:` opens a mapping and
+  quotes its suggested value.** (#2136, #2144)
+
+### WASM
+
+- fix(wasm)!: **a JSON `null` inside a returned value crosses as `null`**, where
+  it crossed as `undefined`. (#2096)
+- fix(wasm)!: **an options object inheriting a key its verb does not read from
+  a null-prototype object throws `unknown key`**, and one whose read throws is
+  refused with the handle left usable. (#2096)
+
+### Base PDF reading
+
+- fix(pdf)!: **a hybrid-xref base fails as `pdf::xref_stream`**, a `/Kids` that
+  is no array of references and an unreadable annotation fail to parse, and a
+  name compares through its `#xx` escapes. An `/Info` reached through a
+  reference chain stamps. (#2096)
+
+
+## v0.123.1 - 2026-10-06
+
+Upgrade path: [0.123.0 → 0.123.1](docs/migrations/0.123.0-to-0.123.1.md).
+
+### Table cells
+
+- feat(content)!: **a table cell carries a line break**, one `\n` in its
+  `text`, spelled `<br>` inside the pipe cell (`| line one<br>line two |`, any
+  case, with attributes or a closing `/`) and typeset as `#linebreak()`. A
+  mark spans the break as it spans a prose hard break, and its edge moves off
+  it. `to_markdown` writes a cell's `\n` as `<br>`, and a `\n` in a cell
+  written through the JSON lanes is a break, where normalization made it a
+  space. `TableCell.text` is unchanged in shape. (#2071)
+- feat(content)!: **an inline `<br>` is a hard break in a paragraph and a
+  space in a heading**, where it rendered nothing, so a `richtext(inline)`
+  value holding one now has two lines and fails as `validation::not_inline`
+  (`edit::field_not_inline` on a strict write; a quill `default:` fails to
+  load), and nothing else reports the change. A `<br>` with no text before it
+  on its line, or alone on a line, still renders nothing; `\<br>` and a `<br>`
+  in backticks stay literal. A `<br>` in an image's alt is a space, where it
+  was dropped. (#2071)
+
+
 ## v0.123.0 - 2026-10-06
 
 Upgrade path: [0.122 → 0.123](docs/migrations/0.122-to-0.123.md).

package/README.md

@@ -190,9 +190,9 @@ const doc = Document.storageVersionOf(content)
   : Document.fromMarkdown(content);
 ```
 
-The `schema` value (`quillmark/document@0.116.0`) is the **model version**,
+The `schema` value (`quillmark/document@0.124.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.116.x` patch release reads
+the `Document` model itself changes, so every `0.124.x` patch release reads
 and writes that same value.
 
 - **Upgrading is safe.** A newer build reads documents an older build's
@@ -332,7 +332,7 @@ the per-call `_commit*` ABI):
 const ed = quill.writer(doc);                       // Rust `quill.writer(doc)` twin; new DocumentWriter(quill, doc) also works
 ed.set("subject", "Q3 results");                    // strict-committed to the schema type
 ed.setAll({ qty: "3", subject: "Q3" });             // all-or-nothing batch
-ed.reviseField("subject", "Q3 **results**");        // typed AND anchor-preserving; returns a Delta
+ed.reviseField("subject", "Q3 **results**");        // typed AND anchor-preserving; returns { delta, warnings }
 ed.set("titel", "x");                               // throws UnknownField: a typo, not a fallback
 ed.card(2).set("body", "**note**");                 // composable card, resolved by its $kind
 ```
@@ -393,11 +393,12 @@ A document that compiles to zero pages still produces a valid session
 `pageCount === 0` to render a "no pages to preview" UI rather than relying on
 the throw.
 
-Their `warnings` differ in reach. `engine.render` returns one list for the
-whole pipeline: `doc.warnings` (parse and `conform::*`), then every
-`quill.validate(doc)` warning, then the compile's own. A session outlives
-the document it opened from, so `session.render` and `session.warnings` carry
-the compile's alone — read `doc.warnings` and `quill.validate(doc)` beside them.
+Their `warnings` differ in reach. `engine.render` returns every
+`quill.validate(doc)` warning but `validation::declined_construct`, which the
+compile raises as `backend::declined_construct`, then the compile's own;
+`session.render` and `session.warnings` carry the compile's alone, so read
+`quill.validate(doc)` beside them. Neither carries the load's: those stay on
+`doc.warnings`, and a revise's on its receipt.
 
 ### Canvas Preview
 
@@ -505,8 +506,12 @@ same shape applies to every throw site:
 - An object argument carrying a key its verb does not read: the render
   options, `new Engine` options, an `Addr`, a `CardInput`. Every own string
   key counts, a non-enumerable one and one holding `undefined` included. The
-  argument must be a plain object, its prototype `null` or `Object.prototype`
-  of any realm, so a `Map`, a class instance or `Object.create({ … })` throws.
+  argument must be a plain object, its prototype `null`, `Object.prototype`
+  of any realm, or a null-prototype object whose keys count too, so a `Map`, a
+  class instance or `Object.create({ … })` throws. A payload item, the fields
+  object `storeFields` takes, and a `$ext` or `$seed` value read their own
+  enumerable keys alone: a non-enumerable or inherited key there is neither
+  read nor refused.
   The diagnostic names the key or what was passed, and carries no `code`: it
   is a call site to fix, not a condition to route on.
 - `engine.render(quill, parsed)` against a quill whose *name* differs

package/core/wasm.d.ts

@@ -105,10 +105,17 @@ export type ContentLineKind =
 export type ContentContainer =
 | {
     container: "list_item";
-    attrs: { ordered: boolean; start: number; ordinal: number };
+    /** `checked` is present on a task item: `true` ticked, `false` open. */
+    attrs: { ordered: boolean; start: number; ordinal: number; checked?: boolean };
     instance?: number;
 }
-| { container: "quote"; instance?: number };
+| { container: "quote"; instance?: number }
+| { container: "element"; attrs: ElementAttrs; instance?: number };
+
+/** A carrier element's name and attributes, one bag: `$name` is the part of
+ * its `qm-<name>` tag after the prefix, and every other key an attribute as
+ * written. */
+export type ElementAttrs = { $name: string; [attr: string]: string };
 
 /** A mark over char range `[start, end)` into `Content.text`. `type` is a
  * closed set, so `type === "link"` narrows `attrs` to `{ url: string }` with no
@@ -127,24 +134,37 @@ export type ContentMarkKind =
 
 /** A cell in a `TableProps`. `marks` rides the prose `ContentMark` shape, but
  * each mark's `start`/`end` are USV offsets into this cell's `text`, not into
- * `Content.text`. */
+ * `Content.text`. A `\n` in `text` is a line break. */
 export interface TableCell {
     text: string;
     marks: ContentMark[];
+    /** The cell's horizontal alignment; absent is its column's. */
+    align?: "left" | "center" | "right";
+    /** The cell's vertical alignment; absent is the quill's. */
+    valign?: "top" | "middle" | "bottom";
 }
 
 /** `props` of a `type: "table"` island: a pipe table normalized to one column
- * count that `header`, every row of `rows`, and `aligns` all share. */
+ * count that `header`, every row of `rows`, `aligns` and `widths` all share.
+ * A layout key at its default is absent. */
 export interface TableProps {
     header: TableCell[];
     rows: TableCell[][];
     /** Per-column alignment, one entry per column. */
     aligns: ("none" | "left" | "center" | "right")[];
+    /** Per-column relative weights; `null` is an auto-fit column. Absent when
+     * every column is auto-fit. A weight is an integer from 1 to
+     * `Number.MAX_SAFE_INTEGER`; any other entry drops the key. */
+    widths?: (number | null)[];
+    /** The table's placement; absent is the quill's. */
+    align?: "left" | "center" | "right";
+    /** `true` draws `header` as the first body row; absent is a header row. */
+    headless?: true;
 }
 
 /** `props` of a `type: "image"` island. Stores and round-trips; no backend
  * typesets one, and a render that holds one warns `backend::declined_construct`,
- * because what `url` names is undecided. */
+ * because no backend resolves `url`. */
 export interface ImageProps {
     url: string;
     alt: string;
@@ -205,6 +225,51 @@ export interface Delta {
     ops: ({ retain: number } | { insert: string } | { delete: number })[];
 }
 
+/**
+ * The receipt of a markdown revise (`revise`, `writer.reviseBody`,
+ * `writer.reviseField`): the text `delta`, and one `parse::dropped_construct`
+ * warning per construct the import dropped, anchored at the revised address.
+ */
+export interface Revised {
+    delta: Delta;
+    warnings: Diagnostic[];
+}
+
+/**
+ * The receipt of `writer.reviseDocument`. `droppedAnchors` names every prose
+ * anchor the write did not carry, at its path in the stored document; a table
+ * cell's anchors drop unnamed. `warnings` are the parse's, then each revised
+ * content field's `parse::dropped_construct`, then the writer's `conform::*`.
+ * A field that lands rather than revises, on an inserted card or over no stored
+ * content, reports no drop.
+ */
+export interface DocumentRevised {
+    droppedAnchors: { path: string; id: string }[];
+    warnings: Diagnostic[];
+}
+
+/**
+ * The read `toAnnotatedMarkdown` returns: `toMarkdown`'s markdown with a
+ * read-only `<qm-anchor ref="…"></qm-anchor>` at each prose anchor's
+ * start its line can hold, and every prose anchor of every body and content
+ * field, spelled or not; a table cell's anchors are neither. Each names the
+ * `path` of its body or field and the text of the `line` its start sits on,
+ * island slots removed.
+ */
+export interface AnnotatedMarkdown {
+    markdown: string;
+    anchors: { id: string; path: string; line: string }[];
+}
+
+/**
+ * A markdown import (`importMarkdown`): the canonical `content`, and one
+ * `parse::dropped_construct` warning per construct it dropped, with no `path`.
+ */
+export interface Imported {
+    content: Content;
+    warnings: Diagnostic[];
+}
+
 /** Which side of a same-position insertion `mapPos` lands a point on. */
 export type Assoc = "before" | "after";
 
@@ -507,8 +572,8 @@ export interface Diagnostic {
     message: string;
     location?: Location;
     /**
-     * Document-model path anchor (e.g. `"cards.indorsement[0].signature_block"`),
-     * set on schema validation diagnostics and `undefined` otherwise.
+     * Document-model path anchor (e.g. `"cards.indorsement[0].signature_block"`)
+     * where the diagnostic has a document address, `undefined` otherwise.
      */
     path?: string;
     hint?: string;
@@ -708,15 +773,17 @@ export class Document {
     /**
      * **Revise** the richtext value at `addr` from a markdown string: the
      * default write path. Imports the markdown, diffs it against the current
-     * value, rebases surviving identity anchors, and returns the text `Delta` an
-     * editor bridge maps its own positions through (`mapPos`). An absent
-     * `addr.field` targets the body, an absent `addr.card` the main card; an
-     * absent field cold-imports from empty.
+     * value, rebases surviving identity anchors, and returns the `Revised`
+     * receipt: the text `delta` an editor bridge maps its own positions through
+     * (`mapPos`), and a `parse::dropped_construct` warning per construct the
+     * import dropped, its `path` the address written. An absent `addr.field`
+     * targets the body, an absent `addr.card` the main card; an absent field
+     * cold-imports from empty.
      *
      * Throws on an out-of-range card, a malformed field name, a present
      * non-content field value, or an over-nested markdown input.
      */
-    revise(addr: Addr | string, markdown: string): Delta;
+    revise(addr: Addr | string, markdown: string): Revised;
     /**
      * The main card's `$seed[kind]` overlay object, or `undefined`. Feeds
      * `quill.seedCard(kind, overlay)` without serializing the whole main card,
@@ -769,8 +836,18 @@ export class Document {
      */
     storeSeedOverlay(card_kind: string, overlay: any): void;
     /**
-     * Emit canonical Quillmark Markdown. Round-trip safe: re-parsing the
-     * result produces a `Document` equal to `self` by value and by type.
+     * `toMarkdown` with each prose anchor of every body and content field
+     * spelled read-only at its start where its line can hold the tag, and
+     * listed with its field's path and line either way. An import drops every
+     * tag, so `writer.reviseDocument` with the markdown keeps the anchors it keeps
+     * with `toMarkdown`'s.
+     */
+    toAnnotatedMarkdown(): AnnotatedMarkdown;
+    /**
+     * Emit canonical Quillmark Markdown. Re-parsing the result produces a
+     * `Document` equal to `self` by value and by type, but for content: a body
+     * or content field holds what its markdown spells, so its anchors drop and
+     * its island ids re-mint. `toStored` keeps both.
      */
     toMarkdown(): string;
     /**
@@ -794,7 +871,7 @@ export class Document {
      * The non-fatal diagnostics of the load that produced this document: parse
      * warnings, plus `conform::*` warnings when it came through `quill.parse`.
      * Session state, not document value: `equals` and the storage DTO exclude
-     * it, and `fromStored` / `loadStored` clear it.
+     * it, and `fromStored` / `loadStored` / `writer.reviseDocument` clear it.
      */
     readonly warnings: Diagnostic[];
 }
@@ -885,8 +962,8 @@ export class Quill {
      */
     toTree(): Map<string, Uint8Array>;
     /**
-     * Validate `doc` against this quill's schema, returning every diagnostic
-     * (empty when the document is valid). Forwards the canonical
+     * Validate `doc` against this quill's schema, returning every diagnostic:
+     * an error blocks a render, a warning does not. Forwards the canonical
      * `validation::*` diagnostics the engine emits.
      */
     validate(doc: Document): Diagnostic[];
@@ -936,18 +1013,20 @@ export function exportMarkdown(rt: Content): string;
 export function formatDiagnostic(diagnostic: Diagnostic): string;
 
 /**
- * Serialize structured [`DocPathSeg`] segments back to the canonical path
+ * Serialize structured `DocPathSeg` segments back to the canonical path
  * string: the inverse of `parseDocPath`. Throws on a segment array the
  * deserializer rejects, and on an empty one.
  */
 export function formatDocPath(segs: DocPathSeg[]): string;
 
 /**
- * Import a markdown string to canonical `Content`: the pure, document-free
- * codec. `overwrite(addr, importMarkdown(md))` spells the cold, anchor-losing
- * write; prefer `revise` for edit semantics. Throws on an over-nested input.
+ * Import a markdown string: the pure, document-free codec. Returns the
+ * canonical `content` and a `parse::dropped_construct` warning per construct
+ * the import dropped, with no `path`. `overwrite(addr, importMarkdown(md).content)`
+ * spells the cold, anchor-losing write; prefer `revise` for edit semantics.
+ * Throws on an over-nested input.
  */
-export function importMarkdown(markdown: string): Content;
+export function importMarkdown(markdown: string): Imported;
 
 /**
  * Whether `content` satisfies the `inline` constraint of `richtext` and
@@ -995,7 +1074,7 @@ export function mapPos(delta: Delta, pos: number, assoc: Assoc): number;
 
 /**
  * Parse a canonical document-model `Diagnostic.path` (`cards.<kind>[<i>].<field>`,
- * `main.body`, `recipients[0].name`) into structured [`DocPathSeg`] segments, so
+ * `main.body`, `recipients[0].name`) into structured `DocPathSeg` segments, so
  * a consumer routes on segments instead of regexing the string. Throws on a
  * malformed path.
  */
@@ -1003,11 +1082,12 @@ export function parseDocPath(path: string): DocPathSeg[];
 
 /**
  * Rebase `markdown` onto a `base` content: the document-free twin of `revise`,
- * returning the new `content` and the text `delta` (offsets are USV indices into
- * `Content.text`, surviving anchors rebased). Throws on an over-nested markdown
- * input or a non-content `base`.
+ * returning the new `content`, the text `delta` (offsets are USV indices into
+ * `Content.text`, surviving anchors rebased), and the import's
+ * `parse::dropped_construct` warnings, with no `path`. Throws on an
+ * over-nested markdown input or a non-content `base`.
  */
-export function rebase(base: Content, markdown: string): { content: Content; delta: Delta };
+export function rebase(base: Content, markdown: string): { content: Content; delta: Delta; warnings: Diagnostic[] };
 
 /**
  * Runs at instantiation, so a Rust panic reaches the console as a stack trace
@@ -1028,6 +1108,7 @@ export interface InitOutput {
     readonly document__readerGet: (a: number, b: number, c: number, d: number) => void;
     readonly document__readerGetContent: (a: number, b: number, c: number, d: number) => void;
     readonly document__readerGetContentAt: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly document__reviseDocument: (a: number, b: number, c: number, d: number, e: number) => void;
     readonly document__reviseField: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
     readonly document_applyChange: (a: number, b: number, c: number, d: number) => void;
     readonly document_bodyMarkdown: (a: number, b: number, c: number) => void;
@@ -1064,6 +1145,7 @@ export interface InitOutput {
     readonly document_storeField: (a: number, b: number, c: number, d: number) => void;
     readonly document_storeFields: (a: number, b: number, c: number, d: number) => void;
     readonly document_storeSeedOverlay: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly document_toAnnotatedMarkdown: (a: number, b: number) => void;
     readonly document_toMarkdown: (a: number, b: number) => void;
     readonly document_toStored: (a: number, b: number) => void;
     readonly document_warnings: (a: number, b: number) => void;