@markup-carve/carve-wasm 0.1.4 → 0.1.6

package/node/carve_wasm.d.ts

@@ -0,0 +1,740 @@
+/* tslint:disable */
+/* eslint-disable */
+
+
+export function toHtmlWithOptions(source: string, options?: RenderOptions | null): string;
+export function toHtmlWithRenderers(source: string, options?: StaticRenderOptions | null): StaticRenderResult;
+
+export interface IncludeContext {
+    sourcePath: string | null;
+    stack: string[];
+    depth: number;
+}
+export type IncludeDenial = "outside-root" | "not-found" | "no-root" | "include-denied" | "include-unresolved";
+export interface IncludeOptions {
+    resolve: (path: string, context: IncludeContext) => string | { source: string; id?: string } | { denial: IncludeDenial } | null;
+    sourcePath?: string;
+    extensions?: string[];
+    maxDepth?: number;
+    maxBytes?: number;
+    maxResolverCalls?: number;
+    maxWarnings?: number;
+}
+export interface IncludeExpansion {
+    json: string;
+    warnings: { rule: string; message: string; file: string | null }[];
+    suppressedWarnings: number;
+    dependencies: { id: string; resolved: boolean; denial: IncludeDenial | null }[];
+    chargedBytes: number;
+    resolverErrors: { path: string; message: string }[];
+}
+export interface SourcePosition {
+    startLine: number;
+    endLine: number;
+    startColumn: number;
+    endColumn: number;
+    /** Unicode codepoint offsets, not UTF-8 bytes or UTF-16 units. */
+    startOffset: number;
+    endOffset: number;
+}
+export interface RenderLoss {
+    code: string;
+    format: string;
+    target: string;
+    nodeType: string;
+    message: string;
+    pos?: SourcePosition;
+}
+export interface RenderResult {
+    value: string;
+    losses: RenderLoss[];
+    totalLosses: number;
+    /**
+     * How many losses each code accounts for, across the WHOLE render.
+     * `losses` is bounded, so counting codes off that array under-reports as
+     * soon as `truncated` is true; these totals do not.
+     */
+    totalsByCode: Record<string, number>;
+    truncated: boolean;
+}
+export interface RenderOptions {
+    full?: boolean;
+    extensions?: string[];
+    symbols?: Record<string, string> | Map<string, string>;
+    rawHtml?: boolean;
+    sections?: boolean;
+    sourceLine?: boolean;
+    positions?: boolean;
+    lowercaseHeadingIds?: boolean;
+    asciiHeadingIds?: "off" | "fold" | "strict";
+    smartTypography?: "glyph" | "source";
+    mode?: "interactive" | "static";
+    profile?: "full" | "article" | "comment" | "minimal";
+    profileBaseHost?: string;
+    mentionUrl?: string;
+    tagUrl?: string;
+    labels?: Record<string, string>;
+}
+export interface StaticRenderOptions extends RenderOptions {
+    renderers?: {
+        math?: (source: string, display: boolean) => string;
+        diagrams?: Record<string, (source: string) => string>;
+    };
+}
+
+export interface LintWarning {
+    /** 1-based line number. */
+    line: number;
+    /** 1-based column number. */
+    column: number;
+    /** Stable rule id, shared with carve-js and carve-php. */
+    rule: string;
+    message: string;
+    /**
+     * 0-based offset into the source in UTF-16 CODE UNITS, inclusive. That is
+     * what indexes a JavaScript string, so `source.slice(start, end)` selects the
+     * span the warning is about. It was a UTF-8 byte offset before 0.1.6, which
+     * agreed with this on an ASCII document and not outside one.
+     */
+    start: number;
+    /** 0-based UTF-16 code unit offset into the source, exclusive. */
+    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;
+    /** The engine that wrote the marker, when it recorded one. */
+    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. */
+    start: number;
+    /** Exclusive UTF-8 byte offset. */
+    end: number;
+    replacement: string;
+    kind: SourceEditKind;
+    code: string;
+}
+export interface SourceSuggestion extends SourceEdit { message: string; }
+export interface SourcePatch {
+    version: 1;
+    sourceFingerprint: string;
+    sourceBytes: number;
+    edits: SourceEdit[];
+    unresolved: SourceSuggestion[];
+}
+
+export interface StaticRendererError {
+    /** "math", or the diagram fence class. */
+    renderer: string;
+    /** Present for math callbacks only. */
+    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 Unicode CODEPOINT offset, or null when the node carried none.
+     * Codepoints, not the UTF-8 bytes `LintWarning` counts: the two lint
+     * families answer in different units.
+     */
+    startOffset: number | null;
+    endOffset: number | null;
+    /**
+     * The same span in UTF-16 code units, which is what indexes a JavaScript
+     * string. Null exactly when `startOffset` / `endOffset` are.
+     */
+    startUtf16: number | null;
+    endUtf16: 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>;
+}
+
+
+
+export function astJsonToMarkdown(json: string, options?: RenderOptions | null): string;
+export function astJsonToPlainText(json: string, options?: RenderOptions | null): string;
+export function astJsonToAnsi(json: string, options?: RenderOptions | null): string;
+
+
+
+export function lintCarveWithOptions(source: string, options?: RenderOptions | null): LintWarning[];
+
+
+
+export function parseJsonWithOptions(source: string, options?: RenderOptions | null): string;
+export function astJsonToHtml(json: string, options?: RenderOptions | null): string;
+
+
+
+export function toHtmlWithReport(source: string, strict?: boolean | null, maximum?: number | null): RenderResult;
+export function toMarkdownWithReport(source: string, strict?: boolean | null, maximum?: number | null): RenderResult;
+export function toPlainTextWithReport(source: string, strict?: boolean | null, maximum?: number | null): RenderResult;
+export function toAnsiWithReport(source: string, strict?: boolean | null, maximum?: number | null): RenderResult;
+export function toCarveWithReport(source: string, strict?: boolean | null, maximum?: number | null): RenderResult;
+
+
+
+export function toMarkdownWithOptions(source: string, options?: RenderOptions | null): string;
+export function toPlainTextWithOptions(source: string, options?: RenderOptions | null): string;
+export function toAnsiWithOptions(source: string, options?: RenderOptions | null): string;
+export function toCarveWithOptions(source: string, options?: RenderOptions | null): string;
+
+
+
+/**
+ * A parser snapshot retained between editor updates. Call `free()` when done.
+ */
+export class ParserSession {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Apply byte edits; a rejected edit leaves the session unchanged.
+     */
+    edit(changes: string): string;
+    constructor(source: string);
+    /**
+     * The current result, with byte ranges and parser-work counters.
+     */
+    snapshot(): 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: SourcePatch): string;
+
+/**
+ * Render an AST-JSON document (PART 12) back to canonical Carve source.
+ *
+ * The round trip a host needs to SAVE an edited tree, rather than only display
+ * it. A tree holding something no Carve source can spell is refused rather
+ * than written approximately.
+ */
+export function astJsonToCarve(json: string): 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: IncludeOptions): IncludeExpansion;
+
+/**
+ * Every extension name this build accepts, in registry order.
+ *
+ * Taken from the engine, so a new extension is reachable as soon as the pin
+ * moves. Nothing here lists names.
+ */
+export function extensions(): string[];
+
+/**
+ * Convert BBCode source to Carve.
+ *
+ * Rejects input past the engine's `BBCODE_MAX_INPUT_LENGTH` rather than
+ * working on it: the importer's cost is superlinear in places, and a browser
+ * host cannot afford to find that out on the main thread.
+ */
+export function fromBbcode(source: string): string;
+
+/**
+ * Convert Djot source to Carve.
+ *
+ * Carve diverges from Djot deliberately - the emphasis delimiters are swapped,
+ * among others - so a Djot document is not Carve source and pasting one in
+ * renders wrongly rather than failing.
+ */
+export function fromDjot(source: string): string;
+
+export function fromHtml(source: string, mode?: string | null): MigrationResult;
+
+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.
+ *
+ * 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): 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.
+ *
+ * Returns an array of `{ line, column, rule, message, start, end }`. The rule
+ * ids are shared with carve-js and carve-php, so the same trigger reports the
+ * same id everywhere. Offsets count UTF-16 CODE UNITS, so they index the
+ * JavaScript string the caller holds; the engine answers in bytes and this
+ * wrapper converts (#164).
+ *
+ * Built as JS objects rather than a JSON string: a message carries arbitrary
+ * document text, and hand-rolled JSON escaping is where that goes wrong.
+ */
+export function lintCarve(source: string): 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.
+ */
+export function needsReview(source: string, current_version: string): boolean;
+
+/**
+ * Parse Carve source and return its AST as a JSON string.
+ *
+ * The PART 12 exchange shape (https://markup-carve.github.io/carve/ast-json):
+ * the same tree every Carve engine publishes, so a consumer written against
+ * one implementation reads another's output. The root carries exactly `type`,
+ * `children` and `srcByteLength`; frontmatter and footnote definitions are
+ * block nodes inside `children`, not root fields.
+ *
+ * Returns a STRING rather than a JS object: the caller runs `JSON.parse`, which
+ * is what a browser does natively and faster than building the object graph
+ * across the wasm boundary one property at a time. It also keeps the bytes
+ * available for a caller that stores or forwards them.
+ *
+ * Position tracking is on for this entry point and nowhere else. PART 12 §4
+ * lets an engine gate tracking behind a parse option but requires the
+ * serialized form to carry it, and rendering would pay for spans nobody reads.
+ */
+export function parseJson(source: string): 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, matching `createSourcePatch` ranges.
+ * `parseJson` positions count Unicode codepoints instead. 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 engine can reuse unchanged plain paragraphs. Other syntax falls back
+ * to a full parse. This function rebuilds the initial snapshot from source;
+ * use a parser session to retain it across edits.
+ */
+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;
+
+export function toCarve(source: string): string;
+
+/**
+ * Preview canonical formatting as a source-preserving patch.
+ */
+export function toCarvePatch(source: string): SourcePatch;
+
+export function toHtml(source: string): string;
+
+/**
+ * Render with the preview extension set enabled (`PREVIEW_EXTENSIONS`), so the
+ * WASM engine matches an extensions-on host such as the docs Playground rather
+ * than the core-only `toHtml`.
+ *
+ * The set is curated, not "everything the engine has": `heading-numbers` and
+ * `table-of-contents` rewrite a document that never asked for it, which is
+ * wrong for a preview. Callers who want an exact set pass `extensions` to
+ * `toHtmlWithOptions`, and `extensions()` reports what this build accepts.
+ *
+ * The optional second argument is the same **symbols map** as
+ * [`to_html_with_symbols`], with the same trusted-raw contract: mapped values
+ * are emitted UNESCAPED, so never feed it untrusted input.
+ */
+export function toHtmlFull(source: string, symbols?: object | null): string;
+
+/**
+ * Render with the core profile and a **symbols map**: `{ rocket: "🚀" }` (a
+ * plain object or a `Map`). A `:name:` symbol whose name is in the map renders
+ * the mapped value; an unmapped `:name:` stays literal `:name:` text, and the
+ * leading word-boundary guard still applies (`a:b:c`, `10:30:`,
+ * `me@example.com` never become symbols).
+ *
+ * Names and values must both be strings; a non-string value throws a JS
+ * `TypeError`.
+ *
+ * SECURITY: a mapped value is inserted as **TRUSTED RAW output in the target
+ * format** - it is NOT escaped, the same trust class as the static `renderers`
+ * map. So `{ b: "<b>x</b>" }` emits a real `<b>` element, not escaped text.
+ * This is deliberate: processor configuration is trusted. NEVER build a
+ * symbols map out of untrusted / user-supplied input.
+ */
+export function toHtmlWithSymbols(source: string, symbols?: object | null): string;
+
+export function toMarkdown(source: string): string;
+
+export function toPlainText(source: string): string;
+
+/**
+ * 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;