@quillmark/wasm 0.94.0 → 0.96.0

package/core/wasm.d.ts

@@ -17,7 +17,7 @@ export type PayloadItem =
     /**
      * Paths to `!must_fill` markers nested *inside* `value` (the `value`
      * projection itself is fill-free). Absent when the field has no nested
-     * placeholders. Preserved across `pushCard` / `makeCard`.
+     * placeholders. Preserved across `insertCard` / `makeCard`.
      */
     nestedFills?: PathStep[][];
 }
@@ -27,7 +27,7 @@ export type PayloadItem =
  * 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 `pushCard` / `insertCard` accept); every `Card` is a valid `CardInput`,
+ * (which `insertCard` accepts); 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
@@ -44,19 +44,19 @@ export interface Card {
     seed?: Record<string, unknown>;
     payloadItems: PayloadItem[];
     /**
-     * The card body as canonical `RichText` — the source-of-truth content model.
-     * Always this corpus shape on read, never a markdown string. For the markdown
+     * 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`.
      */
-    body: RichText;
+    body: Content;
 }
 
 /**
  * A card written *into* a document — the input twin of `Card`, accepted by
- * `Document.pushCard` / `Document.insertCard`. Like `Card` but `body` also
- * takes a markdown `string` (imported to the corpus, so a markdown / LLM writer
- * needn't build the `RichText` shape), and every field but `kind` is optional —
+ * `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`.
  */
@@ -67,26 +67,26 @@ export interface CardInput {
     ext?: Record<string, unknown>;
     seed?: Record<string, unknown>;
     payloadItems?: PayloadItem[];
-    body?: RichText | string;
+    body?: Content | string;
 }
 
 /**
- * Canonical richtext corpus — 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.
- * Mirrors `quillmark_richtext::serial`'s canonical JSON encoding.
+ * Mirrors `quillmark_content::serial`'s canonical JSON encoding.
  */
-export interface RichText {
+export interface Content {
     text: string;
-    lines: RichTextLine[];
-    marks: RichTextMark[];
-    islands: RichTextIsland[];
+    lines: ContentLine[];
+    marks: ContentMark[];
+    islands: ContentIsland[];
 }
 
-/** One `\n`-separated segment of `RichText.text`, in order. */
-export type RichTextLine = {
-    containers: RichTextContainer[];
+/** One `\n`-separated segment of `Content.text`, in order. */
+export type ContentLine = {
+    containers: ContentContainer[];
     /** A within-block hard line break rather than a new block. Omitted (false) in the common case. */
     continues?: boolean;
 } & (
@@ -98,32 +98,68 @@ export type RichTextLine = {
 );
 
 /** An ancestor block a line nests inside, outermost first. */
-export type RichTextContainer =
+export type ContentContainer =
 | { container: "list_item"; ordered: boolean; start: number; ordinal: number }
 | { container: "quote" };
 
-/** A mark over char range `[start, end)` into `RichText.text`. */
-export type RichTextMark = { start: number; end: number } & (
+/** A mark over char range `[start, end)` into `Content.text`. */
+export type ContentMark = { start: number; end: number } & (
 | { type: "strong" | "emph" | "underline" | "strike" | "code" }
 | { type: "link"; url: string }
 | { type: "anchor"; id: string }
 | { type: string; attrs: unknown }
 );
 
-/** A structured object (table, figure, …) occupying one island slot in `RichText.text`. */
-export interface RichTextIsland {
+/** 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`. */
+export interface TableCell {
+    text: string;
+    marks: ContentMark[];
+}
+
+/** `props` of a `type: "table"` island: a pipe table normalized to one column
+ * count that `header`, every row of `rows`, and `aligns` all share. */
+export interface TableProps {
+    header: TableCell[];
+    rows: TableCell[][];
+    /** Per-column alignment, one entry per column. */
+    aligns: ("none" | "left" | "center" | "right")[];
+}
+
+/** `props` of a `type: "image"` island. */
+export interface ImageProps {
+    url: string;
+    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` — key off `type` and read `props` as the matching shape. */
+export type ContentIsland = {
     id: string;
-    type: string;
-    props: unknown;
     /** How faithfully the markdown projection can carry this island. */
     loss: "lossless" | "degraded" | "unrepresentable";
-}
+} & (
+| { type: "table"; props: TableProps }
+| { type: "image"; props: ImageProps }
+| { type: string; props: unknown }
+);
 
 /**
- * A richtext write address. 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` richtext field; `{ card: 2, field: "intro" }` a card field.
+ * 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
+ * rule. A bare number is *not* an addr (`{ card: 2 }` is the self-documenting
+ * spelling), so no third navigation idiom re-fragments the surface.
  */
 export interface Addr {
     card?: number;
@@ -131,7 +167,17 @@ export interface Addr {
 }
 
 /**
- * A text-splice change set over the USV corpus (CodeMirror `ChangeSet`
+ * 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.
+ */
+export interface CardAddr {
+    card?: number;
+}
+
+/**
+ * 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`.
  */
@@ -143,9 +189,9 @@ export interface Delta {
 export type Assoc = "before" | "after";
 
 /**
- * A mark edit in post-text-delta coordinates. `add` / `remove` carry the
- * `RichTextMark` vocabulary (`{ type, … }`); `removeAnchor` drops one identity
- * anchor by id.
+ * 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.
  */
 export type MarkOp =
 | ({ op: "add" | "remove"; start: number; end: number } & (
@@ -156,7 +202,13 @@ export type MarkOp =
 ))
 | { op: "removeAnchor"; id: string };
 
-/** A line/block edit. `split`/`join` splice `\n`; `setKind`/`setContainers` touch metadata. */
+/**
+ * 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
+ * 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 }
@@ -165,10 +217,11 @@ export type LineOp =
 | { kind: "heading"; level: number }
 | { kind: "code"; lang?: string }
 ))
-| { op: "setContainers"; line: number; containers: RichTextContainer[] };
+| { op: "setContainers"; line: number; containers: ContentContainer[] }
+| { op: "setContinues"; line: number; continues: boolean };
 
 /**
- * A committed corpus edit bundle for `applyChange`: a text `delta` (default no
+ * A committed content edit bundle for `applyChange`: a text `delta` (default no
  * text change), then `lineOps`, then `markOps` (mark ranges are in post-delta
  * coordinates). Every field is optional.
  */
@@ -180,6 +233,70 @@ 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`
+ * (`kind: null` is the unknown-kind `cards[i]` form), or a `field`; the tail is
+ * `field` / `index` / a terminal `body`.
+ */
+export type DocPathSeg =
+| { seg: "main" }
+| { seg: "card"; kind: string | null; index: number }
+| { seg: "field"; name: string }
+| { seg: "index"; index: number }
+| { seg: "body" };
+
+
+
+/** The commitment-ladder rung that produced a `ResolvedField.value`. */
+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
+ * 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`.
+ */
+export interface ResolvedField {
+    name: string;
+    value: unknown;
+    source: FieldSource;
+}
+
+/**
+ * The main card's resolved rows in declaration order, plus its body row —
+ * `null` when the main enables no body.
+ */
+export interface ResolvedMain {
+    fields: ResolvedField[];
+    body: ResolvedField | null;
+}
+
+/**
+ * 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.
+ */
+export interface ResolvedCard {
+    kind: string | null;
+    index: number;
+    fields: ResolvedField[];
+    body: ResolvedField | null;
+}
+
+/**
+ * The resolved-value view (`Quill.resolve`): the main card and every
+ * composable card. Value and provenance only — completeness and errors stay
+ * `Quill.validate`.
+ */
+export interface Resolved {
+    main: ResolvedMain;
+    cards: ResolvedCard[];
+}
+
+
+
 /** 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. */
@@ -190,9 +307,23 @@ export interface QuillFieldUi {
     multiline?: boolean;
 }
 
+/** 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. */
+export interface QuillGroupUi {
+    title?: string;
+}
+
 /** 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). */
+    groups?: Record<string, QuillGroupUi>;
 }
 
 /** Body namespace for a card (main or named card kind). */
@@ -213,7 +344,7 @@ export interface QuillCardBody {
  * zero-fills the field). There is no separate `required` axis.
  */
 export interface QuillFieldSchema {
-    type: "string" | "number" | "integer" | "boolean" | "array" | "object" | "datetime" | "richtext" | "plaintext" | "enum";
+    type: "string" | "number" | "integer" | "boolean" | "array" | "object" | "date" | "datetime" | "richtext" | "plaintext" | "enum";
     description?: string;
     default?: unknown;
     example?: unknown;
@@ -294,28 +425,16 @@ export class Document {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Build a composable card of `kind`, typed-commit `fields` onto it, set its
-     * body from optional markdown, and append it — the ABI under
-     * `writer.addCard`. Fuses `makeCard` + typed commit + `pushCard`
-     * transactionally: the card is committed in full before it joins the
-     * document, so a rejected field (or an invalid kind or body) leaves the
-     * document untouched. Field errors throw the same per-field diagnostic
-     * bundle as [`commitFields`](Self::commit_fields), including an
-     * `[EditError::UnknownField]` per undeclared name; an invalid kind or body
-     * throws a single-entry bundle keyed `$kind` / `$body`.
-     */
-    addCard(quill: Quill, kind: string, fields?: Record<string, unknown>, body?: string): void;
-    /**
-     * **Apply** a committed corpus edit `bundle` (`{ delta?, lineOps?, markOps? }`)
+     * **Apply** a committed content edit `bundle` (`{ delta?, lineOps?, markOps? }`)
      * at `addr` — the editor splice: text delta first, then line ops, then mark
-     * ops (mark ranges in post-delta coordinates), each all-or-nothing. An absent
+     * 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.
      *
      * 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).
      */
-    applyChange(addr: Addr, bundle: ChangeBundle): void;
+    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
@@ -323,61 +442,22 @@ export class Document {
      * uniform.
      */
     static blueprintInstruction(quill_name: string): string;
-    clone(): Document;
     /**
-     * Typed field write on the composable card at `index` — the card-indexed
-     * twin of [`commitField`](Document::commit_field). Resolves the field's
-     * type from the card's `$kind` schema in `quill` and strict-commits it.
-     *
-     * Throws `[EditError::IndexOutOfRange]` when `index` is out of range, and
-     * the same typed-mismatch / name errors as `commitField` — including
-     * `[EditError::UnknownField]` for a field the card-kind schema does not
-     * declare (an unknown `$kind` has no schema, so every field is undeclared).
-     */
-    commitCardField(quill: Quill, index: number, name: string, value: any): void;
-    /**
-     * Batched twin of [`commitCardField`](Document::commit_card_field):
-     * typed-commit several fields on the card at `index` atomically, resolving
-     * each field's type from the card's `$kind` schema in `quill`. All-or-nothing
-     * with the same per-field-diagnostic contract as
-     * [`commitFields`](Document::commit_fields), including an
-     * `[EditError::UnknownField]` diagnostic per undeclared name. Throws
-     * `[EditError::IndexOutOfRange]` when `index` is out of range.
-     */
-    commitCardFields(quill: Quill, index: number, fields: Record<string, unknown>): void;
-    /**
-     * Typed field write on the main card, resolving the field's schema `type`
-     * from `quill` — the one write verb for **every** field type (richtext,
-     * scalar, array, object). The schema carries the `inline` constraint, so no
-     * type token or flag is passed. A richtext-typed field stores the canonical
-     * corpus, so identity marks (anchors, island ids) and corpus-only marks
-     * (e.g. `underline`) live on it and survive compiles and the storage DTO.
-     * Values use the encoding the seam already speaks: a corpus object
-     * or markdown string for richtext, a scalar/array/object otherwise.
-     *
-     * A field declared in the schema is strict-committed — a mismatch throws
-     * now, not at render. A name the schema does not declare throws
-     * `[EditError::UnknownField]` rather than falling to the opaque store: on
-     * the typed path it is a typo. Use [`setField`](Document::set_field) when
-     * opaque storage is the intent. Also throws `[EditError::FieldConform]` /
-     * `[EditError::FieldRichtextDecode]` / `[EditError::FieldRichtextNotInline]`
-     * on a typed mismatch and `[EditError::InvalidFieldName]` on a malformed
-     * name.
-     *
-     * The `quill` handle is passed per call because a `Document` carries only a
-     * `$quill` reference, not the resolved schema.
+     * 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.
      */
-    commitField(quill: Quill, name: string, value: any): void;
+    card(index: number): Card;
     /**
-     * Batched twin of [`commitField`](Document::commit_field): typed-commit
-     * several main-card fields atomically, resolving each field's schema `type`
-     * from `quill`. All-or-nothing with the same per-field-diagnostic error
-     * contract as [`setFields`](Document::set_fields) — nothing is applied on
-     * error and the thrown error's `diagnostics` carry one entry per offending
-     * field, including an `[EditError::UnknownField]` for any name the schema
-     * does not declare, so a whole-form submit sees every typo in one pass.
+     * The index of the first composable card whose `$id` equals `id`, or
+     * `undefined` when none carries it. Resolves the canonical durable address
+     * without a hand-rolled scan over [`cards`](Self::cards); `$id` is
+     * non-unique by design, so the first match wins.
      */
-    commitFields(quill: Quill, fields: Record<string, unknown>): void;
+    cardIndexById(id: string): number | undefined;
+    clone(): Document;
     /**
      * Schema version this build writes via [`toJson`](Document::to_json).
      * Tracks the `Document` model version (not the running crate version):
@@ -417,30 +497,54 @@ export class Document {
      */
     static fromMarkdown(markdown: string): Document;
     /**
-     * Read a main-card field's stored value — the raw payload value (a corpus
-     * object for a richtext field, a scalar/array/object otherwise), or
-     * `undefined` when the field is absent. The quill-free read: reads need no
-     * schema, so they live on `Document`, not the typed writer. For the markdown
-     * projection of a richtext value use [`getMarkdown`](Self::get_markdown).
+     * Read the value at `addr` — the raw stored 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`. Reads need no schema, so they live on
+     * `Document`, not the typed writer; for the markdown projection of a
+     * richtext value use [`getMarkdown`](Self::get_markdown).
+     */
+    get(addr: Addr | string): unknown;
+    /**
+     * 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.
      */
-    get(name: string): any;
+    getExt(addr?: CardAddr): Record<string, unknown> | undefined;
     /**
-     * The markdown projection of a main-card field (`name` given) or the main
-     * body (`name` omitted) — the on-demand, lossy export (corpus-only marks do
-     * not survive markdown), returning `""` for an absent field. Re-coins,
-     * lazily and by name, the projection the eager `fieldMarkdown` /
-     * `bodyMarkdown` getters dropped in #925; call it only when markdown is what
-     * you need out.
+     * 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.
      */
-    getMarkdown(name?: string): string;
+    getExtNamespace(addr: CardAddr, ns: string): unknown;
     /**
-     * Insert a card at `index` (must be in `0..=cards.length`). Accepts a
-     * `CardInput` (see [`pushCard`](Self::push_card)).
+     * 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
+     * schema-plane `quill.reader(doc).get(field)`, which interprets by declared
+     * type (#978). An out-of-range `addr.card` throws.
      */
-    insertCard(index: number, card: CardInput): void;
+    getMarkdown(addr?: CardAddr): string;
     /**
-     * **Install** a richtext value at `addr` — **value semantics**, corpus only.
-     * Stores exactly `rt` (a canonical `RichText` corpus object); the identity
+     * 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.
+     */
+    insertCard(card: CardInput, at?: number): void;
+    /**
+     * **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
      * [`revise`](Document::revise); the cold-import path is spelled at the call
@@ -448,9 +552,16 @@ export class Document {
      * source.
      *
      * Throws on an out-of-range card, a malformed field name, or an `rt` that is
-     * not a canonical corpus object.
+     * not a canonical content object.
+     */
+    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
+     * marked) and for a body address (a body is never a fill). Only an
+     * out-of-range `addr.card` throws.
      */
-    install(addr: Addr, rt: RichText): void;
+    isFill(addr: Addr | string): boolean;
     /**
      * Replace this document's contents **in place** from a versioned storage
      * DTO string — the mutating twin of the static
@@ -465,10 +576,10 @@ export class Document {
     loadJson(json: string): void;
     /**
      * Build a fresh `Card` from a kind and a flat field map — the ergonomic
-     * constructor for `pushCard` / `insertCard`. `fields` is an optional
+     * 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
-     * `pushCard` / `insertCard`, not here.
+     * `insertCard`, not here.
      */
     static makeCard(kind: string, fields?: Record<string, unknown>, body?: string): Card;
     /**
@@ -484,14 +595,6 @@ export class Document {
      * Throws on an invalid quill reference. Mirrors Python `Document(quill_ref)`.
      */
     constructor(quill_ref: string);
-    /**
-     * Append a card to the end of the card list. 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.
-     */
-    pushCard(card: CardInput): void;
     /**
      * The canonical `$quill` reference grammar as author-facing text. Core is
      * the single source of truth: drive schema `describe` and validation
@@ -502,54 +605,32 @@ export class Document {
     static quillRefHint(): string;
     removeCard(index: number): Card | undefined;
     /**
-     * Remove the `$ext` map from the composable card at `index` *entirely*,
-     * returning the previous map or `undefined`. Throws if out of range.
-     * Prefer `removeCardExtNamespace` to clear only one consumer's slot.
-     */
-    removeCardExt(index: number): Record<string, unknown> | undefined;
-    /**
-     * Remove `namespace` from the composable card's `$ext` map, returning the
-     * value stored there or `undefined`; clears `$ext` entirely once empty.
-     * The card-indexed twin of `removeExtNamespace`. Throws if out of range.
-     */
-    removeCardExtNamespace(index: number, namespace: string): any;
-    /**
-     * Remove a field on the card at `index`. Returns the removed value or
-     * `undefined`. Throws if `index` is out of range or `name` is invalid.
-     */
-    removeCardField(index: number, name: string): any;
-    /**
-     * Remove the `$ext` map from the main card *entirely*, returning the
-     * previous map or `undefined`. This is a blunt escape hatch that discards
-     * every namespace at once — prefer `removeExtNamespace` to clear only your
-     * own slot while leaving sibling consumers' state intact.
+     * 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.
      */
-    removeExt(): Record<string, unknown> | undefined;
+    removeExt(addr?: CardAddr): Record<string, unknown> | undefined;
     /**
-     * Remove `namespace` from the main card's `$ext` map, returning the value
-     * stored there or `undefined`. This is the recommended way to clear `$ext`
-     * state: sibling namespaces survive, and when the last namespace is removed
-     * the `$ext` entry is dropped entirely (not left as `$ext: {}`).
+     * Remove `$ext[ns]` on the card `addr` targets, returning its value or
+     * `undefined`; drops `$ext` once empty. `addr` is a card address (absent =
+     * main). Preserves sibling namespaces. Throws on a present `field` or an
+     * out-of-range card.
      */
-    removeExtNamespace(namespace: string): any;
+    removeExtNamespace(addr: CardAddr, ns: string): any;
     /**
-     * Remove a payload field on the main card, returning the removed value or
-     * `undefined`. Throws if `name` does not match `[A-Za-z_][A-Za-z0-9_]*`.
+     * 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.
      */
-    removeField(name: string): any;
+    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.
+     * overlay or `undefined`; drops `$seed` entirely once empty. Sibling kinds
+     * survive. `$seed` is main-only, so this takes no address.
      */
     removeSeedNamespace(card_kind: string): any;
-    /**
-     * **Deprecated** — alias for `revise({}, markdown)`, kept one release cycle.
-     * Revise the main card's body from a markdown string (edit semantics: a
-     * `diff_import` that rebases surviving anchors). Discards the text delta;
-     * call [`revise`](Document::revise) to receive it.
-     */
-    replaceBody(body: string): void;
     /**
      * **Revise** the richtext value at `addr` from a markdown string — **edit
      * semantics**, the default write path, returning the text [`Delta`]. Imports
@@ -559,9 +640,9 @@ export class Document {
      * 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-corpus field value, or an over-nested markdown input.
+     * non-content field value, or an over-nested markdown input.
      */
-    revise(addr: Addr, markdown: string): Delta;
+    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 —
@@ -570,30 +651,13 @@ export class Document {
      */
     static schemaVersionOf(json: string): string | undefined;
     /**
-     * Replace the `$ext` map on the composable card at `index`. Throws if out
-     * of range or `value` is not a plain object. Named to mirror `setExt` on
-     * the main card; `setCardExtNamespace` is the sibling-safe alternative.
-     */
-    setCardExt(index: number, value: any): void;
-    /**
-     * Merge `value` into the composable card's `$ext` map under `namespace`,
-     * preserving sibling namespaces. The card-indexed twin of `setExtNamespace`.
-     * Throws if out of range or `value` cannot be serialized.
-     */
-    setCardExtNamespace(index: number, namespace: string, value: any): void;
-    /**
-     * Set a field on the card at `index` — the card-indexed twin of
-     * [`setField`](Document::set_field). Stores the value opaquely.
-     * Throws if `index` is out of range, `name` is reserved or invalid.
-     */
-    setCardField(index: number, name: string, value: any): void;
-    /**
-     * Batched twin of [`setCardField`](Document::set_card_field): set
-     * several fields on the card at `index` atomically. Same all-or-nothing,
-     * one-diagnostic-per-field contract as [`setFields`](Document::set_fields).
-     * Throws if `index` is out of range.
+     * 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.
      */
-    setCardFields(index: number, fields: Record<string, unknown>): void;
+    seedOverlay(kind: string): Record<string, unknown> | undefined;
     /**
      * Replace the kind of the card at `index`. Payload and body are untouched;
      * schema-aware migration is the caller's responsibility.
@@ -601,50 +665,61 @@ export class Document {
      */
     setCardKind(index: number, new_kind: string): void;
     /**
-     * Replace the opaque `$ext` map on the main card. `value` must be a plain
-     * object; throws otherwise. `$ext` carries out-of-band consumer state and
-     * never reaches the rendered output. Pass `{}` to record an explicit
-     * empty `$ext`.
+     * Replace the QUILL reference string. Throws if `ref_str` is invalid.
      */
-    setExt(value: any): void;
+    setQuillRef(ref_str: string): void;
     /**
-     * Merge `value` into the main card's `$ext` map under `namespace`, creating
-     * the map when absent and replacing any existing value at that key. Sibling
-     * namespaces are preserved, so independent consumers (`$ext.editor`,
-     * `$ext.agent`, …) don't clobber each other.
+     * 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.
      */
-    setExtNamespace(namespace: string, value: any): void;
+    storeExt(addr: CardAddr, value: any): void;
     /**
-     * Update a payload field on the main card. Clears any existing `!must_fill` marker.
-     *
-     * Throws if `name` does not match `[A-Za-z_][A-Za-z0-9_]*`.
+     * 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.
      */
-    setField(name: string, value: any): void;
+    storeExtNamespace(addr: CardAddr, ns: string, value: any): void;
     /**
-     * Set several main-card payload fields atomically from a plain object,
-     * clearing any `!must_fill` marker on each key. Nothing is applied on
-     * error; the thrown error's `diagnostics` array carries one entry per
-     * offending field (`path` = field name), so externally-sourced names
-     * (database columns, form keys) surface every violation in one pass.
-     * Mirrors Python `set_fields`.
+     * 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` / `install` / `writer.setBody`. Throws on
+     * an out-of-range card or a malformed name.
      */
-    setFields(fields: Record<string, unknown>): void;
+    storeField(addr: Addr | string, value: any): void;
     /**
-     * Update a payload field on the main card and mark it as `!must_fill`.
-     * Throws on invalid name (see [`setField`](Document::set_field)).
+     * 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.
      */
-    setFill(name: string, value: any): void;
+    storeFields(addr: CardAddr, fields: Record<string, unknown>): void;
     /**
-     * Replace the QUILL reference string. Throws if `ref_str` is invalid.
+     * 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).
      */
-    setQuillRef(ref_str: string): void;
+    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. Sets the starting values
-     * new cards of that kind spawn with. Throws if `overlay` cannot be
-     * serialized or nests too deep.
+     * 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.
      */
-    setSeedNamespace(card_kind: string, overlay: any): void;
+    storeSeedNamespace(card_kind: string, overlay: any): void;
     /**
      * Serialize this document to a versioned storage DTO string.
      *
@@ -697,14 +772,25 @@ export class Quill {
      * canonical shape.
      */
     static fromTree(tree: Map<string, Uint8Array>): Quill;
+    /**
+     * 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 rides the `fields` map under the `$body` key.
+     *
+     * 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`.
+     */
+    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.pushCard` / `insertCard`.
+     * straight into `Document.insertCard`.
      *
-     * Pass `document.main.seed?.[cardKind]` as `overlay` so a card added to a
+     * 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.
@@ -776,19 +862,28 @@ export class Quill {
 }
 
 /**
- * Export a canonical `RichText` corpus to its markdown projection — the pure
- * codec that replaces the eager `bodyMarkdown` / `fieldMarkdown` precomputes
- * (`exportMarkdown(card.body)`). Throws if `rt` is not a canonical corpus.
+ * 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.
  */
-export function exportMarkdown(rt: RichText): string;
+export function exportMarkdown(rt: Content): string;
 
 /**
- * Import a markdown string to a canonical `RichText` corpus — the pure,
+ * 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").
+ */
+export function formatDocPath(segs: DocPathSeg[]): string;
+
+/**
+ * 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.
  */
-export function importMarkdown(markdown: string): RichText;
+export function importMarkdown(markdown: string): Content;
 
 /**
  * Initialize the WASM module with panic hooks for better error messages
@@ -796,7 +891,7 @@ export function importMarkdown(markdown: string): RichText;
 export function init(): void;
 
 /**
- * Map a base corpus position through a `delta` to its new position — the pure
+ * Map a base content position through a `delta` to its new 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`.
@@ -804,10 +899,19 @@ export function init(): void;
 export function mapPos(delta: Delta, pos: number, assoc: Assoc): number;
 
 /**
- * Rebase `markdown` onto a `base` corpus — the pure, document-free twin of
- * `revise`: cold-import + `diff_import`, returning the new `corpus` and the
+ * 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.
+ */
+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` (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-corpus `base`.
+ * atomicity. Throws on an over-nested markdown input or a non-content `base`.
  */
-export function rebase(base: RichText, markdown: string): { corpus: RichText; delta: Delta };
+export function rebase(base: Content, markdown: string): { content: Content; delta: Delta };