@quillmark/wasm 0.88.0 → 0.90.0

package/core/wasm.d.ts

@@ -0,0 +1,439 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/** A field or comment entry in a `Card.payloadItems` list. */
+export type PayloadItem =
+| { type: "field"; key: string; value: unknown; fill?: boolean }
+| { type: "comment"; text: string; inline?: boolean };
+
+/**
+ * A single card block. The one shape exchanged in both directions: returned by
+ * `Document.main` / `Document.cards` / `Document.removeCard` / `Quill.seedCard`,
+ * and accepted by `Document.pushCard` / `Document.insertCard`. Build a fresh
+ * one with `Document.makeCard`.
+ *
+ * `$` system entries are hoisted to named fields: `kind` (the `$kind`, empty
+ * string when none), optional `quill` (the `$quill` `name@version`, main card
+ * only), optional `id` (`$id`), and optional `ext` (`$ext`). `payloadItems`
+ * carries user fields and comments in order.
+ */
+export interface Card {
+    kind: string;
+    quill?: string;
+    id?: string;
+    ext?: Record<string, unknown>;
+    payloadItems: PayloadItem[];
+    body: string;
+}
+
+
+
+/** UI layout hints for a single field. */
+export interface QuillFieldUi {
+    group?: string;
+    order?: number;
+    compact?: boolean;
+    multiline?: boolean;
+}
+
+/** UI layout hints for a card (main or named card kind). */
+export interface QuillCardUi {
+    title?: string;
+}
+
+/** 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;
+}
+
+/** 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>` sentinel and validation reports
+ * `validation::field_absent` if the field is absent at validate
+ * time — a non-fatal signal, since the render path zero-fills an absent
+ * field). There is no separate `required` axis.
+ */
+export interface QuillFieldSchema {
+    type: "string" | "number" | "integer" | "boolean" | "array" | "object" | "datetime" | "markdown";
+    description?: string;
+    default?: unknown;
+    example?: unknown;
+    enum?: string[];
+    ui?: QuillFieldUi;
+    properties?: Record<string, QuillFieldSchema>;
+    items?: QuillFieldSchema;
+}
+
+/** Schema entry for the main card or a named card kind. */
+export interface QuillCardSchema {
+    description?: string;
+    fields: Record<string, QuillFieldSchema>;
+    ui?: QuillCardUi;
+    body?: QuillCardBody;
+}
+
+/**
+ * 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
+ * discriminators are document-level metadata, not schema fields.
+ */
+export interface QuillSchema {
+    main: QuillCardSchema;
+    /** Present only when the quill declares at least one named card kind. */
+    card_kinds?: Record<string, QuillCardSchema>;
+}
+
+/**
+ * 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.
+ */
+export interface QuillMetadata {
+    name: string;
+    version: string;
+    backend: string;
+    author: string;
+    description: string;
+}
+
+
+export interface Diagnostic {
+    severity: Severity;
+    code?: string;
+    message: string;
+    location?: Location;
+    path?: string;
+    hint?: string;
+    sourceChain?: string[];
+}
+
+export interface Location {
+    file: string;
+    line: number;
+    column: number;
+}
+
+export type Severity = "error" | "warning" | "note";
+
+
+/**
+ * Typed in-memory Quillmark document.
+ */
+export class Document {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Authoring-ergonomics header introducing a blueprint to an LLM/MCP
+     * consumer for the given `quillName`. Surfaced verbatim by every binding
+     * so the wording stays uniform across CLI / Python / MCP.
+     */
+    static blueprintInstruction(quill_name: string): string;
+    clone(): Document;
+    /**
+     * Schema 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.
+     */
+    static currentSchemaVersion(): string;
+    /**
+     * Structural equality (parse-time `warnings` excluded). Use to debounce
+     * upstream prop updates instead of re-parsing on every keystroke.
+     */
+    equals(other: Document): boolean;
+    /**
+     * Render a Diagnostic as the canonical pretty-printed text every binding
+     * shows (CLI, Python, MCP). Single source of truth so a Diagnostic looks
+     * identical no matter which consumer surfaces it.
+     */
+    static formatDiagnostic(diag: Diagnostic): string;
+    /**
+     * Authoring-format rules for the card-yaml markdown surface — the same
+     * text every binding (CLI, Python, MCP) shows so callers reading errors
+     * from one binding can use the rules from any other. Read once at
+     * startup and cache; the value never changes between calls.
+     */
+    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).
+     *
+     * Throws if `json` is not a valid storage DTO (malformed JSON, unknown
+     * `schema`, missing fields, or unparseable quill reference).
+     */
+    static fromJson(json: string): Document;
+    /**
+     * Parse markdown into a typed Document. Throws on parse errors.
+     */
+    static fromMarkdown(markdown: string): Document;
+    /**
+     * Insert a card at `index` (must be in `0..=cards.length`). Accepts a
+     * `Card` (see [`pushCard`](Self::push_card)).
+     */
+    insertCard(index: number, card: Card): void;
+    /**
+     * Build a fresh `Card` from a kind and a flat field map — the ergonomic
+     * constructor for `pushCard` / `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.
+     */
+    static makeCard(kind: string, fields?: Record<string, unknown>, body?: string): Card;
+    /**
+     * Move the card at `from` to position `to`. `from == to` is a no-op.
+     */
+    moveCard(from: number, to: number): void;
+    /**
+     * Append a card to the end of the card list. Accepts a `Card` (the shape
+     * returned by `cards` / `removeCard` / `quill.seedCard`); build a fresh
+     * one with [`Document.makeCard`](Document::make_card). Throws if
+     * `card.kind` is not a valid kind name.
+     */
+    pushCard(card: Card): void;
+    /**
+     * The canonical `$quill` reference grammar as author-facing text. Single
+     * source of truth (CLI, Python, MCP): 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.
+     */
+    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.
+     */
+    removeExt(): 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: {}`).
+     */
+    removeExtNamespace(namespace: string): any;
+    /**
+     * Remove a payload field on the main card, returning the removed value or
+     * `undefined`. Throws if `name` does not match `[a-z_][a-z0-9_]*`.
+     */
+    removeField(name: string): any;
+    replaceBody(body: string): void;
+    /**
+     * Read the `schema` 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.
+     */
+    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;
+    /**
+     * Replace the kind of the card at `index`. Payload and body are untouched;
+     * schema-aware migration is the caller's responsibility.
+     * Throws if `index` is out of range or `newKind` is invalid.
+     */
+    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`.
+     */
+    setExt(value: any): 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.presentation`,
+     * `$ext.agent`, …) don't clobber each other.
+     */
+    setExtNamespace(namespace: string, value: any): void;
+    /**
+     * Update a payload field on the main card. Clears any existing `!fill` marker.
+     *
+     * Throws if `name` does not match `[a-z_][a-z0-9_]*`.
+     */
+    setField(name: string, value: any): void;
+    /**
+     * Update a payload field on the main card and mark it as `!fill`.
+     * Throws on invalid name (see [`setField`](Document::set_field)).
+     */
+    setFill(name: string, value: any): void;
+    /**
+     * Replace the QUILL reference string. Throws if `ref_str` is invalid.
+     */
+    setQuillRef(ref_str: string): 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.
+     */
+    toJson(): string;
+    /**
+     * Emit canonical Quillmark Markdown. Round-trip safe: re-parsing the
+     * result produces a `Document` equal to `self` by value and by type.
+     */
+    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.
+     */
+    static tryFromJson(json: string): Document | undefined;
+    /**
+     * Replace the body of the card at `index`. Throws if out of range.
+     */
+    updateCardBody(index: number, body: string): void;
+    /**
+     * Update a field on the card at `index`.
+     * Throws if `index` is out of range, `name` is reserved or invalid.
+     */
+    updateCardField(index: number, name: string, value: any): void;
+    /**
+     * Number of composable cards (excludes the main card). O(1).
+     */
+    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.
+     */
+    readonly main: Card;
+    readonly quillRef: string;
+    readonly warnings: Diagnostic[];
+}
+
+export class Quill {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * 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.
+     */
+    static fromTree(tree: Map<string, Uint8Array>): Quill;
+    /**
+     * Seed a starter composable `Card` of the given kind (carries `$kind`),
+     * committing its fields' `example:` values and leaving every other field
+     * absent. Returns `undefined` if `cardKind` is not declared in this
+     * quill's schema, else a `Card` that feeds straight into
+     * `Document.pushCard` / `insertCard`.
+     */
+    seedCard(card_kind: string): 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".
+     */
+    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.
+     */
+    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.
+     *
+     * 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
+     * `@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.
+     */
+    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::field_absent` completeness signal that `render` demotes.
+     * Field values, defaults, and order are not part of this surface: read
+     * them from the `Document` payload and `Quill.schema` (fields carry
+     * `ui.order`).
+     */
+    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.
+     */
+    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.
+     */
+    readonly metadata: QuillMetadata;
+    /**
+     * Document schema for the quill: the user-fillable fields plus their
+     * `ui` hints (group / order / showWhen). The single field-metadata
+     * surface — drives form editors and LLM/MCP consumers alike. Returns the
+     * `QuillSchema` shape.
+     */
+    readonly schema: QuillSchema;
+}
+
+/**
+ * Initialize the WASM module with panic hooks for better error messages
+ */
+export function init(): void;

package/core/wasm.js

@@ -0,0 +1,9 @@
+/* @ts-self-types="./wasm.d.ts" */
+import * as wasm from "./wasm_bg.wasm";
+import { __wbg_set_wasm } from "./wasm_bg.js";
+
+__wbg_set_wasm(wasm);
+wasm.__wbindgen_start();
+export {
+    Document, Quill, init
+} from "./wasm_bg.js";