@quillmark/wasm 0.97.0 → 0.99.0

package/backends/typst/wasm.d.ts

@@ -44,7 +44,7 @@ export interface Card {
     seed?: Record<string, unknown>;
     payloadItems: PayloadItem[];
     /**
-     * The card body as canonical `Content` — the source-of-truth content model.
+     * The card body as canonical `Content`: the source-of-truth content model.
      * Always this content shape on read, never a markdown string. For the markdown
      * projection call the codec `exportMarkdown(card.body)`. Write a body back
      * with `doc.install(addr, rt)` / `doc.revise(addr, md)`, or via `CardInput.body`.
@@ -53,10 +53,10 @@ export interface Card {
 }
 
 /**
- * A card written *into* a document — the input twin of `Card`, accepted by
+ * A card written *into* a document: the input twin of `Card`, accepted by
  * `Document.insertCard`. Like `Card` but `body` also
  * takes a markdown `string` (imported to the content, so a markdown / LLM writer
- * needn't build the `Content` shape), and every field but `kind` is optional —
+ * needn't build the `Content` shape), and every field but `kind` is optional:
  * an absent field defaults (no payload items, an empty body). Write one inline
  * (`{ kind, body }`) or build it with `Document.makeCard`.
  */
@@ -71,7 +71,7 @@ export interface CardInput {
 }
 
 /**
- * Canonical richtext content — the content model for a card body (and richtext
+ * Canonical richtext content: the content model for a card body (and richtext
  * fields). One text sequence over a single coordinate space (Unicode scalar
  * values): `text` plus line attributes, anchored `marks`, and embedded
  * `islands`. Every edit is a splice; markdown is a projection, not the model.
@@ -84,27 +84,38 @@ export interface Content {
     islands: ContentIsland[];
 }
 
-/** One `\n`-separated segment of `Content.text`, in order. */
+/** One `\n`-separated segment of `Content.text`, in order. `kind` is an open set
+ * (as on `ContentIsland` and `ContentMark`): a role this build does not know
+ * round-trips with opaque `attrs` and renders as a paragraph, so a document
+ * carrying a future block construct still opens. The open arm blocks discriminant
+ * narrowing, so read `level`/`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. */
     continues?: boolean;
-} & (
+} & ContentLineKind;
+
+/** A line's block role, declared once for `ContentLine` and the `setKind` op:
+ * a new role is one edit here, as for `ContentContainer`. */
+export type ContentLineKind =
 | { kind: "para" }
 | { kind: "heading"; level: number }
 | { kind: "code"; lang?: string }
 | { kind: "island" }
 | { kind: "rule" }
-);
+| { kind: string; attrs: unknown };
 
-/** An ancestor block a line nests inside, outermost first. */
+/** An ancestor block a line nests inside, outermost first. Open like
+ * `ContentLine.kind`: an unrecognized container round-trips with opaque `attrs`
+ * and renders transparently (its lines sit at the enclosing level). */
 export type ContentContainer =
 | { container: "list_item"; ordered: boolean; start: number; ordinal: number }
-| { container: "quote" };
+| { container: "quote" }
+| { container: string; attrs: unknown };
 
 /** A mark over char range `[start, end)` into `Content.text`. The open `type`
  * arm blocks discriminant narrowing (as on `ContentIsland`), so read a
- * payload-carrying arm behind its guard — `isLinkMark` (`url`) / `isAnchorMark`
+ * payload-carrying arm behind its guard: `isLinkMark` (`url`) / `isAnchorMark`
  * (`id`), from `@quillmark/wasm/runtime`; the bare arms carry no payload. 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
@@ -117,7 +128,7 @@ export type ContentMark = { start: number; end: number } & (
 | { type: string; attrs: unknown }
 );
 
-/** A cell in a `TableProps` — its plain `text` plus the `marks` over it. `marks`
+/** A cell in a `TableProps`: its plain `text` plus the `marks` over it. `marks`
  * rides the same wire shape as prose `ContentMark`, but each mark's `start`/`end`
  * are USV offsets into this cell's `text` (`0..text.length`), not into
  * `Content.text`. */
@@ -145,12 +156,16 @@ export interface ImageProps {
  * open set: the engine pins `props` as `TableProps` for `table` and `ImageProps`
  * for `image`; an island of any other type round-trips with opaque `props`. Like
  * `ContentMark`, the open `type` arm means a discriminant check does not itself
- * narrow `props` — read `props` as the matching shape behind the `isTableIsland` /
+ * narrow `props`: read `props` as the matching shape behind the `isTableIsland` /
  * `isImageIsland` guards (from `@quillmark/wasm/runtime`), which narrow it. */
+/** How faithfully the markdown projection can carry an island. Open like an
+ * island `type`: a class this build does not know round-trips verbatim, and
+ * reads as `unrepresentable`. */
+export type ContentLossClass = "lossless" | "degraded" | "unrepresentable" | (string & {});
+
 export type ContentIsland = {
     id: string;
-    /** How faithfully the markdown projection can carry this island. */
-    loss: "lossless" | "degraded" | "unrepresentable";
+    loss: ContentLossClass;
 } & (
 | { type: "table"; props: TableProps }
 | { type: "image"; props: ImageProps }
@@ -158,14 +173,14 @@ export type ContentIsland = {
 );
 
 /**
- * A write address — one navigation concept for the whole `Document` surface. An
+ * A write address: one navigation concept for the whole `Document` surface. An
  * absent `field` targets the card body; an absent `card` targets the main card.
  * `{}` is the main-card body; `{ card: 2 }` the body of the composable card at
  * index 2; `{ field: "intro" }` the main card's `intro` field; `{ card: 2,
  * field: "intro" }` a card field.
  *
  * On the `Addr`-taking verbs a **bare string** is shorthand for `{ field: name }`
- * — `doc.storeField("qty", 3)`, `doc.revise("intro", md)` — the one coercion
+ * (`doc.storeField("qty", 3)`, `doc.revise("intro", md)`) the one coercion
  * rule. A bare number is *not* an addr (`{ card: 2 }` is the self-documenting
  * spelling), so no third navigation idiom re-fragments the surface.
  */
@@ -175,7 +190,7 @@ export interface Addr {
 }
 
 /**
- * A card-only address — the axis the card-scoped verbs (`storeFields`,
+ * A card-only address: the axis the card-scoped verbs (`storeFields`,
  * `storeExt`, `getExt`, `commitFields`, …) take. An absent `card` targets the
  * main card. A present `field` throws: a card address takes only `card`, and a
  * would-be nested write is a bug the error names rather than silently ignores.
@@ -186,7 +201,7 @@ export interface CardAddr {
 
 /**
  * A text-splice change set over the USV content (CodeMirror `ChangeSet`
- * semantics) — plain, structured-clone-able data. Returned by `revise` and by
+ * semantics): plain, structured-clone-able data. Returned by `revise` and by
  * the `rebase` codec; map a stored position through it with `mapPos`.
  */
 export interface Delta {
@@ -200,7 +215,7 @@ export type Assoc = "before" | "after";
  * A mark edit in final-text coordinates (post-delta, post-line-op). `add` /
  * `remove` carry the `ContentMark` vocabulary (`{ type, … }`); `removeAnchor`
  * drops one identity anchor by id. An `add` of an `anchor` requires a non-empty
- * `id` not already live in the field — a collision or the empty id throws
+ * `id` not already live in the field: a collision or the empty id throws
  * (ids are caller-supplied and unique per `Content`; DOCUMENT_STORAGE
  * § Anchor-id identity).
  */
@@ -216,18 +231,14 @@ export type MarkOp =
 /**
  * A line/block edit. `split`/`join` splice `\n`; `setKind`/`setContainers`/
  * `setContinues` touch metadata. `setContinues` sets/clears a line's within-block
- * hard-break flag (`ContentLine.continues`) — the op-grained way to lower a
+ * hard-break flag (`ContentLine.continues`): the op-grained way to lower a
  * Shift+Enter hard break or a new code-fence interior line; `continues: true` on
  * line 0 is rejected (nothing precedes it to continue).
  */
 export type LineOp =
 | { op: "split"; at: number }
 | { op: "join"; line: number }
-| ({ op: "setKind"; line: number } & (
-| { kind: "para" | "island" | "rule" }
-| { kind: "heading"; level: number }
-| { kind: "code"; lang?: string }
-))
+| ({ op: "setKind"; line: number } & ContentLineKind)
 | { op: "setContainers"; line: number; containers: ContentContainer[] }
 | { op: "setContinues"; line: number; continues: boolean };
 
@@ -246,7 +257,7 @@ export interface ChangeBundle {
 
 /**
  * One segment of a parsed `Diagnostic.path` (see `parseDocPath`). The head
- * carries the document-model root — `main` (only before `body`), a `card`
+ * carries the document-model root: `main` (only before `body`), a `card`
  * (`kind: null` is the unknown-kind `cards[i]` form), or a `field`; the tail is
  * `field` / `index` / a terminal `body`.
  */
@@ -261,7 +272,7 @@ export type DocPathSeg =
 
 /**
  * Page dimensions in points (1 pt = 1/72 inch). Typst measures in Typst
- * points; pdfform measures in PDF points — the same unit.
+ * points; pdfform measures in PDF points: the same unit.
  *
  * Report-only: the painter sizes the canvas itself based on
  * `PaintOptions`. `pageSize` is exposed for callers that need page
@@ -277,16 +288,16 @@ export interface PageSize {
  * Inputs to `LiveSession.paint`. Both fields are optional and default
  * to `1`.
  *
- * - `layoutScale` — layout-space pixels per point (Typst point / PDF
- *   point — the same 1/72″ unit). For on-screen
+ * - `layoutScale` (layout-space pixels per point (Typst point / PDF
+ *   point) the same 1/72″ unit). For on-screen
  *   canvases this is CSS pixels per pt; the page's layout-pixel size is
  *   `widthPt * layoutScale × heightPt * layoutScale`. The painter
  *   surfaces these dimensions as `layoutWidth` / `layoutHeight` so
  *   consumers can drive `canvas.style.*` (or any layout system).
- * - `densityScale` — backing-store density multiplier. Fold
+ * - `densityScale`: backing-store density multiplier. Fold
  *   `window.devicePixelRatio`, in-app zoom, and `visualViewport.scale`
  *   (pinch-zoom) into a single value here. Defaults to `1`, which
- *   produces a non-retina backing store — pass `window.devicePixelRatio`
+ *   produces a non-retina backing store: pass `window.devicePixelRatio`
  *   for crisp output on high-DPI displays.
  *
  * The effective rasterization scale is `layoutScale * densityScale`.
@@ -302,22 +313,22 @@ export interface PaintOptions {
 /**
  * Returned by `LiveSession.paint`.
  *
- * - `layoutWidth` / `layoutHeight` — layout-pixel dimensions of the
+ * - `layoutWidth` / `layoutHeight`: layout-pixel dimensions of the
  *   canvas's display box. For on-screen canvases this is CSS pixels:
  *   set `canvas.style.width = layoutWidth + "px"` and
  *   `canvas.style.height = layoutHeight + "px"` (or feed these into
  *   your layout system). Independent of `densityScale`.
- * - `pixelWidth` / `pixelHeight` — integer backing-store pixel
+ * - `pixelWidth` / `pixelHeight`: integer backing-store pixel
  *   dimensions the painter wrote to `canvas.width` / `canvas.height`.
  *   Equal to `round(layoutWidth * densityScale)` ×
  *   `round(layoutHeight * densityScale)` *unless* the requested backing
  *   exceeded the painter's safe maximum (16384 px per side), in which
  *   case `densityScale` was clamped to fit.
- * - `clamped` — `true` when that 16384-px clamp fired, so the page is
+ * - `clamped`: `true` when that 16384-px clamp fired, so the page is
  *   painted at fewer device pixels than requested and renders soft at the
  *   same `canvas.style` size. Reads the clamp off the return value instead
  *   of the `pixelWidth < round(layoutWidth * densityScale)` derivation.
- * - `effectiveDensityScale` — the `densityScale` actually applied: the
+ * - `effectiveDensityScale`, the `densityScale` actually applied: the
  *   requested value unless `clamped`, then reduced proportionally.
  *   `layoutScale * effectiveDensityScale` is the scale the backing store
  *   was rasterized at.
@@ -326,11 +337,11 @@ export interface PaintOptions {
  * write to them. The painter does **not** touch `canvas.style.*`;
  * consumers own layout. The write is a whole-backing-store `putImageData`,
  * which bypasses the 2D context transform, `globalAlpha`, and clip: give
- * each visible page its own `` — you cannot composite two pages, a
+ * each visible page its own `<canvas>`; you cannot composite two pages, a
  * sub-rect, or a context transform through `paint`.
  *
  * For `OffscreenCanvasRenderingContext2D` (Worker rasterization, no
- * DOM), `layoutWidth` / `layoutHeight` are informational — there's no
+ * DOM), `layoutWidth` / `layoutHeight` are informational: there's no
  * CSS layout box to apply them to.
  */
 export interface PaintResult {
@@ -349,7 +360,7 @@ export type FieldSource = "authored" | "default" | "zero";
 
 /**
  * One resolved row: its `name`, the value the render projection would use, and
- * the `FieldSource` rung it came from. Rows are an ordered array — declaration
+ * the `FieldSource` rung it came from. Rows are an ordered array: declaration
  * order is structural, not object-key order. The card body is a `body` sibling
  * on its card, never a row in `fields`. Diagnostics stay `Quill.validate`'s;
  * schema guidance (`example:`, labels) reads from `Quill.schema`.
@@ -361,7 +372,7 @@ export interface ResolvedField {
 }
 
 /**
- * The main card's resolved rows in declaration order, plus its body row —
+ * The main card's resolved rows in declaration order, plus its body row:
  * `null` when the main enables no body.
  */
 export interface ResolvedMain {
@@ -372,7 +383,7 @@ export interface ResolvedMain {
 /**
  * One composable card's resolved rows in declaration order, with its authored
  * `kind` (`null` for an unknown-kind card), its document-array `index`, and its
- * body row — `null` when the kind enables no body.
+ * body row: `null` when the kind enables no body.
  */
 export interface ResolvedCard {
     kind: string | null;
@@ -383,7 +394,7 @@ export interface ResolvedCard {
 
 /**
  * The resolved-value view (`Quill.resolve`): the main card and every
- * composable card. Value and provenance only — completeness and errors stay
+ * composable card. Value and provenance only: completeness and errors stay
  * `Quill.validate`.
  */
 export interface Resolved {
@@ -404,7 +415,7 @@ export interface QuillFieldUi {
 }
 
 /** One entry in a card's `ui.groups` registry: a display-label override for the
- * group id (the map key). An empty object carries no override — the consumer
+ * group id (the map key). An empty object carries no override: the consumer
  * derives the label from the id (`memo_for` → "Memo For"), as it does a field
  * label from its key. */
 export interface QuillGroupUi {
@@ -416,7 +427,7 @@ export interface QuillCardUi {
     title?: string;
     /** The card's group registry: the ordered table of contents naming every
      * group a field's `ui.group` may reference. The map key is the group id, and
-     * key order is declaration order — the display-order contract, the same one
+     * key order is declaration order: the display-order contract, the same one
      * `fields` key order carries. Absent when the card declares no groups (or
      * uses the deprecated implicit-group form). */
     groups?: Record<string, QuillGroupUi>;
@@ -454,7 +465,7 @@ export interface QuillFieldSchema {
     properties?: Record<string, QuillFieldSchema>;
     items?: QuillFieldSchema;
     /** Present (and `true`) on a `richtext` or `plaintext` field declared
-     *  `inline` — the single-paragraph, container-free, island-free constraint.
+     *  `inline`: the single-paragraph, container-free, island-free constraint.
      *  Core serializes `inline: true` into the schema JSON; absent otherwise. */
     inline?: boolean;
 }
@@ -495,67 +506,205 @@ export interface QuillMetadata {
 }
 
 
-export interface Artifact {
-    format: OutputFormat;
-    bytes: Uint8Array;
-    mimeType: string;
-}
-
-export interface ChangeSet {
-    pageCount: number;
-    dirtyPages: number[];
+/**
+ * A rendered field region: the quill schema field address plus its geometry on
+ * the page. Emitted for schema-bound fields: span-tracked content (richtext
+ * bodies, `richtext[]` elements, card content fields, direct scalar
+ * references) and form-field widgets (pdfform AcroForm, Typst `form-field`).
+ * Consumers use it to scroll to / highlight the focused field; for the
+ * reverse click direction use `LiveSession.fieldAt`, which answers over any
+ * placement. Geometry only: the raster is already complete, so a region is
+ * never a compositing input.
+ *
+ * `field` is **not** unique: content fields surface one region **per segment**
+ * (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`: every entry
+ * routes to that field. The whole-field highlight is the **union of a page\'s
+ * `span`-bearing segment rects**, so inter-paragraph whitespace stays
+ * uncovered; `LiveSession.fieldBoxes(field)` owns that union so
+ * consumers need not derive it. Later placements of one content value are not
+ * enumerated; `fieldAt` / `positionAt` still resolve clicks on them.
+ */
+export interface FieldRegion {
+    /**
+     * Canonical `DocPath` field address (e.g. `\"signature_block\"`,
+     * `\"cards.indorsement[1].from\"`, `\"main.body\"`): the same grammar
+     * `parseDocPath` reads and `Diagnostic.path` carries. The session resolves
+     * the backend\'s plate-space per-kind ordinal to this absolute-index form,
+     * so one parser routes every address. Feed it back to `fieldBoxes` /
+     * `locate`; hit-test the click direction with `fieldAt` / `positionAt`.
+     */
+    field: string;
+    /**
+     * 0-based page index.
+     */
+    page: number;
+    /**
+     * `[x0, y0, x1, y1]` in PDF points (1/72″), bottom-left origin.
+     */
+    rect: [number, number, number, number];
+    /**
+     * The content slice this box covers: USV `[start, end)` into the field\'s
+     * `Content` for content ink (one segment), `undefined` for a scalar
+     * reference site or widget. Consumers key segment highlights on it;
+     * `fieldBoxes(field)` unions same-page segments for the whole-field box.
+     */
+    span?: [number, number];
 }
 
+/**
+ * A resolved point → content position: the field a click landed in and the USV
+ * offset into its `Content`. The `LiveSession.positionAt` result, paired with
+ * `locate` (content position → caret rect). `pos` is cluster-exact and degrades
+ * to the containing segment\'s start on origin-less ink; `granularity` reports
+ * which happened so a caret UI need not guess.
+ */
 export interface ContentHit {
+    /**
+     * Canonical `DocPath` field address (same grammar as `FieldRegion.field`).
+     */
     field: string;
+    /**
+     * USV offset into the field\'s `Content`.
+     */
     pos: number;
+    /**
+     * Whether `pos` is cluster-exact or floored to the segment start
+     * (`HitGranularity`). `undefined` when the backend does not report it.
+     * Additive-optional.
+     */
     granularity?: HitGranularity;
 }
 
+/**
+ * Diagnostic message (error or warning)
+ */
 export interface Diagnostic {
     severity: Severity;
     code?: string;
     message: string;
     location?: Location;
+    /**
+     * Document-model path anchor (e.g. `\"cards.indorsement[0].signature_block\"`).
+     *
+     * Set on schema validation diagnostics; `undefined` otherwise. See the
+     * Rust `quillmark_core::error` module docs for the path grammar.
+     */
     path?: string;
     hint?: string;
     sourceChain?: string[];
 }
 
-export interface FieldRegion {
-    field: string;
-    page: number;
-    rect: [number, number, number, number];
-    span?: [number, number];
-}
-
-export interface Location {
-    file: string;
-    line: number;
-    column: number;
-}
+/**
+ * How precisely a `ContentHit.pos` resolved: the marker a caret UI reads to
+ * decide whether to trust the offset. Never sub-cluster: `cluster` is the
+ * finest this API offers, `segment` the floor it degrades to on origin-less
+ * ink.
+ */
+export type HitGranularity = "cluster" | "segment";
 
+/**
+ * Options for rendering.
+ */
 export interface RenderOptions {
     format?: OutputFormat;
+    /**
+     * Pixels per inch for raster output formats (PNG).
+     * Ignored for vector/document formats (PDF, SVG).
+     * Defaults to 144.0 (2x at 72pt/inch) when omitted.
+     */
     ppi?: number;
+    /**
+     * Optional 0-based page indices to render (e.g., `[0, 2]` for the
+     * first and third pages). `undefined` renders all pages. Any index
+     * `>= pageCount` throws with the `typst::page_index_out_of_bounds`
+     * code: read `LiveSession.pageCount` first if validation is needed.
+     * **Not supported for PDF output**: passing `pages` with
+     * `format: \"pdf\"` throws with the
+     * `typst::pdf_page_selection_not_supported` code.
+     */
     pages?: number[];
+    /**
+     * Override for the PDF `/Info` `/Producer` metadata string. Omit to use
+     * the default (`Quillmark <version>`). Applies to PDF output only.
+     */
     producer?: string;
+    /**
+     * Populate `RenderResult.regions` with the schema-field geometry sidecar
+     * (the same entries `LiveSession.regions()` serves), for consumers
+     * without a live session; e.g. overlays over a one-shot SVG export.
+     * Defaults to `false`: exports pay no introspection cost. The sidecar
+     * always describes the whole document: page indices are document-space
+     * even when `pages` selects a subset.
+     */
     regions?: boolean;
 }
 
+/**
+ * Output formats supported by backends.
+ *
+ * Gated behind the engine surface (`typst` or `pdfform`) so tsify omits
+ * its `.d.ts` interface from the core bundle (`pkg/core/wasm.d.ts`), which
+ * has no rendering surface.
+ */
+export type OutputFormat = "pdf" | "svg" | "png";
+
+/**
+ * Rendered artifact (PDF, SVG, etc.).
+ */
+export interface Artifact {
+    format: OutputFormat;
+    /**
+     * Serialized via `serde_bytes` so `serde_wasm_bindgen` emits a real
+     * `Uint8Array` at the boundary instead of a `number[]`. Without this
+     * annotation, the declared `Uint8Array` type would silently lie.
+     */
+    bytes: Uint8Array;
+    mimeType: string;
+}
+
+/**
+ * Result of a render operation.
+ */
 export interface RenderResult {
     artifacts: Artifact[];
     warnings: Diagnostic[];
     outputFormat: OutputFormat;
     renderTimeMs: number;
+    /**
+     * Schema-field geometry sidecar: populated only when
+     * `RenderOptions.regions` requested it; empty otherwise. The same entries
+     * `LiveSession.regions()` serves, for consumers without a live session.
+     * Page indices are document-space even under a `pages` subset render.
+     */
     regions: FieldRegion[];
 }
 
-export type HitGranularity = "cluster" | "segment";
+/**
+ * Severity levels for diagnostics
+ */
+export type Severity = "error" | "warning";
 
-export type OutputFormat = "pdf" | "svg" | "txt" | "png";
+/**
+ * Source location for errors and warnings
+ */
+export interface Location {
+    file: string;
+    line: number;
+    column: number;
+}
 
-export type Severity = "error" | "warning";
+/**
+ * What a committed `LiveSession.apply` changed. `dirtyPages` lists the pages
+ * whose rendered content differs from the previous compile, including pages
+ * the edit added; removed pages are implied by `pageCount`. A preview
+ * repaints `dirty ∩ visible` and nothing else.
+ */
+export interface ChangeSet {
+    pageCount: number;
+    dirtyPages: number[];
+}
 
 
 /**
@@ -566,7 +715,7 @@ export class Document {
     [Symbol.dispose](): void;
     /**
      * **Apply** a committed content edit `bundle` (`{ delta?, lineOps?, markOps? }`)
-     * at `addr` — the editor splice: text delta first, then line ops, then mark
+     * at `addr`, the editor splice: text delta first, then line ops, then mark
      * ops (mark ranges in final-text coordinates), each all-or-nothing. An absent
      * `addr.field` targets the body, an absent `addr.card` the main card.
      *
@@ -583,7 +732,7 @@ export class Document {
      */
     static blueprintInstruction(quill_name: string): string;
     /**
-     * A single composable card by index — the whole `Card`, the card-indexed
+     * A single composable card by index: the whole `Card`, the card-indexed
      * twin of the [`main`](Self::main) getter, so reading one card need not
      * materialize every card via [`cards`](Self::cards). An out-of-range
      * `index` throws `edit::index_out_of_range`, matching the card write
@@ -638,54 +787,54 @@ export class Document {
     static fromMarkdown(markdown: string): Document;
     /**
      * The whole `$ext` map at `addr` (a card address, absent `card` = main), or
-     * `undefined` when the card carries none. The fine-grained `$ext` read —
+     * `undefined` when the card carries none. The fine-grained `$ext` read:
      * your own state without serializing the whole card. Throws on a present
      * `field` (a card address takes only `card`) or an out-of-range card.
      */
     getExt(addr?: CardAddr): Record<string, unknown> | undefined;
     /**
      * The value stored under `$ext[ns]` at `addr` (a card address, absent `card`
-     * = main), or `undefined`. The namespace-scoped `$ext` read — your own slot
+     * = main), or `undefined`. The namespace-scoped `$ext` read: your own slot
      * without a whole-card serialize, and non-destructive (unlike
      * `removeExtNamespace`). Throws on a present `field` or an out-of-range card.
      */
     getExtNamespace(addr: CardAddr, ns: string): unknown;
     /**
-     * The **body** markdown projection — the main body, or a composable card's
-     * body (`{ card }`) — the on-demand, lossy export (content-only marks do not
+     * The **body** markdown projection (the main body, or a composable card's
+     * body (`{ card }`)) the on-demand, lossy export (content-only marks do not
      * survive markdown). A body's type is a format fact, not a schema fact, so
      * this read stays quill-free; a body is never absent.
      *
      * `addr` is an optional **card address** (`{ card }`, absent = main). A
-     * present `field` throws — a field's markdown is read through the
+     * present `field` throws: a field's markdown is read through the
      * schema-plane `quill.reader(doc).get(field)`, which interprets by declared
-     * type (#978). An out-of-range `addr.card` throws.
+     * type. An out-of-range `addr.card` throws.
      */
     getMarkdown(addr?: CardAddr): string;
     /**
-     * Read the **verbatim stored value** at `addr` — the raw payload value of a
+     * Read the **verbatim stored value** at `addr`: the raw payload value of a
      * field (a content object for a richtext field, a scalar/array/object
      * otherwise), or the **body content** when `addr.field` is absent. A bare
      * string is `Addr` shorthand for `{ field }`. Reads are total over the field
      * axis: an absent field is `undefined`; only an out-of-range `addr.card`
      * throws `edit::index_out_of_range`. Needs no schema, so it lives on
-     * `Document` — the read echo of the verbatim `store*` write, distinct from
+     * `Document`: the read echo of the verbatim `store*` write, distinct from
      * the interpreted schema-plane [`reader.get`](Self::reader_get). For the
      * markdown projection use [`getMarkdown`](Self::get_markdown) (body) or
      * `reader.get` (a field's declared type).
      */
     getStored(addr: Addr | string): unknown;
     /**
-     * Insert a card — the single insertion verb: `at` absent appends, a number
+     * Insert a card, the single insertion verb: `at` absent appends, a number
      * inserts at that index (must be in `0..=cards.length`). Accepts a
-     * `CardInput` — a card read back (`cards` / `removeCard` / `quill.seedCard`),
+     * `CardInput`: a card read back (`cards` / `removeCard` / `quill.seedCard`),
      * a [`makeCard`](Document::make_card) result, or a bare `{ kind, body }`
      * (every returned `Card` is a valid `CardInput`). Throws if `card.kind` is
      * not a valid kind name, or if `at` is out of range.
      */
     insertCard(card: CardInput, at?: number): void;
     /**
-     * **Install** a richtext value at `addr` — **value semantics**, content only.
+     * **Install** a richtext value at `addr`: **value semantics**, content only.
      * Stores exactly `rt` (a canonical `Content` content object); the identity
      * anchors of any previous value are gone. An absent `addr.field` targets the
      * body, an absent `addr.card` the main card. For "here's new markdown," use
@@ -699,29 +848,37 @@ export class Document {
     install(addr: Addr | string, rt: Content): void;
     /**
      * Whether the field at `addr` is marked `!must_fill`. A bare string is `Addr`
-     * shorthand for `{ field }`. `false` for an absent field (truthful — it isn't
+     * shorthand for `{ field }`. `false` for an absent field (truthful: it isn't
      * marked) and for a body address (a body is never a fill). Only an
      * out-of-range `addr.card` throws.
      */
     isFill(addr: Addr | string): boolean;
     /**
      * Replace this document's contents **in place** from a versioned storage
-     * DTO string — the mutating twin of the static
+     * DTO string: the mutating twin of the static
      * [`fromJson`](Document::from_json) constructor. Parse-time `warnings` are
      * cleared. Throws (leaving the document unchanged) on an invalid DTO.
      *
      * The cross-WASM-memory `Document` bridge: mutate a document on a
      * backend-memory clone, then write the mutated state back into the caller's
-     * canonical document with this — the one way to update a live handle across
+     * canonical document with this, the one way to update a live handle across
      * the linear-memory seam without the caller re-binding its variable.
      */
     loadJson(json: string): void;
     /**
-     * Build a fresh `Card` from a kind and a flat field map — the ergonomic
+     * Build a fresh `Card` from a kind and a flat field map: the ergonomic
      * constructor for `insertCard`. `fields` is an optional
      * `Record<string, unknown>` (each entry becomes a card field, in
-     * insertion order); `body` defaults to `""`. Kind validity is checked by
-     * `insertCard`, not here.
+     * insertion order); `body` defaults to `""`.
+     *
+     * Sugar, not a required step: `insertCard` takes any `Card` object, and
+     * `removeCard` returns one, so a card round-trips without passing through
+     * here.
+     *
+     * Checks only what a detached card can decide alone: field-name grammar
+     * and value depth. Kind validity is positional (`main` is right for the
+     * root, reserved for a composable card) so `insertCard` is its gate, and
+     * any kind string is accepted here.
      */
     static makeCard(kind: string, fields?: Record<string, unknown>, body?: string): Card;
     /**
@@ -729,7 +886,7 @@ export class Document {
      */
     moveCard(from: number, to: number): void;
     /**
-     * `new Document(quillRef)` — a blank document: a main card carrying only
+     * `new Document(quillRef)`, a blank document: a main card carrying only
      * `$quill`, an empty body, and no composable cards. The programmatic
      * blank canvas: absent fields resolve at render time (`default`, else
      * type-empty zero), so nothing the caller did not set reaches the
@@ -740,7 +897,7 @@ export class Document {
     /**
      * The canonical `$quill` reference grammar as author-facing text. Core is
      * the single source of truth: drive schema `describe` and validation
-     * messages from this instead of re-stating the rule — it matches the
+     * messages from this instead of re-stating the rule; it matches the
      * `hint` on `parse::invalid_quill_reference`. Cache it; the value never
      * changes.
      */
@@ -748,7 +905,7 @@ export class Document {
     removeCard(index: number): Card | undefined;
     /**
      * Remove the `$ext` map on the card `addr` targets *entirely*, returning the
-     * previous map or `undefined` — a blunt escape hatch that discards every
+     * previous map or `undefined`: a blunt escape hatch that discards every
      * namespace at once (prefer `removeExtNamespace`). `addr` is a card address
      * (absent = main). Throws on a present `field` or an out-of-range card.
      */
@@ -774,7 +931,7 @@ export class Document {
      */
     removeSeedNamespace(card_kind: string): any;
     /**
-     * **Revise** the richtext value at `addr` from a markdown string — **edit
+     * **Revise** the richtext value at `addr` from a markdown string: **edit
      * semantics**, the default write path, returning the text `Delta`. Imports
      * the markdown, diffs it against the current value, rebases surviving
      * identity anchors, and returns the change an editor bridge maps its own
@@ -787,7 +944,7 @@ export class Document {
     revise(addr: Addr | string, markdown: string): Delta;
     /**
      * Read the `schema` version tag from a raw storage DTO string without a
-     * full parse, or `undefined`. Returns unknown future versions as-is —
+     * full parse, or `undefined`. Returns unknown future versions as-is:
      * useful to distinguish "build too old" from "payload corrupt" when
      * `fromJson` throws.
      */
@@ -796,7 +953,7 @@ export class Document {
      * The main card's `$seed` overlay object for `kind` (the `$seed[kind]`
      * entry), or `undefined` when absent. The cheap read that feeds
      * `quill.seedCard(kind, overlay)` without serializing the whole main card
-     * via [`main`](Self::main) to fish out one key — and it keeps `seedCard`
+     * via [`main`](Self::main) to fish out one key, and it keeps `seedCard`
      * pure: the quill still never reads the document.
      */
     seedOverlay(kind: string): Record<string, unknown> | undefined;
@@ -814,41 +971,41 @@ export class Document {
      * Replace the opaque `$ext` map on the card `addr` targets (a card address,
      * absent `card` = main). `value` must be a plain object. `$ext` carries
      * out-of-band consumer state and never reaches the rendered output; pass
-     * `{}` for an explicit empty `$ext`. Quill-free and verbatim — an opaque
+     * `{}` for an explicit empty `$ext`. Quill-free and verbatim: an opaque
      * `store` verb. Throws on a present `field` or an out-of-range card.
      */
     storeExt(addr: CardAddr, value: any): void;
     /**
      * Merge `value` into `$ext[ns]` on the card `addr` targets, preserving
-     * sibling namespaces — the recommended `$ext` write. `addr` is a card
-     * address (absent = main). Quill-free and verbatim — an opaque `store` verb.
+     * sibling namespaces: the recommended `$ext` write. `addr` is a card
+     * address (absent = main). Quill-free and verbatim: an opaque `store` verb.
      * Throws on a present `field` or an out-of-range card.
      */
     storeExtNamespace(addr: CardAddr, ns: string, value: any): void;
     /**
-     * Store a field verbatim at `addr` — the opaque store (**store** = verbatim,
+     * Store a field verbatim at `addr`: the opaque store (**store** = verbatim,
      * coercion deferred to render; the typed write is
      * [`commitField`](Document::commit_field)). A bare string is `Addr`
      * shorthand for `{ field }`, so `doc.storeField("qty", 3)` reads as written;
      * `{ card: 2, field: "qty" }` targets a composable card. Clears any
-     * `!must_fill` marker. A body address (no `field`) throws — a body is never
+     * `!must_fill` marker. A body address (no `field`) throws: a body is never
      * opaque; write it with `revise` / `install` / `writer.setBody`. Throws on
      * an out-of-range card or a malformed name.
      */
     storeField(addr: Addr | string, value: any): void;
     /**
-     * Store several fields verbatim and atomically on the card `addr` targets —
+     * Store several fields verbatim and atomically on the card `addr` targets:
      * the opaque store's batch. `addr` is a **card address** (`{ card }`, absent
      * = main); a present `field` throws. The batch verb takes the address first
      * and is never shape-overloaded, because `card` is a legal field name:
      * `storeFields({}, fields)` is the main card, `storeFields({ card: 2 },
-     * fields)` a composable one — never ambiguous with "set field `card`".
+     * fields)` a composable one, never ambiguous with "set field `card`".
      * Nothing is applied on error; the thrown error's `diagnostics` carry one
      * entry per offending field. Throws on an out-of-range card.
      */
     storeFields(addr: CardAddr, fields: Record<string, unknown>): void;
     /**
-     * Store a field verbatim at `addr` and mark it `!must_fill` — the opaque
+     * Store a field verbatim at `addr` and mark it `!must_fill`: the opaque
      * store's fill variant, card-capable (a bare string or `{ field }` for main,
      * `{ card, field }` for a composable card). A body address throws. Same
      * validation as [`storeField`](Document::store_field).
@@ -856,9 +1013,9 @@ export class Document {
     storeFill(addr: Addr | string, value: any): void;
     /**
      * Merge a card-kind's seed `overlay` into the **main** card's `$seed` map
-     * under `cardKind`, preserving sibling kinds — `$seed` lives on the main
+     * under `cardKind`, preserving sibling kinds: `$seed` lives on the main
      * card by model, so this takes no address. Sets the starting values new
-     * cards of that kind spawn with. Quill-free and verbatim — an opaque `store`
+     * cards of that kind spawn with. Quill-free and verbatim: an opaque `store`
      * verb. Throws if `overlay` cannot be serialized or nests too deep.
      */
     storeSeedNamespace(card_kind: string, overlay: any): void;
@@ -866,7 +1023,7 @@ export class Document {
      * Serialize this document to a versioned storage DTO string.
      *
      * Prefer this over `toMarkdown` for persistence across restarts or crate
-     * upgrades — the wire format is frozen per `schema` version. Parse-time
+     * upgrades: the wire format is frozen per `schema` version. Parse-time
      * `warnings` are excluded from the DTO.
      *
      * Output is **byte-deterministic** within a `schema` version: equal
@@ -880,7 +1037,7 @@ export class Document {
     toMarkdown(): string;
     /**
      * Like [`fromJson`](Document::from_json) but returns `undefined` instead
-     * of throwing when `json` is not a valid storage DTO — use to
+     * of throwing when `json` is not a valid storage DTO: use to
      * discriminate format without exceptions as control flow.
      * `undefined` means "not a storage DTO"; `fromMarkdown` still throws on
      * genuinely malformed markdown.
@@ -893,7 +1050,7 @@ export class Document {
     readonly cards: Card[];
     /**
      * The document's main (entry) card. Allocates and serializes on each
-     * call — cache locally if read in a hot loop.
+     * call: cache locally if read in a hot loop.
      */
     readonly main: Card;
     readonly quillRef: string;
@@ -905,7 +1062,7 @@ export class Document {
  * `fieldAt`, `positionAt`, `locate`) serve the current compile. `apply(doc)`
  * recompiles a whole document in place, transactionally (on throw every read
  * keeps serving the last-good compile). Geometry reads reflect the current
- * compile; anchoring a caret across edits is the editor's job — re-read
+ * compile; anchoring a caret across edits is the editor's job: re-read
  * geometry after each committed `apply`.
  *
  * **Empty documents.** A zero-page document yields a valid session
@@ -918,7 +1075,7 @@ export class LiveSession {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Recompile the session against `doc` — the edit verb of a live preview.
+     * Recompile the session against `doc`: the edit verb of a live preview.
      * The document is compiled through the same schema pipeline as `open`
      * (same quill), then applied transactionally: on throw every read
      * (`render`, `paint`, `pageSize`, `regions`, `fieldAt`) keeps serving the last-good
@@ -927,11 +1084,11 @@ export class LiveSession {
      */
     apply(doc: Document): ChangeSet;
     /**
-     * The schema field whose content is under a point on `page` — the
+     * The schema field whose content is under a point on `page`, the
      * forward (click → field) direction: hit-test a click against the
      * compiled document and get back the `DocPath` field address to focus in
      * the editor, or `undefined` off any field's ink. `x`/`y` are PDF points
-     * with a **bottom-left** origin, the same space as `FieldRegion.rect` —
+     * with a **bottom-left** origin, the same space as `FieldRegion.rect`,
      * from a canvas click, invert the overlay transform documented on
      * `FieldRegion`: `x = clickPx.x / renderScale`,
      * `y = pageHeightPt - clickPx.y / renderScale`. Unlike `regions()`,
@@ -939,19 +1096,19 @@ export class LiveSession {
      */
     fieldAt(page: number, x: number, y: number): string | undefined;
     /**
-     * The whole-field highlight boxes for `field` — one union rect per page,
+     * The whole-field highlight boxes for `field`: one union rect per page,
      * over the field's `span`-bearing content segments. The convenience that
      * owns the union `regions()` leaves derived: it keeps `regions()` the
-     * low-level disjoint truth (#829) and folds the span-filter + per-page
+     * low-level disjoint truth and folds the span-filter + per-page
      * union here, so a "highlight the focused field" consumer stops
-     * reimplementing it. **Content only** — a field placed solely as a scalar
+     * reimplementing it. **Content only**: a field placed solely as a scalar
      * reference or a bound widget carries no `span` and returns `[]`; its box
      * is a single `regions()` rect. Reflects the current compile, like
      * `regions()`.
      */
     fieldBoxes(field: string): FieldRegion[];
     /**
-     * A content position → **caret rect** — the reverse of `positionAt`: given
+     * A content position → **caret rect**, the reverse of `positionAt`: given
      * a field and a USV offset into its `Content`, return the box (in the
      * same bottom-left PDF-point space as `FieldRegion.rect`) to draw a caret
      * at, its `span` collapsed to `[pos, pos]`; `undefined` when the field
@@ -968,12 +1125,12 @@ export class LiveSession {
      * `OffscreenCanvasRenderingContext2D`. The painter owns
      * `canvas.width`/`height` (no `clearRect` needed); consumers own
      * `canvas.style.*`. If `layoutScale * densityScale` exceeds 16384 px
-     * per side, `densityScale` is clamped — `PaintResult.clamped` reports it and
+     * per side, `densityScale` is clamped: `PaintResult.clamped` reports it and
      * `PaintResult.effectiveDensityScale` carries the density actually applied.
      *
      * `put_image_data` writes the whole backing store, bypassing the 2D
      * context's transform, `globalAlpha`, and clip: the painter owns the entire
-     * canvas, so each visible page needs its own `` — you cannot composite
+     * canvas, so each visible page needs its own `<canvas>`; you cannot composite
      * two pages, a sub-rect, or a context transform through this call.
      *
      * Throws if the backend has no canvas painter, `page` is out of range,
@@ -981,18 +1138,18 @@ export class LiveSession {
      */
     paint(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, page: number, opts: PaintOptions | undefined): PaintResult;
     /**
-     * A point → **content position** — the fine-grained click direction:
+     * A point → **content position**, the fine-grained click direction:
      * hit-test a point and get back 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 — the same space as `fieldAt`. The offset is
+     * bottom-left origin: the same space as `fieldAt`. The offset is
      * cluster-exact and degrades to the containing segment's start on
      * origin-less ink (list markers, a code fence's interior). See
      * `ContentHit`.
      */
     positionAt(page: number, x: number, y: number): ContentHit | undefined;
     /**
-     * Schema-field geometry for this compiled session — each content field's
+     * Schema-field geometry for this compiled session: each content field's
      * **first placement** (one region per page it touches) plus widget and
      * scalar-reference-site regions, keyed on the canonical `DocPath` address
      * (`parseDocPath`-routable; the session resolves the backend's plate-space
@@ -1012,12 +1169,12 @@ export class LiveSession {
     /**
      * `true` iff `paint` and `pageSize` will succeed for this session. Derived
      * from the session's canvas seam, so it reflects exactly what `paint` will
-     * do — no separately captured flag.
+     * do: no separately captured flag.
      */
     readonly supportsCanvas: boolean;
     /**
      * Non-fatal diagnostics of the session's **current compile** (e.g. Typst
-     * font fallback) — set at open and refreshed by each committed `apply`;
+     * font fallback): set at open and refreshed by each committed `apply`;
      * a failed apply keeps the last-good compile's warnings. Also appended
      * to `RenderResult.warnings` on each `render()` call.
      */
@@ -1029,7 +1186,7 @@ export class Quill {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Build a quill from a file tree. Pure — no backend, no engine; the
+     * Build a quill from a file tree. Pure: no backend, no engine; the
      * declared backend is resolved later, at render time.
      *
      * Accepts either a `Map<string, Uint8Array>` or a plain object
@@ -1039,11 +1196,11 @@ export class Quill {
      */
     static fromTree(tree: Map<string, Uint8Array>): Quill;
     /**
-     * The resolved-value view of `doc` against this quill's schema — for every
+     * The resolved-value view of `doc` against this quill's schema: for every
      * declared field the value the render projection would use and the
      * `FieldSource` rung it came from (`"authored" | "default" | "zero"`), in
      * one call. The card body is a `body` sibling on its card (row `name`
-     * `"body"`), never a row in `fields` — `null` when the kind enables no body.
+     * `"body"`), never a row in `fields`: `null` when the kind enables no body.
      *
      * Value and provenance only: completeness and errors stay `validate`'s
      * (a consumer merges it with its own diagnostic producers regardless), and
@@ -1060,11 +1217,11 @@ export class Quill {
      * Pass `document.seedOverlay(cardKind)` as `overlay` so a card added to a
      * template-derived document inherits its curated starting values; omit it
      * (or pass `undefined` / `null`) for the bare schema seed. `overlay` is a
-     * plain object — this reads the document, it does not mutate it.
+     * plain object: this reads the document, it does not mutate it.
      */
     seedCard(card_kind: string, overlay: Record<string, unknown> | undefined): Card | undefined;
     /**
-     * Seed a starter `Document` from the schema — the main card plus one
+     * Seed a starter `Document` from the schema, the main card plus one
      * instance of each composable card kind, each committing its fields'
      * `example:` values and leaving every other field absent (interpolated at
      * render: `default:`, else type-empty zero). Illustration-first: a field
@@ -1073,14 +1230,14 @@ export class Quill {
      */
     seedDocument(): Document;
     /**
-     * Seed a starter main `Card` (carries `$quill`) from the schema — the
+     * Seed a starter main `Card` (carries `$quill`) from the schema: the
      * `$kind: main` card of [`seedDocument`](Self::seed_document) in
      * isolation, committing each field's `example:` value. Returns the same
      * `Card` shape as the `Document.main` getter.
      */
     seedMain(): Card;
     /**
-     * Flatten this quill back into its canonical file tree — the inverse of
+     * Flatten this quill back into its canonical file tree: the inverse of
      * [`fromTree`](Self::from_tree). Round-trips: `Quill.fromTree(q.toTree())`
      * reproduces an equivalent quill.
      *
@@ -1096,8 +1253,8 @@ export class Quill {
      * Validate `doc` against this quill's schema, returning every diagnostic
      * (an empty array when the document is valid).
      *
-     * Forwards the canonical `validation::*` diagnostics — same `code`,
-     * `path`, and `hint` the engine emits — including the non-fatal
+     * Forwards the canonical `validation::*` diagnostics (same `code`,
+     * `path`, and `hint` the engine emits) including the non-fatal
      * `validation::must_fill` warning for each `!must_fill` marker left in
      * the document. Field values, defaults, and order are not part of this
      * surface: read them from the `Document` payload and `Quill.schema`
@@ -1106,14 +1263,14 @@ export class Quill {
     validate(doc: Document): Diagnostic[];
     /**
      * The *declared* backend identifier (`config.backend`, e.g. `"typst"`).
-     * Intent, not a resolved capability — capability (`supportedFormats` /
+     * Intent, not a resolved capability: capability (`supportedFormats` /
      * `supportsCanvas`) is read from the engine.
      */
     readonly backendId: string;
     readonly blueprint: string;
     /**
      * Identity snapshot of the `quill:` section of `Quill.yaml` plus any extra
-     * `quill:` keys. Pure config — the backend's output formats are a
+     * `quill:` keys. Pure config: the backend's output formats are a
      * resolved-backend capability read from the engine
      * (`Quillmark.supportedFormats`), not part of this snapshot.
      */
@@ -1121,15 +1278,15 @@ export class Quill {
     /**
      * Document schema for the quill: the user-fillable fields plus their
      * `ui` hints (title / group / compact / multiline). The single
-     * field-metadata surface — drives form editors and LLM/MCP consumers
-     * alike. Key order in `fields`/`properties` is declaration order — the
+     * field-metadata surface: drives form editors and LLM/MCP consumers
+     * alike. Key order in `fields`/`properties` is declaration order: the
      * ordering contract. Returns the `QuillSchema` shape.
      */
     readonly schema: QuillSchema;
 }
 
 /**
- * Render engine: a backend registry and render dispatcher. Render build only —
+ * Render engine: a backend registry and render dispatcher. Render build only:
  * the core build constructs and validates quills without it.
  */
 export class Quillmark {
@@ -1147,7 +1304,7 @@ export class Quillmark {
      */
     render(quill: Quill, doc: Document, opts?: RenderOptions | null): RenderResult;
     /**
-     * The output formats `quill`'s backend can emit. Static capability —
+     * The output formats `quill`'s backend can emit. Static capability:
      * resolves the backend but compiles nothing. Throws `engine::backend_not_found`
      * if no registered backend matches the quill's declared backend.
      */
@@ -1163,7 +1320,7 @@ export class Quillmark {
 }
 
 /**
- * Export a canonical `Content` content to its markdown projection — the pure
+ * Export a canonical `Content` content to its markdown projection: the pure
  * on-demand codec behind `exportMarkdown(card.body)`. Throws if `rt` is not a
  * canonical content.
  */
@@ -1171,7 +1328,7 @@ export function exportMarkdown(rt: Content): string;
 
 /**
  * Serialize structured [`DocPathSeg`] segments back to the canonical path
- * string — the inverse of `parseDocPath`, for a consumer that builds a path
+ * string: the inverse of `parseDocPath`, for a consumer that builds a path
  * rather than reads one. Throws on a segment array the deserializer rejects,
  * and on an empty segment array (symmetric with `parseDocPath("")`, which
  * throws "empty path").
@@ -1179,7 +1336,7 @@ export function exportMarkdown(rt: Content): string;
 export function formatDocPath(segs: DocPathSeg[]): string;
 
 /**
- * Import a markdown string to a canonical `Content` content — the pure,
+ * Import a markdown string to a canonical `Content` content: the pure,
  * document-free codec. Pair with `install(addr, importMarkdown(md))` to spell
  * the cold (anchor-losing) write at the call site; prefer `revise` for edit
  * semantics. Throws on an over-nested input.
@@ -1192,8 +1349,8 @@ export function importMarkdown(markdown: string): Content;
 export function init(): void;
 
 /**
- * Map a base content position — a USV index into `Content.text`, not a UTF-16
- * offset — through a `delta` to its new USV position: the pure position-mapping
+ * Map a base content position (a USV index into `Content.text`, not a UTF-16
+ * offset) through a `delta` to its new USV position: the pure position-mapping
  * codec an editor bridge composes to hold a caret stable across a `revise`.
  * `assoc` decides the side of a same-position insertion (`"after"` moves past
  * it). Throws on a malformed `delta`.
@@ -1203,14 +1360,14 @@ 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 its
- * structured [`DocPathSeg`] segments — the exported inverse of the engine's
+ * structured [`DocPathSeg`] segments: the exported inverse of the engine's
  * one path serializer, so a consumer routes on segments instead of regexing
  * the string. Throws on a malformed path.
  */
 export function parseDocPath(path: string): DocPathSeg[];
 
 /**
- * Rebase `markdown` onto a `base` content — the pure, document-free twin of
+ * Rebase `markdown` onto a `base` content, the pure, document-free twin of
  * `revise`: cold-import + `diff_import`, returning the new `content` and the
  * text `delta` (its offsets USV indices into `Content.text`, surviving anchors
  * rebased). Use it to compute a revise without a document in hand; `revise(addr,