@quillmark/wasm 0.114.0 → 0.116.0

package/core/wasm.d.ts

@@ -13,13 +13,6 @@ export type PayloadItem =
     type: "field";
     key: string;
     value: unknown;
-    fill?: boolean;
-    /**
-     * 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 `insertCard`.
-     */
-    nestedFills?: PathStep[][];
 }
 | { type: "comment"; text: string; inline?: boolean };
 
@@ -27,9 +20,9 @@ export type PayloadItem =
  * 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), `quill` (`$quill` `name@version`, main card only), `ext`
- * (`$ext`), and `seed` (the `$seed` per-kind overlay map, main card only).
+ * `$` system entries are hoisted to named fields: `kind` (the `$kind`),
+ * `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 {
@@ -73,9 +66,9 @@ export interface Content {
 }
 
 /** One `\n`-separated segment of `Content.text`, in order. `kind` is a closed
- * set: a role outside it is refused wherever content is decoded. Every role
- * spells its payload in `attrs`, so `kind === "heading"` narrows `attrs` to
- * `{ level: number }` with no guard. */
+ * set: `island` reads as `para`, and any other role outside it is refused
+ * wherever content is decoded. Every role spells its payload in `attrs`, so
+ * `kind === "heading"` narrows `attrs` to `{ level: number }` with no guard. */
 export type ContentLine = {
     containers: ContentContainer[];
     /** A within-block hard line break rather than a new block. Omitted (false) in the common case. */
@@ -87,7 +80,6 @@ export type ContentLineKind =
 | { kind: "para" }
 | { kind: "heading"; attrs: { level: number } }
 | { kind: "code"; attrs?: { lang?: string } }
-| { kind: "island" }
 | { kind: "rule" };
 
 /** An ancestor block a line nests inside, outermost first. Closed like
@@ -158,14 +150,10 @@ export interface ImageProps {
     alt: string;
 }
 
-/** How faithfully the markdown projection can carry an island. */
-export type ContentLossClass = "lossless" | "degraded" | "unrepresentable";
-
 /** A structured object occupying one island slot in `Content.text`. `type` is a
  * closed set, so `type === "table"` narrows `props` to `TableProps`. */
 export type ContentIsland = {
     id: string;
-    loss: ContentLossClass;
 } & (
 | { type: "table"; props: TableProps }
 | { type: "image"; props: ImageProps }
@@ -237,10 +225,12 @@ export type MarkOp =
  * metadata. `setContinues` sets or clears a line's within-block hard-break flag
  * (`ContentLine.continues`); `continues: true` lands as `false` on line 0, which
  * nothing precedes, on a line whose containers differ from the line above, and
- * on one following a heading, island or rule, each a block of one line.
- * `setKind` lands a kind the line's text contradicts — `island` or `rule` over
+ * on one following a heading, a rule or a block island's line, each a block of
+ * one line. `setKind` lands a kind the line's text contradicts — `rule` over
  * prose, `code` over a slot — as `para`, which is what re-importing the line's
- * own markdown yields. Read the content back to see where an op settled.
+ * own markdown yields, and reads an `island` the union does not offer as the
+ * `para` that spelling projects. Read the content back to see where an op
+ * settled.
  */
 export type LineOp =
 | { op: "split"; at: number }
@@ -264,22 +254,16 @@ export type LineOp =
  * 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.
- *
- * A `set` stores the `loss` it is given; nothing re-derives the class from the
- * new `props`.
+ * island whole. 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.
  *
  * An island is *inline* (a slot inside a paragraph) or a **block** (that slot
- * alone on a line under `kind: "island"`), and for a slot alone on a line the
- * type settles which: markdown writes a `table` as a block and an image inline,
- * so the line's `kind` is read off the type and a `setKind` spelling it
- * otherwise does not survive. Landing a block island is one bundle of all three
- * channels, in the order they apply: `delta` inserts the `\n` that opens the
- * line, `islandOps` inserts the slot, `lineOps` tags the line
- * `{ op: "setKind", kind: "island" }`. `{ op: "split" }` cannot open that line,
- * since line ops run after island ops.
+ * alone on its own line), and the type settles which: markdown writes a `table`
+ * as a block and an image inline. Both lines read `kind: "para"` — the block is
+ * the slot's markup, not a role the line carries — so landing a block island is
+ * two channels: `delta` inserts the `\n` that opens the line, `islandOps`
+ * inserts the slot. `{ op: "split" }` cannot open that line, since line ops run
+ * after island ops.
  *
  * A `table` has no inline placement: markdown writes it as a block, so an
  * `insert` whose `at` is not an empty line throws, as does a `set` retyping an
@@ -366,11 +350,11 @@ export interface ResolvedMain {
 
 /**
  * One composable card's resolved rows in declaration order, with its authored
- * `kind` (`null` for an unknown-kind card), its document-array `index`, and its
+ * `kind` (an undeclared one included), its document-array `index`, and its
  * body row: `null` when the kind enables no body.
  */
 export interface ResolvedCard {
-    kind: string | null;
+    kind: string;
     index: number;
     fields: ResolvedField[];
     body: ResolvedField | null;
@@ -378,7 +362,7 @@ export interface ResolvedCard {
 
 /**
  * The resolved-value view (`Quill.resolve`): the main card and every composable
- * card. Value and provenance only; completeness stays `Quill.validate`'s.
+ * card. Value and provenance only; diagnostics stay `Quill.validate`'s.
  */
 export interface Resolved {
     main: ResolvedMain;
@@ -390,7 +374,6 @@ export interface Resolved {
 /** 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;
@@ -398,9 +381,10 @@ export interface QuillFieldUi {
      *  conventional label of its own. */
     blank_title?: string;
     /** The control the field asks for, where the shape admits more than one.
-     *  A request, not a contract: a consumer that cannot draw it falls back to
-     *  its own choice for the type. `"table"` is valid only on an `array`
-     *  whose `items` is an `object`. */
+     *  `"table"` is valid only on an `array` whose `items` is an `object`.
+     *  Every column is a leaf, a contract refused at load as
+     *  `quill::table_column_not_flat`. Drawing the grid is a request: a
+     *  consumer that cannot falls back to its own choice for the type. */
     layout?: "table";
 }
 
@@ -413,63 +397,52 @@ export interface QuillGroupUi {
 
 /** UI layout hints for a card (main or named card kind). */
 export interface QuillCardUi {
-    title?: string;
     /** 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 body content, shown on the blueprint's `# body e.g.` line above the body. */
     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[];
 }
 
+export type QuillFieldType = "string" | "number" | "integer" | "boolean" | "array" | "object" | "date" | "datetime" | "richtext" | "plaintext" | "enum" | "matrix";
+
 /** Schema entry for a single field declared in a quill's `Quill.yaml`.
  *
- * One declaration, and no `required` key. `default` and `example` say what the
- * cell holds, and `default`'s absence is the obligation: a field nobody
- * declared a value for carries a `!must_fill` marker in the blueprint and warns
- * `validation::must_fill` while the document leaves it unauthored. Neither
- * gates render: an absent field blank-fills.
+ * `default` is the value an unanswered cell renders; `example` documents shape
+ * and never renders. An absent field without a `default` blank-fills.
  */
 export interface QuillFieldSchema {
-    type: "string" | "number" | "integer" | "boolean" | "array" | "object" | "date" | "datetime" | "richtext" | "plaintext" | "enum" | "matrix";
+    /** A trailing `?` marks the cell optional: unanswered, it renders `none`
+     *  rather than its type's blank, and it never carries a `default`. A
+     *  consumer offers a way back to unanswered (`removeField`) on such a cell. */
+    type: QuillFieldType | `${Exclude<QuillFieldType, "object" | "matrix">}?`;
+    /** The field's label, a literal. Absent, the consumer humanizes the key
+     *  (`memo_for` → "Memo For"). Never present on an array's `items`. */
+    title?: string;
     description?: string;
     default?: unknown;
     example?: unknown;
     /** The closed set of allowed values. Required on `type: "enum"`, and valid
      *  nowhere else. */
     values?: string[];
-    /** Per-member field sets on a card-level `type: "enum"` field, keyed by
-     *  member: the fields that exist only where the discriminant holds that
-     *  member. Declaring it makes the field rest as a container,
-     *  `{value: <member>, …that member's fields}`, rather than a bare string. */
+    /** Per-member field sets on a `type: "enum"` field that is a card's own
+     *  field or a typed dictionary's property, keyed by member: the fields that
+     *  exist only where the discriminant holds that member. Declaring it makes
+     *  the field rest as a container, `{value: <member>, …that member's
+     *  fields}`, rather than a bare string. */
     variants?: Record<string, Record<string, QuillFieldSchema>>;
     /** The roster of a `type: "matrix"` field, required there and valid
-     *  nowhere else: the closed vocabulary a document ticks, in display order.
+     *  nowhere else: member id to display title, key order the display order.
      *  Each member is an object of `held` plus the field's `properties`
      *  (the columns), addressed as `<field>.<member id>.held`. */
-    members?: QuillMatrixGroup[];
+    members?: Record<string, string>;
     ui?: QuillFieldUi;
     properties?: Record<string, QuillFieldSchema>;
     items?: QuillFieldSchema;
@@ -482,15 +455,11 @@ export interface QuillFieldSchema {
     inline?: boolean;
 }
 
-/** One block of a `type: "matrix"` roster: an optional display heading and the
- * members under it, member id to display title. Key order is display order. */
-export interface QuillMatrixGroup {
-    group?: string;
-    values: Record<string, string>;
-}
-
 /** Schema entry for the main card or a named card kind. */
 export interface QuillCardSchema {
+    /** The kind's label, a literal. Absent, the consumer humanizes the kind
+     *  name. An instance takes its label from its own values. */
+    title?: string;
     description?: string;
     fields: Record<string, QuillFieldSchema>;
     ui?: QuillCardUi;
@@ -572,11 +541,6 @@ export class Document {
      * building `markOps` need not predict it.
      */
     applyChange(addr: Addr | string, bundle: ChangeBundle): void;
-    /**
-     * A blueprint's fill obligation for the given `quillName`, re-exposed from
-     * core. Carries no tool name: pair it with your own next-step directive.
-     */
-    static blueprintInstruction(quill_name: string): string;
     /**
      * 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
@@ -610,11 +574,6 @@ export class Document {
      * Structural equality, excluding parse-time `warnings`.
      */
     equals(other: Document): boolean;
-    /**
-     * Authoring-format rules for the card-yaml markdown surface, re-exposed from
-     * core. Constant across calls; read once and cache.
-     */
-    static formatRules(): string;
     /**
      * Parse markdown into a typed Document. Throws on parse errors.
      */
@@ -660,12 +619,6 @@ export class Document {
      * `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 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 [`fromStored`](Document::from_stored).
@@ -674,6 +627,11 @@ export class Document {
      * variable.
      */
     loadStored(json: string): void;
+    /**
+     * The Quillmark Markdown rules, re-exposed from core. Constant across
+     * calls; read once and cache.
+     */
+    static markdownRules(): string;
     /**
      * Move the card at `from` to position `to`. `from == to` is a no-op.
      */
@@ -682,8 +640,8 @@ export class Document {
      * 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.
+     * For one instance of every card kind use `Quill.seedDocument()`. Throws on
+     * an invalid quill reference.
      */
     constructor(quill_ref: string);
     /**
@@ -780,7 +738,7 @@ export class Document {
      * 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:
+     * composable card. A body address throws:
      * write a body with `revise` / `overwrite`. Throws on an out-of-range card
      * or a malformed name.
      */
@@ -793,11 +751,6 @@ export class Document {
      * 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`. 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` is main-only, so this
@@ -847,12 +800,19 @@ export class Quill {
      * transport door (`fromMarkdown`, `fromStored`, a stored row).
      *
      * 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
+     * bytes survive. 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[];
+    /**
+     * The empty document: a main card carrying this quill's `$quill` and
+     * `$kind: main`, no field committed, no composable card, no body. The
+     * type-minimal valid input, and the document a plate is bound to render
+     * (the quill authoring contract). `new Document(ref)` is the same document
+     * reached by spelling the reference.
+     */
+    emptyDocument(): Document;
     /**
      * 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
@@ -874,9 +834,9 @@ export class Quill {
     parse(markdown: string): Document;
     /**
      * 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`). `undefined` when `cardKind` is not
-     * declared in this quill's schema.
+     * committing an optional per-kind seed `overlay`'s fields and `$body`
+     * (`overlay › absent`, body `overlay › empty`). `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
@@ -885,9 +845,9 @@ export class Quill {
     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 as
-     * `default:`, else the field's blank). A field with both renders its example.
+     * of each composable card kind, each body empty and every field absent
+     * (interpolated at render as `default:`, else the field's blank). No
+     * `example:` is committed (a field's or `body.example`).
      */
     seedDocument(): Document;
     /**
@@ -908,8 +868,7 @@ export class Quill {
     /**
      * Validate `doc` against this quill's schema, returning every diagnostic
      * (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.
+     * `validation::*` diagnostics the engine emits.
      */
     validate(doc: Document): Diagnostic[];
     /**
@@ -971,6 +930,22 @@ export function formatDocPath(segs: DocPathSeg[]): string;
  */
 export function importMarkdown(markdown: string): Content;
 
+/**
+ * Whether `content` satisfies the `inline` constraint of `richtext` and
+ * `plaintext`: one `Para` line, in no container, with no islands. Judged on
+ * the normalized content, which is what a write stores. Throws if `content` is
+ * not canonical content.
+ */
+export function isInline(content: Content): boolean;
+
+/**
+ * Whether `content` satisfies the `plaintext` constraint: no marks, no
+ * islands, every line a `Para` in no container. Judged on the normalized
+ * content, which is what a write stores. Throws if `content` is not canonical
+ * content.
+ */
+export function isPlain(content: Content): boolean;
+
 /**
  * Where `bundle`'s text-moving channels (`delta`, then `islandOps`, then
  * `lineOps`) leave `content`'s marks: the final-text coordinates the bundle's
@@ -1036,7 +1011,6 @@ export interface InitOutput {
     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;
@@ -1045,15 +1019,14 @@ export interface InitOutput {
     readonly document_clone: (a: number) => number;
     readonly document_currentStorageVersion: (a: number) => void;
     readonly document_equals: (a: number, b: number) => number;
-    readonly document_formatRules: (a: number) => void;
     readonly document_fromMarkdown: (a: number, b: number, c: number) => void;
     readonly document_fromStored: (a: number, b: number, c: number) => void;
     readonly document_getExt: (a: number, b: number, c: number) => void;
     readonly document_getStored: (a: number, b: number, c: number) => void;
     readonly document_insertCard: (a: number, b: number, c: number, d: number) => void;
-    readonly document_isFill: (a: number, b: number, c: number) => void;
     readonly document_loadStored: (a: number, b: number, c: number, d: number) => void;
     readonly document_main: (a: number, b: number) => void;
+    readonly document_markdownRules: (a: number) => void;
     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;
@@ -1071,7 +1044,6 @@ export interface InitOutput {
     readonly document_storeExt: (a: number, b: number, c: number, d: number) => void;
     readonly document_storeField: (a: number, b: number, c: number, d: number) => void;
     readonly document_storeFields: (a: number, b: number, c: number, d: number) => void;
-    readonly document_storeFill: (a: number, b: number, c: number, d: number) => void;
     readonly document_storeSeedOverlay: (a: number, b: number, c: number, d: number, e: number) => void;
     readonly document_toMarkdown: (a: number, b: number) => void;
     readonly document_toStored: (a: number, b: number) => void;
@@ -1080,13 +1052,16 @@ export interface InitOutput {
     readonly formatDiagnostic: (a: number, b: number) => void;
     readonly formatDocPath: (a: number, b: number) => void;
     readonly importMarkdown: (a: number, b: number, c: number) => void;
+    readonly isInline: (a: number, b: number) => void;
+    readonly isPlain: (a: number, b: number) => void;
     readonly mapMarks: (a: number, b: number, c: number) => void;
     readonly mapPos: (a: number, b: number, c: number, d: number) => void;
     readonly parseDocPath: (a: number, b: number, c: number) => void;
-    readonly quill__resolve: (a: number, b: number, c: number) => void;
+    readonly quill__resolve: (a: number, b: number, c: number, d: number, e: number) => void;
     readonly quill_backendId: (a: number, b: number) => void;
     readonly quill_blueprint: (a: number, b: number) => void;
     readonly quill_conform: (a: number, b: number, c: number) => void;
+    readonly quill_emptyDocument: (a: number) => number;
     readonly quill_fromTree: (a: number, b: number) => void;
     readonly quill_metadata: (a: number, b: number) => void;
     readonly quill_parse: (a: number, b: number, c: number, d: number) => void;