@markup-carve/carve-wasm 0.1.3 → 0.1.5

package/carve_wasm.d.ts

@@ -15,6 +15,22 @@ export interface LintWarning {
     end: number;
 }
 
+export interface ProfileViolation {
+    /** Canonical node type that was disallowed. */
+    nodeType: string;
+    /** Machine reason: element_not_allowed | max_nesting_exceeded | link_not_allowed | image_not_allowed. */
+    reason: string;
+    /** The profile's own wording for the denial, when it carries one. */
+    reasonDescription: string | null;
+    /** The engine's prose, the same text a thrown ProfileViolationError lists. */
+    message: string;
+}
+export interface ProfileFilterResult {
+    /** The filtered tree, as AST JSON. */
+    json: string;
+    violations: ProfileViolation[];
+}
+
 export interface Stamp {
     /** The spec version the document was last processed under. */
     version: string;
@@ -22,6 +38,25 @@ export interface Stamp {
     generatedBy: string | null;
 }
 
+export type MigrationFidelity = "preserved" | "normalized" | "degraded" | "dropped";
+export type MigrationConfidence = "exact" | "inferred" | "fallback";
+export interface MigrationDiagnostic {
+    code: string;
+    message: string;
+    severity: "info" | "warning" | "error";
+    fidelity: MigrationFidelity;
+    confidence: MigrationConfidence;
+    path?: string;
+}
+export interface MigrationReport {
+    schemaVersion: 2;
+    sourceFormat: string;
+    mode?: string;
+    adapter?: string;
+    diagnostics: MigrationDiagnostic[];
+}
+export interface MigrationResult { value: string; report: MigrationReport; }
+
 export type SourceEditKind = "formatting" | "syntax-migration" | "quick-fix" | "refactor";
 export interface SourceEdit {
     /** Inclusive UTF-8 byte offset. */
@@ -41,13 +76,107 @@ export interface SourcePatch {
     unresolved: SourceSuggestion[];
 }
 
+export interface StaticRendererError {
+    /** The renderer that failed. Only "math" is bound. */
+    renderer: "math";
+    /** True for display math. */
+    display: boolean;
+    /** The source the renderer was handed. */
+    source: string;
+    message: string;
+}
+export interface StaticRenderResult {
+    html: string;
+    /** Empty unless a render callback threw or returned a non-string. */
+    rendererErrors: StaticRendererError[];
+}
+
+export interface AccessibilityDiagnostic {
+    /** Stable rule id, e.g. a11y/image-alt. */
+    rule: string;
+    severity: "warning" | "error";
+    message: string;
+    /** 0-based BYTE offset into the source, or null when the node carried none. */
+    startOffset: number | null;
+    endOffset: number | null;
+}
+
+export interface SanitizeSvgOptions {
+    allowStyle?: boolean;
+    allowLinks?: boolean;
+    allowAnimation?: boolean;
+    allowExternalImages?: boolean;
+}
+export interface SanitizeResult {
+    /** Meaningful only when ok is true. */
+    svg: string;
+    /** False when the input was not a single well-formed <svg> root. */
+    ok: boolean;
+}
+
+export interface ParsedLocator {
+    label: string | null;
+    value: string | null;
+    suffixText: string | null;
+}
+
+export interface ProseMirrorResult {
+    /** The ProseMirror document, JSON-encoded. */
+    json: string;
+    /** Carve node type -> why its content is gone. */
+    dropped: Record<string, string>;
+    /** Carve node type -> why its node type is gone while its text survives. */
+    degraded: Record<string, string>;
+}
+
 
 
+/**
+ * Replay patch JSON onto a PART 12 tree, returning the result as AST JSON.
+ */
+export function applyAstPatch(ast: string, patch: string): string;
+
+/**
+ * Apply a security profile to an AST-JSON document (PART 12), keeping the
+ * filtered tree.
+ *
+ * The `profile` render option filters on the way to HTML and throws the result
+ * of the filtering away. This is the same pass with the tree kept, so a host
+ * that stores, diffs or re-renders an untrusted document does not have to
+ * render HTML and parse it back to get one.
+ *
+ * `violations` reports what the filter degraded or stripped, which the HTML
+ * path cannot: a profile whose action is `error` throws instead, so a
+ * resolved call under `to-text` or `strip` is the only place this is visible.
+ *
+ * Only `profileBaseHost` and `smartTypography` are read from `options`. The
+ * rest of the render options describe a renderer, and this is not one.
+ *
+ * The profile's `max_length` is NOT enforced here: the engine applies it to the
+ * source bytes before a parse, and this entry point is handed a tree.
+ */
+export function applyProfile(json: string, profile: string, options?: object | null): ProfileFilterResult;
+
+/**
+ * Replay a reversible patch, forward or inverted.
+ *
+ * The fingerprint is checked first: a tree that is not the one this patch was
+ * made against is refused rather than half-patched. That is a broken caller
+ * contract, so it throws.
+ */
+export function applyReversibleAstPatch(ast: string, patch: string, inverse?: boolean | null): string;
+
 /**
  * Apply a trusted patch after its source length and fingerprint still match.
  */
 export function applySourcePatch(source: string, patch: any): string;
 
+/**
+ * Render an AST-JSON document (PART 12) to ANSI-styled text. See
+ * [`ast_json_to_markdown`], including what a tree without positions costs.
+ */
+export function astJsonToAnsi(json: string, options?: object | null): string;
+
 /**
  * Render an AST-JSON document (PART 12) back to canonical Carve source.
  *
@@ -69,11 +198,120 @@ export function astJsonToCarve(json: string): string;
  */
 export function astJsonToHtml(json: string, options?: object | null): string;
 
+/**
+ * Render an AST-JSON document (PART 12) to Markdown.
+ *
+ * The direct call for a host that already holds a tree. Without it Markdown was
+ * reached through `astJsonToCarve` and then `toMarkdown`: a canonical write, a
+ * re-parse and a second render for one answer, and lossier than this, because a
+ * tree holding something no Carve source can spell is refused by the write
+ * rather than rendered.
+ *
+ * Takes the same options object as [`to_markdown_with_options`], and reads the
+ * same narrow part of it. The profile filter and the `before_render` hooks run,
+ * as they do in [`ast_json_to_html`].
+ *
+ * ORDERING FOLLOWS THE TREE. `toMarkdown` parses with positions on, because
+ * section 7 orders collected definitions by source position. A tree arriving as
+ * JSON carries whatever positions its producer put there, and one carrying none
+ * prints its footnote and link definitions in label order. That is the only
+ * order available to a tree without spans, so it is reported here rather than
+ * repaired.
+ */
+export function astJsonToMarkdown(json: string, options?: object | null): string;
+
+/**
+ * Render an AST-JSON document (PART 12) to plain text. See
+ * [`ast_json_to_markdown`], including what a tree without positions costs.
+ */
+export function astJsonToPlainText(json: string, options?: object | null): string;
+
+/**
+ * The difference between two PART 12 trees, as patch JSON.
+ *
+ * ```js
+ * const patch = createAstPatch(parseJson('# One\n'), parseJson('# Two\n'))
+ * applyAstPatch(parseJson('# One\n'), patch) // the '# Two' tree
+ * ```
+ *
+ * Trees and patches both cross as JSON strings, matching `parseJson` and
+ * `astJsonToHtml`. A patch carries node payloads, so it carries arbitrary
+ * document text - the reason `parseJson` chose a string in the first place.
+ *
+ * The engine's `ast_patch_to_json` and `ast_patch_from_json` are not bound
+ * separately. With the patch crossing as JSON they ARE the encoding of this
+ * pair, and a host calling them would be converting JSON it already holds.
+ *
+ * The operations are position-independent `{ op, path, value }`, so a patch
+ * stays meaningful against a tree that moved underneath it - unlike a source
+ * patch, which `createSourcePatch` fingerprints against staleness.
+ */
+export function createAstPatch(before: string, after: string): string;
+
+/**
+ * The same difference with its inverse and both fingerprints, as one JSON
+ * object: `{ forward, inverse, beforeFingerprint, afterFingerprint }`.
+ *
+ * This is the shape an undo step wants. THE STACK IS THE HOST'S: every entry
+ * point in this package is a pure function that owns nothing, so there is no
+ * history kept here to undo against, and a browser host already has one - a
+ * key handler, a toolbar, an editor's own history plugin.
+ *
+ * What the pair adds over two `createAstPatch` calls is the precondition.
+ * [`apply_reversible_ast_patch`] refuses a tree whose fingerprint is not the
+ * one the patch was made against, so an undo cannot be replayed onto a
+ * document that has moved on.
+ */
+export function createReversibleAstPatch(before: string, after: string): string;
+
 /**
  * Build the smallest single UTF-8 byte-range replacement between two sources.
  */
 export function createSourcePatch(source: string, replacement: string, kind: string, code: string): SourcePatch;
 
+/**
+ * Expand `{{ path }}` include directives (spec PART 9 §19) through a JS
+ * resolver, and hand back the expanded tree as AST JSON.
+ *
+ * The resolver MUST BE SYNCHRONOUS, which decides who can use this. A browser
+ * host that would resolve a path by `fetch` cannot: `fetch` is a Promise and
+ * wasm-bindgen cannot await across the call. A host whose files are already in
+ * memory - an editor with its open buffers, a bundler, a VFS, a test harness -
+ * resolves from that map and is exactly who this is for.
+ *
+ * ```js
+ * const files = new Map([['child.crv', 'Included body.\n']])
+ * expandIncludes('Before.\n\n{{ child.crv }}\n', {
+ *   resolve: (path) => files.get(path) ?? null,
+ * })
+ * // { json, warnings: [], suppressedWarnings: 0, dependencies: […],
+ * //   chargedBytes: 15, resolverErrors: [] }
+ * ```
+ *
+ * The resolver returns the child's source as a string, or
+ * `{ source, id }` when it can name the file canonically - the id is what the
+ * cycle guard compares, so two spellings of one file defeat it without one.
+ * `null` refuses the directive as `not-found`; `{ denial }` refuses it in one
+ * of the classes §19 names.
+ *
+ * An `async` resolver returns a Promise, which is not a string and cannot be
+ * awaited. That is a per-document failure reported in `resolverErrors`,
+ * matching what an `async` `renderers.math` gets from
+ * [`to_html_with_renderers`]: the directive stays literal and the caller is
+ * told why, rather than the value being swallowed or stringified.
+ *
+ * The BUDGETS are part of the contract, not a detail: `maxBytes` defaults to
+ * `max(1 MB, 8 x source bytes)`, `maxDepth` to 16, `maxResolverCalls` to 1000
+ * and `maxWarnings` to 100. They bound what a document of directives can make
+ * a host do, and lowering them is how a host serving untrusted documents keeps
+ * that bounded.
+ *
+ * The tree carries no positions. Expansion merges nodes from several files,
+ * and a span on a node that came from a child would point into a source the
+ * caller did not pass.
+ */
+export function expandIncludes(source: string, options: object): IncludeExpansion;
+
 /**
  * Every extension name this build accepts, in registry order.
  *
@@ -100,9 +338,46 @@ export function fromBbcode(source: string): string;
  */
 export function fromDjot(source: string): string;
 
-export function fromHtml(source: string, mode?: string | null): any;
+export function fromHtml(source: string, mode?: string | null): MigrationResult;
 
-export function fromMarkdown(source: string): any;
+export function fromMarkdown(source: string): MigrationResult;
+
+/**
+ * Convert a ProseMirror document back to canonical Carve source.
+ *
+ * The save half of the editor loop. A payload the schema map does not describe
+ * is refused rather than written approximately, so an editor extended with a
+ * node the bridge has never seen fails where it can be reported.
+ */
+export function fromProseMirror(doc: string): string;
+
+/**
+ * Import HTML straight to the tree, as AST JSON.
+ *
+ * `htmlToCarve` writes Carve SOURCE, so a host that wanted the tree had to
+ * re-parse what it had just written - two parses of one document to get one
+ * answer. This is the same importer without that round trip.
+ *
+ * ```js
+ * const { value, report } = htmlToAst('<p>Hello <b>world</b></p>', 'safe')
+ * astJsonToHtml(value)
+ * ```
+ *
+ * Returns the SAME `{ value, report }` shape `htmlToCarve` does, with `value`
+ * holding the tree instead of the source, in the same fidelity vocabulary. A
+ * third result shape for one importer is what that avoids.
+ *
+ * The REPORT IS NOT ALWAYS IDENTICAL, and the difference is the point. A loss
+ * only a WRITER takes is not reported here, because no writer ran (PART 12
+ * §16): a `<figure>` wrapping a table, or a table with an explicit
+ * head/body/foot grouping, has no Carve spelling, so `htmlToCarve` reports
+ * `structure-unspellable` and this does not - the tree keeps the thing that
+ * would have been lost.
+ *
+ * `mode` is spelled as it is there: `safe` (the default), `semantic`, and
+ * trusted-only `roundtrip`.
+ */
+export function htmlToAst(source: string, mode?: string | null): MigrationResult;
 
 /**
  * Import HTML through the Rust HTML5 DOM and canonical Carve writer.
@@ -110,7 +385,16 @@ export function fromMarkdown(source: string): any;
  * Returns `{ value, report }`; `report.diagnostics` makes every lossy import
  * decision observable. `roundtrip` is only safe for Carve-produced HTML.
  */
-export function htmlToCarve(source: string, mode?: string | null): any;
+export function htmlToCarve(source: string, mode?: string | null): MigrationResult;
+
+/**
+ * The accessibility diagnostics, a second family beside `lintCarve`.
+ *
+ * Its own rule ids (`a11y/image-alt`, `a11y/heading-jump`) and its own
+ * severity, which `lintCarve` has no field for. Offsets are `null` when the
+ * node that triggered the rule carried no position.
+ */
+export function lintAccessibility(source: string): AccessibilityDiagnostic[];
 
 /**
  * Lint a document for the degradations PART 15 describes.
@@ -125,6 +409,61 @@ export function htmlToCarve(source: string, mode?: string | null): any;
  */
 export function lintCarve(source: string): LintWarning[];
 
+/**
+ * Lint a document with the same options object the render entry points take.
+ *
+ * `lintCarve` is the option-less form. Which degradations exist depends on the
+ * extensions in play, so a host that renders with a set has to lint with it.
+ */
+export function lintCarveWithOptions(source: string, options?: object | null): LintWarning[];
+
+/**
+ * Import Markdown straight to the tree, as AST JSON.
+ *
+ * `fromMarkdown` writes Carve SOURCE, so a host that wanted the tree had to
+ * re-parse what it had just written. This is the same importer without that
+ * round trip. The losses `fromMarkdown` reports are not repeated here; a host
+ * that needs them calls that one.
+ */
+export function markdownToAstJson(source: string): string;
+
+/**
+ * Three-way merge over PART 12 trees, with conflicts as a VALUE.
+ *
+ * ```js
+ * const { ok, ast, conflicts } = JSON.parse(mergeAst(base, ours, theirs))
+ * ```
+ *
+ * Returns `{ ok, ast, conflicts, resolverErrors }` as one JSON string. A
+ * conflict does NOT throw: it is a result the caller asked for, and two people
+ * editing one document is the ordinary case rather than a broken contract.
+ * `ok` is false, `ast` is null, and `conflicts` says where and why.
+ *
+ * The `{ ok, ast, conflicts }` shape and the three `reason` names -
+ * `both-changed`, `delete-edit`, `concurrent-sequence-edit` - are carve-js's,
+ * so a host merging with either engine reads one contract. The Rust engine
+ * carries no `deleted` flags on a conflict, so that optional carve-js field is
+ * absent here rather than guessed at.
+ *
+ * `options.resolve` is an optional `(conflict) => 'base' | 'ours' | 'theirs' |
+ * { value } | null`, answering conflicts while the merge runs; an answer of
+ * `null` leaves one unresolved. IT MUST BE SYNCHRONOUS. A resolver that asks a
+ * server, or asks the user, returns a Promise the merge cannot await - that is
+ * reported in `resolverErrors` and the conflict is left unresolved, the same
+ * treatment an `async` `renderers.math` gets.
+ */
+export function mergeAst(base: string, ours: string, theirs: string, options?: object | null): string;
+
+/**
+ * Convert BBCode and retain a conservative v2 fidelity report.
+ */
+export function migrateBbcode(source: string): MigrationResult;
+
+/**
+ * Convert Djot and retain a conservative v2 fidelity report.
+ */
+export function migrateDjot(source: string): MigrationResult;
+
 /**
  * Whether a document was last processed under an older spec version than
  * `currentVersion`. An unstamped document counts as needing review.
@@ -151,13 +490,115 @@ export function needsReview(source: string, current_version: string): boolean;
  */
 export function parseJson(source: string): string;
 
+/**
+ * Serialize the tree with the same options object as
+ * [`to_html_with_options`], so a host can export the tree of an untrusted
+ * document under the `profile` it renders that document with.
+ *
+ * `positions` is not read: every serialized tree this binding produces carries
+ * them, as in [`parse_json`].
+ */
+export function parseJsonWithOptions(source: string, options?: object | null): string;
+
+/**
+ * Parse the locator portion of a citation into `{ label, value, suffixText }`.
+ *
+ * A field the source did not carry is `null`. Same shape as carve-js
+ * `parseLocator`; pure, and never throws on bad input.
+ */
+export function parseLocator(loc: string): ParsedLocator;
+
+/**
+ * Parse a document and keep what a later [`reparse`] needs.
+ *
+ * Returns one JSON object: `{ source, document, sourceLayout, changedSource,
+ * reusedPreviousTree }`. `document` is the PART 12 tree, `sourceLayout` the
+ * byte-exact record [`parse_source_layout_json`] produces, and
+ * `changedSource` the byte ranges this parse covered - the whole document, on
+ * a first parse.
+ *
+ * The snapshot crosses as JSON rather than as a handle a host has to `free()`.
+ * Every other entry point here is a pure function that owns nothing, and the
+ * engine's own snapshot holds only the source, so there is no tree being kept
+ * alive in wasm memory for a handle to point at.
+ */
+export function parseSnapshot(source: string): string;
+
+/**
+ * The PART 12 §13 source-layout sidecar for a document.
+ *
+ * Separate from `parseJson`, which carries semantic positions on the nodes.
+ * This is the byte-exact record of the SOURCE: its line endings, whether it
+ * had a BOM, and a path-addressed byte span per node - what a host needs to
+ * write an edit back into the file it came from.
+ */
+export function parseSourceLayoutJson(source: string): string;
+
 /**
  * Read a document's provenance marker: `{ version, generatedBy }`, or `null`.
  */
 export function readStamp(source: string): Stamp | null;
 
+/**
+ * Re-parse `source` with `changes` applied.
+ *
+ * ```js
+ * const first = JSON.parse(parseSnapshot('# One\n'))
+ * const next = JSON.parse(reparse(first.source, '[{"range":[2,5],"replacement":"Two"}]'))
+ * ```
+ *
+ * `changes` is a JSON array of `{ range: [start, end], replacement }`.
+ *
+ * THE OFFSETS ARE UTF-8 BYTE OFFSETS, which is what `parseJson` positions and
+ * `createSourcePatch` ranges already mean. A browser editor counts UTF-16 code
+ * units, so a host holding a `selectionStart` converts before calling - an
+ * offset that lands inside a multi-byte character is refused rather than
+ * guessed at.
+ *
+ * A malformed change THROWS: overlapping ranges, an end past the source, and a
+ * range that splits a code point are all a broken caller contract, not a
+ * result the caller asked for.
+ *
+ * `reusedPreviousTree` says whether the parse reused any of the previous one.
+ * The pinned engine always reports `false` - it validates and applies the
+ * edits and then parses the whole source - so a host should read this as the
+ * engine's own answer rather than assume work was saved.
+ */
+export function reparse(source: string, changes: string): string;
+
+/**
+ * Sanitize an SVG document, the helper a host embedding SVG would otherwise
+ * reimplement.
+ *
+ * `{ svg, ok }`. `ok` false means the input was not a single well-formed
+ * `<svg>` root, and a caller must then show the SOURCE rather than the input:
+ * `svg` carries nothing to display. Every option defaults to `false`, which is
+ * the strict setting.
+ */
+export function sanitizeSvg(source: string, options?: object | null): SanitizeResult;
+
+/**
+ * Write a provenance marker onto already-formatted Carve.
+ *
+ * The other half of `readStamp` and `needsReview`, which could read a marker
+ * this package had no way to write. `generatedBy` is the engine identity a
+ * host wants recorded, e.g. `"my-app 1.2"`; `form` is `"line"` (default) or
+ * `"block"`. Same signature as carve-js `stampCarve`.
+ *
+ * The input is expected to be formatted already: this appends the marker and
+ * replaces one the document carries, it does not canonicalize. `toCarve` is
+ * the formatter.
+ */
+export function stampCarve(formatted: string, generated_by: string, form?: string | null): string;
+
 export function toAnsi(source: string): string;
 
+/**
+ * Render to ANSI text with an options object. See
+ * [`to_markdown_with_options`].
+ */
+export function toAnsiWithOptions(source: string, options?: object | null): string;
+
 export function toAnsiWithReport(source: string, strict?: boolean | null, maximum?: number | null): any;
 
 export function toCarve(source: string): string;
@@ -167,6 +608,14 @@ export function toCarve(source: string): string;
  */
 export function toCarvePatch(source: string): SourcePatch;
 
+/**
+ * Write canonical Carve with an options object.
+ *
+ * `profile` is the only option this target reads; see
+ * [`to_markdown_with_options`] for why.
+ */
+export function toCarveWithOptions(source: string, options?: object | null): string;
+
 export function toCarveWithReport(source: string, strict?: boolean | null, maximum?: number | null): any;
 
 export function toHtml(source: string): string;
@@ -245,11 +694,22 @@ export function toHtmlFull(source: string, symbols?: object | null): string;
  * * `lowercaseHeadingIds` (default `false`) and `asciiHeadingIds`
  *   (`"off"` (default), `"fold"`, `"strict"`) - the slug policy, for a host
  *   whose anchors have to match another generator's.
+ * * `mentionUrl` and `tagUrl` - URL templates for `@mention` and `#tag`.
+ *   Without them both render as inert spans, which is why a host that wants
+ *   them linked has to say where to. The token name is percent-encoded into
+ *   `{name}` - `{user}` works too for a mention - and the result goes through
+ *   the same URL sanitizer as an authored link. These are the HOST's
+ *   configuration, not the document's: the template is trusted, the name
+ *   substituted into it is not.
  *
  * An unrecognized key is ignored: the object is configuration, and a caller
  * who mistypes one deserves the render to still work. A wrong TYPE on a key
  * that is recognized does throw, because that changes behavior silently.
  *
+ * `renderers` is the one recognized key this entry point refuses, because a
+ * render callback can fail and a bare string has nowhere to report that. Use
+ * [`to_html_with_renderers`].
+ *
  * Turning sections off changes nothing else. Ids, collision dedup, `</#id>`
  * crossrefs, implicit `[Heading][]` references and heading numbering all
  * resolve against the slug rather than the element carrying it, and the
@@ -258,6 +718,66 @@ export function toHtmlFull(source: string, symbols?: object | null): string;
  */
 export function toHtmlWithOptions(source: string, options?: object | null): string;
 
+/**
+ * Render with a build-time math renderer, the option `mode: "static"` needs.
+ *
+ * Static output carries no client scripts, so a formula it contains has to be
+ * rendered while the HTML is being written. `renderers.math` is the callback
+ * the engine calls for each ``` ```math ``` fence, with the TeX source and a
+ * display flag; KaTeX's `renderToString` has that exact shape.
+ *
+ * ```js
+ * toHtmlWithRenderers(src, {
+ *   mode: 'static',
+ *   extensions: ['math-block'],
+ *   renderers: { math: (tex, display) => katex.renderToString(tex, { displayMode: display }) },
+ * })
+ * // { html: '…', rendererErrors: [] }
+ * ```
+ *
+ * SECURITY: what the callback returns is inserted as **TRUSTED RAW HTML**, the
+ * same trust class as a `symbols` value. The difference worth stating: a symbol
+ * value is host configuration keyed by a NAME, while a renderer is host
+ * configuration that is HANDED DOCUMENT CONTENT and typically echoes some of it
+ * back. A host rendering documents it did not author is accepting whatever its
+ * renderer makes of that input, so the escaping is the renderer's job.
+ *
+ * The engine consults the renderer only under `mode: "static"`; interactive
+ * output keeps the `\[…\]` source for the client to typeset, and so does a
+ * static render with no renderer supplied.
+ *
+ * The callback must be SYNCHRONOUS. wasm-bindgen cannot await across it, so an
+ * `async` renderer returns a Promise the engine has no way to resolve; that is
+ * recorded as a failure rather than stringified into the document.
+ *
+ * `renderers.diagrams` is the same callback one level down, keyed by the
+ * fence's css class: `{ mermaid: (source) => html }`. A host that renders its
+ * diagrams beforehand passes the lookup in that one line -
+ * `(source) => prerendered.get(source)`. Mermaid itself cannot be passed,
+ * because its `render` returns a Promise from v10 on.
+ *
+ * ```js
+ * toHtmlWithRenderers(src, {
+ *   mode: 'static',
+ *   extensions: ['fenced-render'],
+ *   renderers: { diagrams: { mermaid: (source) => prerendered.get(source) } },
+ * })
+ * ```
+ *
+ * A diagram key the document never uses renders nothing and reports nothing.
+ * So does a fence whose class the caller did not configure: the engine
+ * degrades it to an escaped source block, and this binding never sees the
+ * node.
+ *
+ * A callback that throws, or returns anything other than a string, does not
+ * abort the render: the node it was called for emits nothing and the failure
+ * is reported in `rendererErrors`, with `renderer` naming the css class.
+ * This entry point exists because [`to_html_with_options`] returns a bare
+ * string with nowhere to put that, and so it rejects `renderers` rather than
+ * dropping the failures.
+ */
+export function toHtmlWithRenderers(source: string, options?: object | null): StaticRenderResult;
+
 export function toHtmlWithReport(source: string, strict?: boolean | null, maximum?: number | null): any;
 
 /**
@@ -280,10 +800,57 @@ export function toHtmlWithSymbols(source: string, symbols?: object | null): stri
 
 export function toMarkdown(source: string): string;
 
+/**
+ * Render to Markdown with the same options object as
+ * [`to_html_with_options`].
+ *
+ * `profile` is why this exists. Without it a host can hold an untrusted
+ * document to a profile on the way to HTML and not on the way to Markdown,
+ * out of one package: the max-length bound, the denied constructs and the
+ * link policy were all unreachable here. A document the profile rejects
+ * throws a `ProfileViolationError` rather than resolving to an empty string.
+ *
+ * What these targets read is narrower than HTML's list: `profile` and
+ * `smartTypography` change the output and extensions run, while `symbols`
+ * (markup-carve/carve-rs#1668), `labels`, `sections`, `sourceLine`, `mode` and
+ * the heading-id switches are HTML-side concerns the engine's other renderers
+ * do not consult. `renderers` is refused for the reason
+ * [`to_html_with_options`] refuses it.
+ *
+ * [`to_carve_with_options`] is narrower again and reads `profile` alone: the
+ * engine's canonical writer is parse-only by contract, so extensions and
+ * `smartTypography` are inert there. They are accepted rather than refused
+ * because one options object is meant to serve every target.
+ */
+export function toMarkdownWithOptions(source: string, options?: object | null): string;
+
 export function toMarkdownWithReport(source: string, strict?: boolean | null, maximum?: number | null): any;
 
 export function toPlainText(source: string): string;
 
+/**
+ * Render to plain text with an options object. See
+ * [`to_markdown_with_options`].
+ */
+export function toPlainTextWithOptions(source: string, options?: object | null): string;
+
 export function toPlainTextWithReport(source: string, strict?: boolean | null, maximum?: number | null): any;
 
+/**
+ * Convert Carve source to the ProseMirror document shape.
+ *
+ * ProseMirror runs in a browser and nowhere else, so this is the one engine
+ * capability whose whole audience sits behind a WASM binding. Without it a host
+ * wiring a Carve editor either round-trips to a server or reimplements the node
+ * mapping in JS, where it drifts from the engine's.
+ *
+ * Returns `{ json, dropped, degraded }`. `json` is the ProseMirror document as
+ * a JSON string, the same choice `parseJson` makes and for the same reason.
+ * The two maps say what the ProseMirror model could not hold: `dropped` where
+ * the content is gone, `degraded` where the text survives without its node
+ * type. A silent conversion is the degradation shape `lintCarve` exists to
+ * avoid.
+ */
+export function toProseMirror(source: string): ProseMirrorResult;
+
 export function version(): string;

package/carve_wasm.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./carve_wasm_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    applySourcePatch, astJsonToCarve, astJsonToHtml, createSourcePatch, extensions, fromBbcode, fromDjot, fromHtml, fromMarkdown, htmlToCarve, lintCarve, needsReview, parseJson, readStamp, toAnsi, toAnsiWithReport, toCarve, toCarvePatch, toCarveWithReport, toHtml, toHtmlFull, toHtmlWithOptions, toHtmlWithReport, toHtmlWithSymbols, toMarkdown, toMarkdownWithReport, toPlainText, toPlainTextWithReport, version
+    applyAstPatch, applyProfile, applyReversibleAstPatch, applySourcePatch, astJsonToAnsi, astJsonToCarve, astJsonToHtml, astJsonToMarkdown, astJsonToPlainText, createAstPatch, createReversibleAstPatch, createSourcePatch, expandIncludes, extensions, fromBbcode, fromDjot, fromHtml, fromMarkdown, fromProseMirror, htmlToAst, htmlToCarve, lintAccessibility, lintCarve, lintCarveWithOptions, markdownToAstJson, mergeAst, migrateBbcode, migrateDjot, needsReview, parseJson, parseJsonWithOptions, parseLocator, parseSnapshot, parseSourceLayoutJson, readStamp, reparse, sanitizeSvg, stampCarve, toAnsi, toAnsiWithOptions, toAnsiWithReport, toCarve, toCarvePatch, toCarveWithOptions, toCarveWithReport, toHtml, toHtmlFull, toHtmlWithOptions, toHtmlWithRenderers, toHtmlWithReport, toHtmlWithSymbols, toMarkdown, toMarkdownWithOptions, toMarkdownWithReport, toPlainText, toPlainTextWithOptions, toPlainTextWithReport, toProseMirror, version
 } from "./carve_wasm_bg.js";