@quillmark/wasm 0.103.0 → 0.105.0

package/core/wasm.d.ts

@@ -24,17 +24,13 @@ export type PayloadItem =
 | { type: "comment"; text: string; inline?: boolean };
 
 /**
- * A single card block, as read back from a document: returned by
- * `Document.main` / `Document.cards` / `Document.removeCard` / `Quill.seedCard`
- * / `Document.makeCard`. To feed a card *into* a document use `CardInput`
- * (which `insertCard` accepts); every `Card` is a valid `CardInput`,
- * so a card read from one document pushes straight into another.
+ * A single card block, as read back from a document. Every `Card` is a valid
+ * `CardInput`, so a card read from one document pushes straight into another.
  *
  * `$` system entries are hoisted to named fields: `kind` (the `$kind`, empty
- * string when none), optional `quill` (the `$quill` `name@version`, main card
- * only), optional `ext` (`$ext`), and optional `seed`
- * (the `$seed` per-kind overlay map, main card only). `payloadItems` carries
- * user fields and comments in order.
+ * string when none), `quill` (`$quill` `name@version`, main card only), `ext`
+ * (`$ext`), and `seed` (the `$seed` per-kind overlay map, main card only).
+ * `payloadItems` carries user fields and comments in order.
  */
 export interface Card {
     kind: string;
@@ -43,21 +39,16 @@ export interface Card {
     seed?: Record<string, unknown>;
     payloadItems: PayloadItem[];
     /**
-     * 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.overwrite(addr, rt)` / `doc.revise(addr, md)`, or via `CardInput.body`.
+     * The card body as canonical `Content`, never a markdown string. For the
+     * markdown projection call `exportMarkdown(card.body)`.
      */
     body: Content;
 }
 
 /**
- * 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:
- * an absent field defaults (no payload items, an empty body). Write one inline
- * (`{ kind, body }`) or build it with `Document.makeCard`.
+ * A card written *into* a document, accepted by `Document.insertCard`. Like
+ * `Card`, but `body` also takes a markdown `string`, and every field but `kind`
+ * is optional (defaulting to no payload items and an empty body).
  */
 export interface CardInput {
     kind: string;
@@ -69,11 +60,10 @@ export interface CardInput {
 }
 
 /**
- * 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.
- * Mirrors `quillmark_content::serial`'s canonical JSON encoding.
+ * Canonical richtext content: the model behind 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.
  */
 export interface Content {
     text: string;
@@ -82,19 +72,17 @@ export interface Content {
     islands: ContentIsland[];
 }
 
-/** 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. */
+/** 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. */
 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`. */
+/** A line's block role, shared by `ContentLine` and the `setKind` op. */
 export type ContentLineKind =
 | { kind: "para" }
 | { kind: "heading"; level: number }
@@ -112,13 +100,12 @@ export type ContentContainer =
 | { 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`
- * (`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
- * markdown projection and survives only through the edit lane. See DOCUMENT_STORAGE
- * § Anchor-id identity. */
+ * arm blocks discriminant narrowing, so read a payload-carrying arm behind its
+ * guard: `isLinkMark` (`url`) / `isAnchorMark` (`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 }
@@ -126,9 +113,8 @@ 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`
- * 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
+/** 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`. */
 export interface TableCell {
     text: string;
@@ -150,17 +136,15 @@ export interface ImageProps {
     alt: string;
 }
 
-/** A structured object occupying one island slot in `Content.text`. `type` is an
- * 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` /
- * `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`. */
+/** How faithfully the markdown projection can carry an island. Open: an unknown
+ * class round-trips verbatim and reads as `unrepresentable`. */
 export type ContentLossClass = "lossless" | "degraded" | "unrepresentable" | (string & {});
 
+/** A structured object occupying one island slot in `Content.text`. `type` is an
+ * open set: `props` is `TableProps` for `table` and `ImageProps` for `image`,
+ * and any other type round-trips with opaque `props`. The open arm blocks
+ * narrowing, so read `props` behind the `isTableIsland` / `isImageIsland`
+ * guards (from `@quillmark/wasm/runtime`). */
 export type ContentIsland = {
     id: string;
     loss: ContentLossClass;
@@ -178,9 +162,16 @@ export type ContentIsland = {
  * 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
- * rule. A bare number is *not* an addr (`{ card: 2 }` is the self-documenting
- * spelling), so no third navigation idiom re-fragments the surface.
+ * (`doc.storeField("qty", 3)`); a bare number is *not* an addr.
+ *
+ * `doc.pathFor(addr)` mints the address as its canonical `DocPath` string, the
+ * anchor `Diagnostic.path` carries and `session.locate` / `session.fieldBoxes`
+ * take. A card path is kind-qualified, so a hand-built one needs the card's
+ * `$kind`, and a wrong-kind path matches nothing silently.
+ *
+ * An `Addr` names a field, never a value inside one: every verb that takes one
+ * would then carry an element axis it cannot answer. The one read that reaches
+ * inside takes the path as its own argument, `reader.getContentAt(addr, path)`.
  */
 export interface Addr {
     card?: number;
@@ -188,10 +179,9 @@ export interface Addr {
 }
 
 /**
- * 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.
+ * A card-only address, taken by the card-scoped verbs (`storeFields`,
+ * `storeExt`, `getExt`, `commitFields`, …). An absent `card` targets the main
+ * card; a present `field` throws.
  */
 export interface CardAddr {
     card?: number;
@@ -199,8 +189,8 @@ 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
- * the `rebase` codec; map a stored position through it with `mapPos`.
+ * semantics), returned by `revise` and by the `rebase` codec. Map a stored
+ * position through it with `mapPos`.
  */
 export interface Delta {
     ops: ({ retain: number } | { insert: string } | { delete: number })[];
@@ -211,11 +201,9 @@ 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
- * (ids are caller-supplied and unique per `Content`; DOCUMENT_STORAGE
- * § Anchor-id identity).
+ * `remove` carry the `ContentMark` vocabulary; `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.
  */
 export type MarkOp =
 | ({ op: "add" | "remove"; start: number; end: number } & (
@@ -227,12 +215,10 @@ export type MarkOp =
 | { op: "removeAnchor"; id: string };
 
 /**
- * A line/block edit. `split`/`join` splice `\n` in post-`delta`, post-`islandOps`
- * coordinates; `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 Shift+Enter hard
- * break or a new code-fence interior line; `continues: true` on line 0 is
- * rejected (nothing precedes it to continue).
+ * A line/block edit. `split`/`join` splice `\n` in post-`delta`,
+ * post-`islandOps` coordinates; `setKind`/`setContainers`/`setContinues` touch
+ * metadata. `setContinues` sets or clears a line's within-block hard-break flag
+ * (`ContentLine.continues`); `continues: true` on line 0 is rejected.
  */
 export type LineOp =
 | { op: "split"; at: number }
@@ -243,34 +229,25 @@ export type LineOp =
 
 /**
  * An island edit: the only channel that reaches an island's payload, a table's
- * cells or an image's url.
- *
- * Both ops move one island entry and leave the field's text and marks alone, so
- * an island edit keeps every identity anchor in the field. That is why a table
- * edit lowers to `applyChange` rather than `overwrite`, which drops them all.
+ * cells or an image's url. Both ops leave the field's text and marks alone, so
+ * an island edit keeps every identity anchor in the field.
  *
- * `set` addresses an existing island by `id`; an `id` no island carries throws
- * rather than passing silently. `insert` places a new island's slot at `at`
- * together with its entry, so a slot never exists without an island behind it;
- * its `id` must be non-empty and unused. `at` is a position in the text the
- * `delta` and this bundle's earlier island ops left: each insert splices its
- * slot before the next op reads the text, so slots after `a` and `b` of `abc`
- * go in at 1 and 3. A stale frame misplaces slots and never throws.
+ * `set` addresses an existing island by `id`; an unknown `id` throws. `insert`
+ * places a new island's slot at `at` together with its entry, so a slot never
+ * exists without an island behind it; its `id` must be non-empty and unused.
+ * `at` is a position in the text the `delta` and this bundle's earlier island
+ * ops left, so slots after `a` and `b` of `abc` go in at 1 and 3. A stale frame
+ * misplaces slots and never throws. A `delta` insert string may not carry a
+ * slot, which would orphan: split such a splice into the slot-free `delta` plus
+ * one `insert` per slot.
  *
- * A `delta` insert string may not carry a slot, which would orphan. A producer
- * that computes one splice over the whole field text carries slots in it on any
- * paste of an island or undo of a deletion; that splice splits into the
- * slot-free `delta` plus one `insert` per slot.
+ * Deleting an island needs no op: a `delta` that removes its slot drops the
+ * island whole, and a block island's line demotes to `para`. Re-landing it is an
+ * `insert` of the full island under its original id; a pasted copy of a live
+ * island mints a fresh one.
  *
- * Deleting an island needs no op, and the drop is whole: a `delta` that removes
- * its slot drops the island from the store. Re-landing it is an `insert` of the
- * full island under its original id, and only the producer that deleted it
- * still holds that value. A pasted copy of a live island is new and mints fresh
- * (DOCUMENT_STORAGE § Island-id determinism). A block island's line demotes to
- * `para` when its slot goes, so re-landing one re-tags the line too.
- *
- * A `set` stores the `loss` it is given: nothing re-derives the class from the
- * new `props`, so a write that changes what markdown can carry must say so.
+ * A `set` stores the `loss` it is given; nothing re-derives the class from the
+ * new `props`.
  *
  * An island is *inline* (a slot inside a paragraph) unless its line says
  * otherwise. A **block** island is one bundle of all three channels, in the
@@ -283,13 +260,12 @@ export type IslandOp =
 | ({ op: "insert"; at: number } & ContentIsland);
 
 /**
- * A committed content edit bundle for `applyChange`: a text `delta` (default no
- * text change), then `islandOps`, then `lineOps`, then `markOps` (mark ranges
- * are in final-text coordinates: every earlier channel applied). Every field is
- * optional.
+ * A committed content edit bundle for `applyChange`, applied in order: a text
+ * `delta`, then `islandOps`, then `lineOps`, then `markOps` (mark ranges are in
+ * final-text coordinates). Every field is optional.
  *
- * Within each channel ops apply in sequence, each against the state the earlier
- * ones left: an island `insert`'s `at` counts earlier ops' slots, and `lineOps`
+ * 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`.
  */
 export interface ChangeBundle {
@@ -317,14 +293,12 @@ export type DocPathSeg =
 
 
 /** The commitment-ladder rung that produced a `ResolvedField.value`. */
-export type FieldSource = "authored" | "default" | "zero";
+export type FieldSource = "authored" | "default" | "blank";
 
 /**
  * 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
- * 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`.
+ * the `FieldSource` rung it came from. Rows are an ordered array, so declaration
+ * order is structural rather than object-key order.
  */
 export interface ResolvedField {
     name: string;
@@ -354,9 +328,8 @@ export interface ResolvedCard {
 }
 
 /**
- * The resolved-value view (`Quill.resolve`): the main card and every
- * composable card. Value and provenance only: completeness and errors stay
- * `Quill.validate`.
+ * The resolved-value view (`Quill.resolve`): the main card and every composable
+ * card. Value and provenance only; completeness stays `Quill.validate`'s.
  */
 export interface Resolved {
     main: ResolvedMain;
@@ -365,20 +338,21 @@ export interface Resolved {
 
 
 
-/** UI layout hints for a single field. Field display order is not a hint:
- * key order in the schema's `fields`/`properties` objects is declaration
- * order, the ordering contract. */
+/** UI layout hints for a single field. Display order is not a hint: key order
+ * in the schema's `fields`/`properties` objects is the ordering contract. */
 export interface QuillFieldUi {
     title?: string;
     group?: string;
     compact?: boolean;
     multiline?: boolean;
+    /** Label for an `enum`'s blank option. Absent, the consumer supplies a
+     *  conventional label of its own. */
+    blank_title?: string;
 }
 
 /** 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
- * derives the label from the id (`memo_for` → "Memo For"), as it does a field
- * label from its key. */
+ * group id (the map key). An empty object carries no override, and the consumer
+ * derives the label from the id (`memo_for` → "Memo For"). */
 export interface QuillGroupUi {
     title?: string;
 }
@@ -386,48 +360,61 @@ export interface QuillGroupUi {
 /** UI layout hints for a card (main or named card kind). */
 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
-     * `fields` key order carries. Absent when the card declares no groups (or
-     * uses the deprecated implicit-group form). */
+    /** The groups a field's `ui.group` may reference, keyed by group id. Key
+     * order is the display-order contract, as with `fields`. Absent when the
+     * card declares no groups. */
     groups?: Record<string, QuillGroupUi>;
 }
 
+/** A block construct a body can hold. `paragraph` is the floor and cannot be
+ * declined, so it is absent. */
+export type QuillBlockConstruct =
+| "heading"
+| "rule"
+| "code"
+| "list"
+| "quote"
+| "table"
+| "image";
+
 /** Body namespace for a card (main or named card kind). */
 export interface QuillCardBody {
     /** When false, consumers must not accept or store body content for this card kind. Defaults to true. */
     enabled?: boolean;
     /** Example body content embedded verbatim in the blueprint body region. Fallback is "Write <card> body here." */
     example?: string;
+    /** Block constructs this quill's plate does not typeset in this body;
+     * absent or empty declines nothing. A body that holds one anyway draws a
+     * non-fatal `plate::unsupported_construct` warning. Nothing verifies the
+     * claim: absence from this list is not a promise the plate typesets it. */
+    unsupported?: QuillBlockConstruct[];
 }
 
 /** Schema entry for a single field declared in a quill's `Quill.yaml`.
  *
- * A field's *cell* is determined by `default`: a field with a `default`
- * is **Endorsed** (the rendered value is shippable as-is), while a field
- * without a `default` is **Unendorsed** (the blueprint carries a
- * `!must_fill` marker; a marker left in the document yields the non-fatal
- * `validation::must_fill` warning from validate, and the render path
- * zero-fills the field). There is no separate `required` axis.
+ * Two independent axes, and no separate `required` one. `default` and
+ * `example` say what the cell holds; `must_fill` says whether a human must
+ * author it, deriving from `default`'s absence when left unset. An obliged
+ * field carries a `!must_fill` marker in the blueprint and warns
+ * `validation::must_fill` while the document leaves it unauthored. Neither
+ * axis gates render: an absent field blank-fills.
  */
 export interface QuillFieldSchema {
     type: "string" | "number" | "integer" | "boolean" | "array" | "object" | "date" | "datetime" | "richtext" | "plaintext" | "enum";
     description?: string;
     default?: unknown;
     example?: unknown;
-    /** Closed value domain. On `type: "enum"` declared as `values`; the
-     *  deprecated `enum` modifier on `type: "string"` is accepted for one
-     *  release. Both round-trip through this field. */
-    enum?: string[];
-    /** Required on `type: "enum"`: the closed set of allowed string values. */
+    /** The closed set of allowed values. Required on `type: "enum"`, and valid
+     *  nowhere else. */
     values?: string[];
+    /** Whether a human must author the field. Absent, it derives from
+     *  `default`: a defaulted field is unobliged, a defaultless one obliged. */
+    must_fill?: boolean;
     ui?: QuillFieldUi;
     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.
-     *  Core serializes `inline: true` into the schema JSON; absent otherwise. */
+    /** `true` on a `richtext` or `plaintext` field declared `inline`: the
+     *  single-paragraph, container-free, island-free constraint. */
     inline?: boolean;
 }
 
@@ -440,10 +427,8 @@ export interface QuillCardSchema {
 }
 
 /**
- * Document schema returned by `Quill.schema`. Includes optional `ui` keys.
- *
- * Describes only the user-fillable fields. The quill reference
- * (constructed as `${metadata.name}@${metadata.version}`) and card-kind
+ * Document schema returned by `Quill.schema`: the user-fillable fields only.
+ * The quill reference (`${metadata.name}@${metadata.version}`) and card-kind
  * discriminators are document-level metadata, not schema fields.
  */
 export interface QuillSchema {
@@ -453,10 +438,9 @@ export interface QuillSchema {
 }
 
 /**
- * Identity snapshot mirroring the `quill:` section of `Quill.yaml`.
- * The schema lives on `Quill.schema`; the backend's output formats are a
- * resolved-backend capability read from the engine (`Quillmark.supportedFormats`),
- * not part of this pure-config snapshot.
+ * Identity snapshot mirroring the `quill:` section of `Quill.yaml`. The schema
+ * lives on `Quill.schema`; output formats are a resolved-backend capability read
+ * from `Quillmark.supportedFormats`, not part of this config snapshot.
  */
 export interface QuillMetadata {
     name: string;
@@ -476,31 +460,22 @@ export interface Diagnostic {
     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.
+     * Document-model path anchor (e.g. `\"cards.indorsement[0].signature_block\"`),
+     * set on schema validation diagnostics and `undefined` otherwise.
      */
     path?: string;
     hint?: string;
     /**
-     * The facts `message` interpolates, keyed by name. With `code`, the
-     * substitution unit needed to word this diagnostic in another language;
-     * `prose/canon/ERROR.md` § \"Diagnostic args\" tabulates the keys per code.
+     * The facts `message` interpolates, keyed by name. With `code`, enough to
+     * word this diagnostic in another language.
      *
-     * Declared optional explicitly because `tsify` does not read
-     * `skip_serializing_if`: without this, a field the runtime omits is
-     * declared required. `sourceChain` carries that mismatch.
+     * Declared optional explicitly: `tsify` does not read
+     * `skip_serializing_if`, so an omitted field would be declared required.
      */
     args?: Record<string, unknown>;
     sourceChain?: string[];
 }
 
-/**
- * Severity levels for diagnostics
- */
-export type Severity = "error" | "warning";
-
 /**
  * Source location for errors and warnings
  */
@@ -510,6 +485,8 @@ export interface Location {
     column: number;
 }
 
+export type Severity = "error" | "warning";
+
 
 /**
  * Typed in-memory Quillmark document.
@@ -518,79 +495,69 @@ export class Document {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * **Apply** a committed content edit `bundle`
-     * (`{ delta?, islandOps?, lineOps?, markOps? }`) at `addr`, the editor
-     * splice: text delta first, then island ops, 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.
-     *
-     * The island channel keeps a table or image edit on the op path: it moves
-     * the island alone, so the anchors elsewhere in the field survive an edit
+     * **Apply** a committed content edit `bundle` at `addr`, the editor splice:
+     * text delta first, then island ops, then line ops, then mark ops (mark
+     * ranges in final-text coordinates), all-or-nothing. An absent `addr.field`
+     * targets the body, an absent `addr.card` the main card. The island channel
+     * moves an island alone, so anchors elsewhere in the field survive an edit
      * `overwrite` would clear.
      *
      * 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).
+     * bundle, or an op that applies out of bounds; the value is unchanged on a
+     * failed apply.
      */
     applyChange(addr: Addr | string, bundle: ChangeBundle): void;
     /**
-     * Authoring-ergonomics header introducing a blueprint to an LLM/MCP
-     * consumer for the given `quillName`. Re-exposes core's canonical text for
-     * JS consumers; any surface that draws from the same core source stays
-     * uniform.
+     * Authoring-ergonomics header introducing a blueprint to an LLM/MCP consumer
+     * for the given `quillName`, re-exposed from core.
      */
     static blueprintInstruction(quill_name: string): string;
     /**
-     * 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.
+     * The **body** markdown projection: an 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, and 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
-     * schema-plane `quill.reader(doc).get(field)`, which interprets by declared
-     * type. An out-of-range `addr.card` throws.
+     * `addr` is an optional card address (absent = main). A present `field`
+     * throws: read a field's markdown through `quill.reader(doc).get(field)`,
+     * which interprets by declared type. An out-of-range `addr.card` throws.
      */
     bodyMarkdown(addr?: CardAddr): string;
     /**
-     * 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
-     * verbs.
+     * A single composable card by index, so reading one need not materialize
+     * every card via [`cards`](Self::cards). An out-of-range `index` throws
+     * `edit::index_out_of_range`.
      */
     card(index: number): Card;
+    /**
+     * The composable card's own path, `cards.<kind>[index]`: the root
+     * [`pathFor`](Self::path_for) extends, for anchoring the card rather than
+     * one of its fields. Total on the index axis; out of range renders
+     * `cards[index]`.
+     */
+    cardPath(index: number): string;
     clone(): Document;
     /**
-     * Storage version this build writes via [`toJson`](Document::to_json).
-     * Tracks the `Document` model version (not the running crate version):
-     * the tag advances only when the wire format changes, not on every release.
+     * Storage version this build writes via [`toJson`](Document::to_json). The
+     * tag advances only when the wire format changes, not on every release.
      */
     static currentStorageVersion(): string;
     /**
-     * Structural equality (parse-time `warnings` excluded). Use to debounce
-     * upstream prop updates instead of re-parsing on every keystroke.
+     * Structural equality, excluding parse-time `warnings`.
      */
     equals(other: Document): boolean;
     /**
-     * Render a Diagnostic as the canonical pretty-printed text (core's
-     * `Diagnostic::fmt_pretty`). Single source of truth so a Diagnostic looks
-     * identical no matter which consumer surfaces it.
+     * Render a Diagnostic as the canonical pretty-printed text, so it looks
+     * identical whichever consumer surfaces it.
      */
     static formatDiagnostic(diag: Diagnostic): string;
     /**
-     * Authoring-format rules for the card-yaml markdown surface. The canonical
-     * text is core's (`quillmark_core::document::FORMAT_RULES`), re-exposed
-     * here for JS consumers so it matches any other surface that draws from the
-     * same source. Read once at startup and cache; the value never changes
-     * between calls.
+     * Authoring-format rules for the card-yaml markdown surface, re-exposed from
+     * core. Constant across calls; read once and cache.
      */
     static formatRules(): string;
     /**
-     * Reconstruct a `Document` from a versioned storage DTO string produced
-     * by [`toJson`](Document::to_json). Unknown `schema` tags are rejected.
-     * The result carries no parse-time warnings (`.warnings` is always empty).
-     *
+     * Reconstruct a `Document` from a versioned storage DTO string produced by
+     * [`toJson`](Document::to_json). The result carries no parse-time warnings.
      * Throws if `json` is not a valid storage DTO (malformed JSON, unknown
      * `schema`, missing fields, or unparseable quill reference).
      */
@@ -601,81 +568,66 @@ 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:
-     * 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.
+     * `undefined` when the card carries none: the `$ext` read that avoids
+     * serializing the whole card. Throws on a present `field` 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
-     * without a whole-card serialize, and non-destructive (unlike
-     * `removeExtNamespace`). Throws on a present `field` or an out-of-range card.
+     * = main), or `undefined`. Throws on a present `field` or an out-of-range
+     * card.
      */
     getExtNamespace(addr: CardAddr, ns: string): unknown;
     /**
-     * Read the **verbatim stored value** at `addr`: the raw payload value of a
-     * field, 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
-     * the interpreted schema-plane [`reader.get`](Self::reader_get). For the
-     * markdown projection use [`bodyMarkdown`](Self::get_markdown) (body) or
-     * `reader.get` (a field's declared type).
+     * Read the **verbatim stored value** at `addr`: a field's raw payload value,
+     * or the body content when `addr.field` is absent. A bare string is `Addr`
+     * shorthand for `{ field }`. Needs no schema: the read echo of the verbatim
+     * `store*` write, distinct from the interpreted
+     * [`reader.get`](Self::reader_get). Reads are total over the field axis — an
+     * absent field is `undefined` — and only an out-of-range `addr.card` throws
+     * `edit::index_out_of_range`.
      *
-     * **A content field at rest has one stored form per codec**: a `richtext`
-     * field holds the canonical content object, a `plaintext` field its literal
-     * string. A document that came through the bound door (`quill.parse` /
-     * `quill.conform`) is at rest, so this read no longer depends on which lane
-     * built it. A document that came through the transport door
-     * (`Document.fromMarkdown`, a legacy stored row) may rest as authored until
-     * it is conformed, and this read reports what is there. For the `Content`
-     * either way, use the schema-plane `reader.getContent`, which decodes
-     * through the codec the field's declared type names.
+     * A content field at rest has one stored form per codec: a `richtext` field
+     * holds the canonical content object, a `plaintext` field its literal
+     * string. A document from the bound door (`quill.parse` / `quill.conform`)
+     * is at rest; one from the transport door may rest as authored until it is
+     * conformed, and this read reports what is there. For the `Content` either
+     * way use `reader.getContent`.
      */
     getStored(addr: Addr | string): unknown;
     /**
-     * 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`),
-     * 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.
+     * Insert a card: `at` absent appends, a number inserts at that index (in
+     * `0..=cards.length`). Accepts any `CardInput`, including a card read back
+     * out of a document. Throws if `card.kind` is not a valid kind name, or if
+     * `at` is out of range.
      */
     insertCard(card: CardInput, at?: number): 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
-     * marked) and for a body address (a body is never a fill). Only an
-     * out-of-range `addr.card` throws.
+     * shorthand for `{ field }`. `false` for an absent field and for a body
+     * address; 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
-     * [`fromJson`](Document::from_json) constructor. Parse-time `warnings` are
-     * cleared. Throws (leaving the document unchanged) on an invalid DTO.
+     * Replace this document's contents **in place** from a versioned storage DTO
+     * string: the mutating twin of [`fromJson`](Document::from_json). Parse-time
+     * `warnings` are cleared. Throws on an invalid DTO, leaving the document
+     * unchanged.
      *
      * 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
-     * the linear-memory seam without the caller re-binding its variable.
+     * backend-memory clone, then write the state back into the caller's
+     * canonical document, 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
-     * constructor for `insertCard`. `fields` is an optional
-     * `Record<string, unknown>` (each entry becomes a card field, in
-     * insertion order); `body` defaults to `""`.
+     * constructor for `insertCard`, which also takes any `Card` object
+     * directly. Each `fields` entry becomes a card field in 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
+     * Checks only what a detached card can decide alone: field-name grammar and
+     * value depth. Kind validity is positional, so `insertCard` is its gate and
      * any kind string is accepted here.
      */
     static makeCard(kind: string, fields?: Record<string, unknown>, body?: string): Card;
@@ -684,43 +636,51 @@ export class Document {
      */
     moveCard(from: number, to: number): void;
     /**
-     * `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
-     * output. For an example-filled starter use `Quill.seedDocument()`.
-     * Throws on an invalid quill reference. Mirrors Python `Document(quill_ref)`.
+     * A blank document: a main card carrying only `$quill`, an empty body, and
+     * no composable cards. Absent fields resolve at render time (`default`, else
+     * the field's blank), so nothing the caller did not set reaches the output.
+     * For an example-filled starter use `Quill.seedDocument()`. Throws on an
+     * invalid quill reference.
      */
     constructor(quill_ref: string);
     /**
-     * **Overwrite** the content value at `addr`: **value semantics**, content
-     * only. Stores exactly `rt` (a canonical `Content` content object); the
-     * identity anchors of any previous value are gone. The bottom rung of the
-     * content lane's ladder by anchor fate: `overwrite` destroys,
-     * [`revise`](Document::revise) rebases,
-     * [`applyChange`](Document::apply_change) preserves. An absent `addr.field`
-     * targets the body, an absent `addr.card` the main card. Cold-importing
-     * markdown is spelled `overwrite(addr, importMarkdown(md))` at the call
-     * site, where the anchor loss is visible.
+     * **Overwrite** the content value at `addr` with exactly `rt`: value
+     * semantics, so the identity anchors of any previous value are gone. By
+     * anchor fate `overwrite` destroys, [`revise`](Document::revise) rebases,
+     * and [`applyChange`](Document::apply_change) preserves. An absent
+     * `addr.field` targets the body, an absent `addr.card` the main card.
      *
      * Throws on an out-of-range card, a malformed field name, or an `rt` that is
      * not a canonical content object.
      */
     overwrite(addr: Addr | string, rt: Content): void;
     /**
-     * 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
-     * `hint` on `parse::invalid_quill_reference`. Cache it; the value never
-     * changes.
+     * `addr`'s canonical `DocPath` string, the anchor `Diagnostic.path` carries:
+     * `pathFor()` is `main.body`, `pathFor("intro")` `main.intro`,
+     * `pathFor({card: 2})` `cards.<kind>[2].body`.
+     *
+     * The kind is the card's stored `$kind` verbatim, not `validate`'s
+     * declared-kind filter, since a `Document` holds a `$quill` reference and no
+     * schema. That is the one edge where this path and a `validate` diagnostic
+     * path differ for the same card.
+     *
+     * **Total on the index axis**, unlike the `Addr` reads, which throw there:
+     * an out-of-range `{card: 7, field: "from"}` renders `cards[7].from`, which
+     * parses back and resolves to nothing rather than mis-targeting. Only a
+     * malformed address throws.
+     */
+    pathFor(addr: Addr | string): string;
+    /**
+     * The canonical `$quill` reference grammar as author-facing text: the same
+     * text the `parse::invalid_quill_reference` hint carries. Drive validation
+     * messages from this instead of re-stating the rule.
      */
     static quillRefHint(): string;
     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
-     * namespace at once (prefer `removeExtNamespace`). `addr` is a card address
-     * (absent = main). Throws on a present `field` or an out-of-range card.
+     * Remove the `$ext` map on the card `addr` targets entirely, returning the
+     * previous map or `undefined`. Discards every namespace at once; prefer
+     * `removeExtNamespace`. Throws on a present `field` or an out-of-range card.
      */
     removeExt(addr?: CardAddr): Record<string, unknown> | undefined;
     /**
@@ -732,35 +692,31 @@ export class Document {
     removeExtNamespace(addr: CardAddr, ns: string): any;
     /**
      * Remove a field at `addr`, returning the removed value or `undefined`. A
-     * bare string is `Addr` shorthand for `{ field }`. One `remove` verb serves
-     * every write lane. A body address throws; throws on an out-of-range card or
-     * a malformed name.
+     * bare string is `Addr` shorthand for `{ field }`. A body address throws, as
+     * does an out-of-range card or a malformed name.
      */
     removeField(addr: Addr | string): any;
     /**
-     * Remove `cardKind` from the main card's `$seed` map, returning its
-     * overlay or `undefined`; drops `$seed` entirely once empty. Sibling kinds
-     * survive. `$seed` is main-only, so this takes no address.
+     * Remove `cardKind` from the main card's `$seed` map, returning its overlay
+     * or `undefined`; drops `$seed` entirely once empty. Sibling kinds survive.
      */
     removeSeedOverlay(card_kind: string): any;
     /**
-     * **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
-     * positions through (`mapPos`). An absent `addr.field` targets the body, an
-     * absent `addr.card` the main card; an absent field cold-imports from empty.
+     * **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.
      *
      * 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;
     /**
-     * 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`
-     * pure: the quill still never reads the document.
+     * The main card's `$seed[kind]` overlay object, or `undefined`. Feeds
+     * `quill.seedCard(kind, overlay)` without serializing the whole main card,
+     * and keeps `seedCard` pure: the quill never reads the document.
      */
     seedOverlay(kind: string): Record<string, unknown> | undefined;
     /**
@@ -774,78 +730,60 @@ export class Document {
      */
     setQuillRef(ref_str: string): void;
     /**
-     * Read the storage version tag from a raw storage DTO string without a
-     * full parse, or `undefined`. Returns unknown future versions as-is:
-     * useful to distinguish "build too old" from "payload corrupt" when
-     * `fromJson` throws.
-     *
-     * The storage version, not a field schema ([`schema`](Quill::schema) is the
-     * quill's field declarations). The JSON key is spelled `"schema"`: it is
-     * the DTO's serde tag, and retagging it would break the version dispatch
-     * it drives.
+     * Read the storage version tag from a raw storage DTO string without a full
+     * parse, or `undefined`. Unknown future versions come back as-is, which
+     * distinguishes "build too old" from "payload corrupt" when `fromJson`
+     * throws. This is the storage version, not a field schema, though the JSON
+     * key is spelled `"schema"`: that is the DTO's serde tag.
      */
     static storageVersionOf(json: string): string | undefined;
     /**
-     * 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
-     * `store` verb. Throws on a present `field` or an out-of-range card.
+     * Replace the opaque `$ext` map on the card `addr` targets (absent `card` =
+     * main). `value` must be a plain object. `$ext` carries out-of-band consumer
+     * state and never reaches the rendered output. 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.
-     * Throws on a present `field` or an out-of-range card.
+     * sibling namespaces: the recommended `$ext` write. 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,
-     * 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
-     * opaque; write it with `revise` / `overwrite` / `writer.reviseBody`. Throws on
-     * an out-of-range card or a malformed name.
+     * Store a field verbatim at `addr`, deferring coercion to render; the typed
+     * write is [`commitField`](Document::commit_field). A bare string is `Addr`
+     * shorthand for `{ field }`; `{ card: 2, field: "qty" }` targets a
+     * composable card. Clears any `!must_fill` marker. A body address throws:
+     * write a body with `revise` / `overwrite`. 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:
-     * 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`".
-     * Nothing is applied on error; the thrown error's `diagnostics` carry one
-     * entry per offending field. Throws on an out-of-range card.
+     * Store several fields verbatim and atomically on the card `addr` targets.
+     * `addr` is a **card address** (`{ card }`, absent = main) and comes first
+     * because `card` is itself a legal field name; a present `field` throws.
+     * Nothing is applied on error, and 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'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).
+     * Store a field verbatim at `addr` and mark it `!must_fill`. A body address
+     * throws; same validation as [`storeField`](Document::store_field).
      */
     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
-     * 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`
-     * verb. Throws if `overlay` cannot be serialized or nests too deep.
+     * under `cardKind`, preserving sibling kinds; `$seed` is main-only, so this
+     * takes no address. Sets the starting values new cards of that kind spawn
+     * with. Throws if `overlay` cannot be serialized or nests too deep.
      */
     storeSeedOverlay(card_kind: string, overlay: any): void;
     /**
-     * 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
-     * `warnings` are excluded from the DTO.
-     *
-     * Output is **byte-deterministic** within a `schema` version: equal
-     * documents produce byte-equal output, safe for content-hash use cases.
+     * Serialize this document to a versioned storage DTO string. Prefer it over
+     * `toMarkdown` for persistence: the wire format is frozen per `schema`
+     * version and the output is byte-deterministic within one, so equal
+     * documents hash equal. Parse-time `warnings` are excluded.
      */
     toJson(): string;
     /**
@@ -854,29 +792,26 @@ 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
-     * discriminate format without exceptions as control flow.
-     * `undefined` means "not a storage DTO"; `fromMarkdown` still throws on
-     * genuinely malformed markdown.
+     * Like [`fromJson`](Document::from_json) but returns `undefined` instead of
+     * throwing when `json` is not a valid storage DTO, to discriminate format
+     * without exceptions as control flow.
      */
     static tryFromJson(json: string): Document | undefined;
     /**
-     * Number of composable cards (excludes the main card). O(1).
+     * Number of composable cards, excluding the main card.
      */
     readonly cardCount: number;
     readonly cards: Card[];
     /**
-     * The document's main (entry) card. Allocates and serializes on each
-     * call: cache locally if read in a hot loop.
+     * The document's main (entry) card. Allocates and serializes on each call.
      */
     readonly main: Card;
     readonly quillRef: string;
     /**
      * The non-fatal diagnostics of the load that produced this document: parse
-     * warnings, plus the `conform::*` warnings when it came through
-     * `quill.parse`. Session state, not document value: `equals` and the
-     * storage DTO exclude it, and `fromJson` / `loadJson` clear it.
+     * warnings, plus `conform::*` warnings when it came through `quill.parse`.
+     * Session state, not document value: `equals` and the storage DTO exclude
+     * it, and `fromJson` / `loadJson` clear it.
      */
     readonly warnings: Diagnostic[];
 }
@@ -887,196 +822,152 @@ export class Quill {
     [Symbol.dispose](): void;
     /**
      * Land `doc`'s declared content fields at their canonical rest **in
-     * place**, returning the `conform::*` diagnostics for the values that would
-     * not commit (an empty array when everything rested).
-     *
-     * The read-repair verb: a document that arrived through the transport door
-     * (`fromMarkdown`, `fromJson`, a stored row) converges here, and is then
-     * eligible for rewrite under its current schema tag. Idempotent, and a
-     * no-op on an already-canonical document: an equal value is not rewritten,
-     * so YAML comments and stored bytes survive.
+     * place**, returning the `conform::*` diagnostics for values that would not
+     * commit. The read-repair verb for a document that arrived through the
+     * transport door (`fromMarkdown`, `fromJson`, a stored row).
      *
-     * A `!must_fill` marker anywhere in a field's value skips that field (the
-     * marker is the state), and a value the strict write refuses stays as
-     * authored with a diagnostic. Throws when `doc` declares a different
-     * `$quill`, before any mutation.
+     * Idempotent: an equal value is not rewritten, so YAML comments and stored
+     * bytes survive. A `!must_fill` marker anywhere in a field's value skips
+     * that field, and a value the strict write refuses stays as authored with a
+     * diagnostic. Throws when `doc` declares a different `$quill`, before any
+     * mutation.
      */
     conform(doc: Document): Diagnostic[];
     /**
-     * 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
-     * (`Record<string, Uint8Array>`). Plain objects are walked via
-     * `Object.entries` at the boundary; the Rust side sees a single
-     * canonical shape.
+     * Build a quill from a file tree. Pure: the declared backend is resolved
+     * later, at render time. Accepts a `Map<string, Uint8Array>` or a plain
+     * object.
      */
     static fromTree(tree: Map<string, Uint8Array>): Quill;
     /**
-     * Parse `markdown` and conform it against this quill: the **primary
-     * ingestion path**, and the bound twin of the schema-free
-     * `Document.fromMarkdown`. The returned document rests at its canonical
-     * form (a `richtext` field as a content object, a `plaintext` field as its
-     * literal string), so `getStored` answers "content object or string?" by the
-     * field's declared codec rather than by how the document was built.
+     * Parse `markdown` and conform it against this quill: the primary ingestion
+     * path, and the bound twin of the schema-free `Document.fromMarkdown`. The
+     * returned document rests at its canonical form (a `richtext` field as a
+     * content object, a `plaintext` field as its literal string), so `getStored`
+     * answers by the field's declared codec, not by how the document was built.
      *
      * Parse warnings and the `conform::*` diagnostics both land on
      * `doc.warnings`. Throws on a parse failure, or when `markdown` declares a
-     * `$quill` this quill does not answer to: nothing conforms under the wrong
-     * schema. To open a document whose `$quill` is stale, use the transport
-     * door (`Document.fromMarkdown`, `setQuillRef`, then `quill.conform`).
+     * `$quill` this quill does not answer to. To open a document whose `$quill`
+     * is stale, use `Document.fromMarkdown`, `setQuillRef`, then `quill.conform`.
      */
     parse(markdown: string): Document;
     /**
-     * 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.
-     *
-     * Value and provenance only: completeness and errors stay `validate`'s
-     * (a consumer merges it with its own diagnostic producers regardless), and
-     * schema guidance reads from `Quill.schema`.
+     * The resolved-value view of `doc`: for every declared field, the value the
+     * render projection would use and the `FieldSource` rung it came from
+     * (`"authored" | "default" | "blank"`). The card body is a `body` sibling on
+     * its card, never a row in `fields`, and `null` when the kind enables no
+     * body. Value and provenance only; completeness stays `validate`'s.
      */
     resolve(doc: Document): Resolved;
     /**
      * Seed a starter composable `Card` of the given kind (carries `$kind`),
-     * layering an optional per-kind seed `overlay` over the schema-example
-     * base (`overlay › example › absent`). Returns `undefined` if `cardKind`
-     * is not declared in this quill's schema, else a `Card` that feeds
-     * straight into `Document.insertCard`.
+     * layering an optional per-kind seed `overlay` over the schema-example base
+     * (`overlay › example › absent`). `undefined` when `cardKind` is not
+     * declared in this quill's schema.
      *
      * 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.
+     * for the bare schema seed.
      */
     seedCard(card_kind: string, overlay: Record<string, unknown> | undefined): Card | undefined;
     /**
-     * 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
-     * with both an `example` and a `default` renders its example. See
-     * `prose/canon/SCHEMAS.md` § "Document seeding".
+     * 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 as
+     * `default:`, else the field's blank). A field with both renders its example.
      */
     seedDocument(): Document;
     /**
      * 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.
+     * `$kind: main` card of [`seedDocument`](Self::seed_document) alone.
      */
     seedMain(): Card;
     /**
-     * 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.
+     * Flatten this quill back into its canonical file tree, the inverse of
+     * [`fromTree`](Self::from_tree). Keys are `"/"`-joined relative paths.
      *
      * This is how a quill crosses a WASM linear-memory boundary as data: a
-     * `Quill` built in one build (e.g. the Typst-less `@quillmark/wasm/core`)
-     * cannot be passed to an engine in another (separate linear memories), so
+     * `Quill` built in one build cannot be passed to an engine in another, so
      * `@quillmark/wasm/runtime` re-feeds this tree to the backend build's
-     * `Quill.fromTree` on demand. Keys are `"/"`-joined relative paths,
-     * matching what `fromTree` accepts.
+     * `Quill.fromTree` on demand.
      */
     toTree(): Map<string, Uint8Array>;
     /**
      * 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
-     * `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`
-     * (schema key order is display order).
+     * (empty when the document is valid). Forwards the canonical
+     * `validation::*` diagnostics the engine emits, including the non-fatal
+     * `validation::must_fill` warning per `!must_fill` marker left behind.
      */
     validate(doc: Document): Diagnostic[];
     /**
-     * The *declared* backend identifier (`config.backend`, e.g. `"typst"`).
-     * Intent, not a resolved capability: capability (`supportedFormats` /
-     * `supportsCanvas`) is read from the engine.
+     * The *declared* backend identifier (e.g. `"typst"`): intent, not a
+     * resolved capability. Capability 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
-     * resolved-backend capability read from the engine
-     * (`Quillmark.supportedFormats`), not part of this snapshot.
+     * `quill:` keys. Pure config: output formats are a resolved-backend
+     * capability read from `Quillmark.supportedFormats`, not part of this.
      */
     readonly metadata: QuillMetadata;
     /**
-     * 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
-     * ordering contract. Returns the `QuillSchema` shape.
+     * Document schema for the quill: the user-fillable fields plus their `ui`
+     * hints. Key order in `fields`/`properties` is declaration order, the
+     * ordering contract.
      */
     readonly schema: QuillSchema;
 }
 
 /**
- * Export a canonical `Content` content to its markdown projection: the pure
- * on-demand codec behind `exportMarkdown(card.body)`. Throws if `rt` is not a
+ * Export canonical `Content` to its markdown projection. Throws if `rt` is not
  * canonical content.
  */
 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
- * 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").
+ * 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 a canonical `Content` content: the pure,
- * document-free codec. Pair with `overwrite(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.
+ * 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.
  */
 export function importMarkdown(markdown: string): Content;
 
 /**
  * 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`.
+ * 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`.
  */
 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
- * one path serializer, so a consumer routes on segments instead of regexing
- * the string. Throws on a malformed path.
+ * Parse a canonical document-model `Diagnostic.path` (`cards.<kind>[<i>].<field>`,
+ * `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.
  */
 export function parseDocPath(path: string): DocPathSeg[];
 
 /**
- * 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,
- * md)` fuses this with the store for atomicity. Throws on an over-nested
- * markdown input or a non-content `base`.
+ * 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`.
  */
 export function rebase(base: Content, markdown: string): { content: Content; delta: Delta };
 
 /**
- * Runs at instantiation (the wasm-bindgen start section): installs the panic
- * hook, so a Rust panic reaches the console as a stack trace rather than
- * `unreachable`.
- *
- * Not the package's `init`. That name belongs to the hand-written runtime,
- * which owns instantiation itself (`runtime/runtime.js`); this runs as part of
- * the instantiation it awaits.
+ * Runs at instantiation, so a Rust panic reaches the console as a stack trace
+ * rather than `unreachable`. Not the package's `init` — that name belongs to
+ * the hand-written runtime, which owns instantiation itself.
  */
 export function start(): void;
 
@@ -1091,12 +982,14 @@ export interface InitOutput {
     readonly document__commitFields: (a: number, b: number, c: number, d: number, e: number) => void;
     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__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_blueprintInstruction: (a: number, b: number, c: number) => void;
     readonly document_bodyMarkdown: (a: number, b: number, c: number) => void;
     readonly document_card: (a: number, b: number, c: number) => void;
     readonly document_cardCount: (a: number) => number;
+    readonly document_cardPath: (a: number, b: number, c: number) => void;
     readonly document_cards: (a: number, b: number) => void;
     readonly document_clone: (a: number) => number;
     readonly document_currentStorageVersion: (a: number) => void;
@@ -1116,6 +1009,7 @@ export interface InitOutput {
     readonly document_moveCard: (a: number, b: number, c: number, d: number) => void;
     readonly document_new: (a: number, b: number, c: number) => void;
     readonly document_overwrite: (a: number, b: number, c: number, d: number) => void;
+    readonly document_pathFor: (a: number, b: number, c: number) => void;
     readonly document_quillRef: (a: number, b: number) => void;
     readonly document_quillRefHint: (a: number) => void;
     readonly document_removeCard: (a: number, b: number, c: number) => void;