@markupme/core 0.0.0-stage → 0.1.0

package/dist/format.d.ts

@@ -0,0 +1,3 @@
+import type { Diagnostic } from './types.js';
+/** `file:line:col severity code message (rule)`: the format editors and CI annotate from. */
+export declare function formatDiagnostic(d: Diagnostic): string;

package/dist/format.js

@@ -0,0 +1,5 @@
+/** `file:line:col severity code message (rule)`: the format editors and CI annotate from. */
+export function formatDiagnostic(d) {
+    const where = [d.file ?? '<input>', d.line, d.column].filter((x) => x !== undefined).join(':');
+    return `${where} ${d.severity} ${d.code} ${d.message} (${d.rule})`;
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { formatDiagnostic } from './format.js';
+export { ALERT_TITLES, ALERT_TYPES, type AlertType } from './plugins/alerts.js';
+export { CALLOUTS, CONTAINERS, LEAF_DIRECTIVES, TEXT_DIRECTIVES } from './plugins/directives.js';
+export { headingId, type OutlineItem, outline } from './plugins/headings.js';
+export { buildToc, insertToc, type TocNode } from './plugins/toc.js';
+export { type BuiltinTransform, createProcessor, MarkupMeError, type Processor, parse, render, serialize, type TransformOptions, type TransformResult, transform, validate, } from './processor.js';
+export { markupmeSchema } from './render/schema.js';
+export type { SerializeFormat, SerializeOptions } from './serialize.js';
+export * from './types.js';
+export { type BlockChange, type DocumentStats, diff, escapeHtml, query, stats, stripPositions, visit, } from './util.js';
+export { RULES } from './validate.js';
+export { VERSION } from './version.js';

package/dist/index.js

@@ -0,0 +1,11 @@
+export { formatDiagnostic } from './format.js';
+export { ALERT_TITLES, ALERT_TYPES } from './plugins/alerts.js';
+export { CALLOUTS, CONTAINERS, LEAF_DIRECTIVES, TEXT_DIRECTIVES } from './plugins/directives.js';
+export { headingId, outline } from './plugins/headings.js';
+export { buildToc, insertToc } from './plugins/toc.js';
+export { createProcessor, MarkupMeError, parse, render, serialize, transform, validate, } from './processor.js';
+export { markupmeSchema } from './render/schema.js';
+export * from './types.js';
+export { diff, escapeHtml, query, stats, stripPositions, visit, } from './util.js';
+export { RULES } from './validate.js';
+export { VERSION } from './version.js';

package/dist/parse.d.ts

@@ -0,0 +1,6 @@
+import { type PluggableList } from 'unified';
+import { type MarkupMeDocument, type ParseOptions, type ProcessorOptions, type TocOptions } from './types.js';
+/** Syntax extensions shared by the parser and the serializer, so round trips keep every construct. */
+export declare function syntaxPlugins(opts: ProcessorOptions): PluggableList;
+export declare function tocOptions(opts: ProcessorOptions): TocOptions | undefined;
+export declare function parseDocument(source: string, opts: ProcessorOptions, parseOpts?: ParseOptions): MarkupMeDocument;

package/dist/parse.js

@@ -0,0 +1,66 @@
+import remarkDirective from 'remark-directive';
+import remarkFrontmatter from 'remark-frontmatter';
+import remarkGfm from 'remark-gfm';
+import remarkMath from 'remark-math';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+import { annotateAlerts } from './plugins/alerts.js';
+import { normalizeDirectives } from './plugins/directives.js';
+import { readFrontmatter } from './plugins/frontmatter.js';
+import { addHeadingIds } from './plugins/headings.js';
+import { insertToc } from './plugins/toc.js';
+import { SCHEMA_VERSION, } from './types.js';
+/** Syntax extensions shared by the parser and the serializer, so round trips keep every construct. */
+export function syntaxPlugins(opts) {
+    const list = [];
+    if (opts.gfm !== false)
+        list.push(remarkGfm);
+    if (opts.frontmatter !== false)
+        list.push([remarkFrontmatter, ['yaml', 'toml']]);
+    if (opts.directives !== false)
+        list.push(remarkDirective);
+    if (opts.math === true)
+        list.push(remarkMath);
+    for (const p of opts.plugins ?? [])
+        if (p.remarkPlugins)
+            list.push(...p.remarkPlugins);
+    return list;
+}
+export function tocOptions(opts) {
+    if (opts.toc === false)
+        return undefined;
+    return opts.toc === true || opts.toc === undefined ? {} : opts.toc;
+}
+export function parseDocument(source, opts, parseOpts = {}) {
+    const processor = unified().use(remarkParse).use(syntaxPlugins(opts));
+    const tree = processor.runSync(processor.parse(source));
+    const diagnostics = [];
+    const file = parseOpts.file;
+    const report = (d) => diagnostics.push(file ? { ...d, file } : d);
+    const doc = {
+        type: 'markupme-document',
+        schemaVersion: SCHEMA_VERSION,
+        source,
+        tree,
+        diagnostics,
+        ...(file ? { file } : {}),
+    };
+    if (opts.frontmatter !== false) {
+        const fm = readFrontmatter(tree, report);
+        if (fm)
+            doc.frontmatter = fm;
+    }
+    if (opts.directives !== false)
+        normalizeDirectives(tree, report);
+    if (opts.alerts !== false)
+        annotateAlerts(tree);
+    if (opts.headingIds !== false)
+        addHeadingIds(tree, report);
+    const toc = tocOptions(opts);
+    if (toc)
+        insertToc(tree, toc);
+    const ctx = { doc, options: opts, report };
+    for (const p of opts.plugins ?? [])
+        p.parse?.(tree, ctx);
+    return doc;
+}

package/dist/plugins/alerts.d.ts

@@ -0,0 +1,8 @@
+import type { Root } from 'mdast';
+export declare const ALERT_TYPES: readonly ['note', 'tip', 'important', 'warning', 'caution'];
+export type AlertType = (typeof ALERT_TYPES)[number];
+export declare const ALERT_TITLES: Record<AlertType, string>;
+/** Parse time: records `data.alert` on `> [!NOTE]` blockquotes. The tree text is untouched. */
+export declare function annotateAlerts(tree: Root): void;
+/** Render time (on a copy): turns annotated blockquotes into GitHub-style alert boxes. */
+export declare function presentAlerts(tree: Root): void;

package/dist/plugins/alerts.js

@@ -0,0 +1,50 @@
+import { visit } from 'unist-util-visit';
+export const ALERT_TYPES = ['note', 'tip', 'important', 'warning', 'caution'];
+const MARKER = /^\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\][ \t]*(?:\r?\n|$)/i;
+export const ALERT_TITLES = {
+    note: 'Note',
+    tip: 'Tip',
+    important: 'Important',
+    warning: 'Warning',
+    caution: 'Caution',
+};
+/** Parse time: records `data.alert` on `> [!NOTE]` blockquotes. The tree text is untouched. */
+export function annotateAlerts(tree) {
+    visit(tree, 'blockquote', (node) => {
+        const first = node.children[0];
+        if (first?.type !== 'paragraph')
+            return;
+        const text = first.children[0];
+        if (text?.type !== 'text')
+            return;
+        const m = MARKER.exec(text.value);
+        if (!m?.[1])
+            return;
+        node.data = { ...node.data, alert: m[1].toLowerCase() };
+    });
+}
+/** Render time (on a copy): turns annotated blockquotes into GitHub-style alert boxes. */
+export function presentAlerts(tree) {
+    visit(tree, 'blockquote', (node) => {
+        const type = node.data?.alert;
+        if (!type)
+            return;
+        const first = node.children[0];
+        const text = first.children[0];
+        if (text?.type === 'text')
+            text.value = text.value.replace(MARKER, '');
+        if (first.children.length === 1 && text?.type === 'text' && text.value === '')
+            node.children.shift();
+        const title = {
+            type: 'paragraph',
+            children: [{ type: 'text', value: ALERT_TITLES[type] }],
+            data: { hProperties: { className: ['markdown-alert-title'] } },
+        };
+        node.children.unshift(title);
+        node.data = {
+            ...node.data,
+            hName: 'div',
+            hProperties: { className: ['markdown-alert', `markdown-alert-${type}`], role: 'note' },
+        };
+    });
+}

package/dist/plugins/directives.d.ts

@@ -0,0 +1,16 @@
+import type { Root } from 'mdast';
+import type { Diagnostic } from '../types.js';
+/** `:::name` containers rendered as callout boxes. */
+export declare const CALLOUTS: string[];
+export declare const CONTAINERS: string[];
+/** `:name[label]` inline directives. */
+export declare const TEXT_DIRECTIVES: string[];
+/** `::name` leaf directives. `toc` is handled by the TOC plugin. */
+export declare const LEAF_DIRECTIVES: string[];
+/**
+ * Parse time: a text directive with no label and no attributes (`10:30`, `note:this`) is almost
+ * always prose, so it goes back to plain text. Unknown directives are reported, never dropped.
+ */
+export declare function normalizeDirectives(tree: Root, report: (d: Diagnostic) => void): void;
+/** Render time (on a copy): maps directives to HTML elements. */
+export declare function presentDirectives(tree: Root): void;

package/dist/plugins/directives.js

@@ -0,0 +1,126 @@
+import { toString as mdToString } from 'mdast-util-to-string';
+import { SKIP, visit } from 'unist-util-visit';
+/** `:::name` containers rendered as callout boxes. */
+export const CALLOUTS = [
+    'note',
+    'tip',
+    'info',
+    'important',
+    'warning',
+    'caution',
+    'danger',
+    'success',
+];
+export const CONTAINERS = [...CALLOUTS, 'details', 'figure', 'columns', 'column'];
+/** `:name[label]` inline directives. */
+export const TEXT_DIRECTIVES = ['kbd', 'abbr', 'mark', 'sub', 'sup', 'badge'];
+/** `::name` leaf directives. `toc` is handled by the TOC plugin. */
+export const LEAF_DIRECTIVES = ['toc', 'br'];
+function isLabel(node) {
+    return (node?.type === 'paragraph' &&
+        node.data?.directiveLabel === true);
+}
+/**
+ * Parse time: a text directive with no label and no attributes (`10:30`, `note:this`) is almost
+ * always prose, so it goes back to plain text. Unknown directives are reported, never dropped.
+ */
+export function normalizeDirectives(tree, report) {
+    visit(tree, (node, index, parent) => {
+        if (node.type !== 'textDirective' &&
+            node.type !== 'leafDirective' &&
+            node.type !== 'containerDirective')
+            return;
+        const d = node;
+        const hasAttrs = d.attributes && Object.keys(d.attributes).length > 0;
+        if (d.type === 'textDirective' &&
+            d.children.length === 0 &&
+            !hasAttrs &&
+            parent &&
+            index !== undefined) {
+            parent.children.splice(index, 1, { type: 'text', value: `:${d.name}` });
+            return [SKIP, index];
+        }
+        const known = d.type === 'textDirective'
+            ? TEXT_DIRECTIVES
+            : d.type === 'leafDirective'
+                ? LEAF_DIRECTIVES
+                : CONTAINERS;
+        if (!known.includes(d.name)) {
+            report({
+                code: 'MM009',
+                rule: 'unknown-directive',
+                severity: 'warning',
+                message: `Unknown directive "${d.name}" (${d.type.replace('Directive', '')}); its content is rendered as-is`,
+                line: d.position?.start.line,
+                column: d.position?.start.column,
+            });
+        }
+        return undefined;
+    });
+}
+function setH(node, hName, hProperties = {}) {
+    node.data = { ...node.data, hName, hProperties: { ...hProperties } };
+}
+/** Render time (on a copy): maps directives to HTML elements. */
+export function presentDirectives(tree) {
+    visit(tree, (node) => {
+        if (node.type !== 'textDirective' &&
+            node.type !== 'leafDirective' &&
+            node.type !== 'containerDirective')
+            return;
+        const d = node;
+        const attrs = d.attributes ?? {};
+        if (d.type === 'containerDirective') {
+            const label = isLabel(d.children[0]) ? d.children.shift() : undefined;
+            const title = attrs.title ?? (label ? mdToString(label) : undefined);
+            if (CALLOUTS.includes(d.name)) {
+                setH(d, 'div', { className: ['mm-callout', `mm-callout-${d.name}`], role: 'note' });
+                const heading = title ?? d.name.charAt(0).toUpperCase() + d.name.slice(1);
+                d.children.unshift({
+                    type: 'paragraph',
+                    children: label && !attrs.title ? label.children : [{ type: 'text', value: heading }],
+                    data: { hProperties: { className: ['mm-callout-title'] } },
+                });
+            }
+            else if (d.name === 'details') {
+                setH(d, 'details', attrs.open !== undefined ? { open: true } : {});
+                d.children.unshift({
+                    type: 'paragraph',
+                    children: label ? label.children : [{ type: 'text', value: title ?? 'Details' }],
+                    data: { hName: 'summary' },
+                });
+            }
+            else if (d.name === 'figure') {
+                setH(d, 'figure', { className: ['mm-figure'] });
+                if (label)
+                    d.children.push({
+                        type: 'paragraph',
+                        children: label.children,
+                        data: { hName: 'figcaption' },
+                    });
+            }
+            else if (d.name === 'columns')
+                setH(d, 'div', { className: ['mm-columns'] });
+            else if (d.name === 'column')
+                setH(d, 'div', { className: ['mm-column'] });
+            else
+                setH(d, 'div', { className: ['mm-directive', `mm-directive-${d.name}`] });
+        }
+        else if (d.type === 'textDirective') {
+            if (d.name === 'kbd' || d.name === 'mark' || d.name === 'sub' || d.name === 'sup')
+                setH(d, d.name);
+            else if (d.name === 'abbr')
+                setH(d, 'abbr', attrs.title ? { title: attrs.title } : {});
+            else if (d.name === 'badge')
+                setH(d, 'span', { className: ['mm-badge', `mm-badge-${attrs.type ?? 'default'}`] });
+            else
+                setH(d, 'span', { className: ['mm-directive', `mm-directive-${d.name}`] });
+        }
+        else {
+            if (d.name === 'br')
+                setH(d, 'br');
+            else
+                setH(d, 'div', { className: ['mm-directive', `mm-directive-${d.name}`] });
+        }
+    });
+}

package/dist/plugins/emoji.d.ts

@@ -0,0 +1,3 @@
+import type { Root } from 'mdast';
+/** Render time: replaces GitHub `:shortcode:` names with emoji. Unknown names stay as written. */
+export declare function presentEmoji(tree: Root): void;

package/dist/plugins/emoji.js

@@ -0,0 +1,22 @@
+import { gemoji } from 'gemoji';
+import { visit } from 'unist-util-visit';
+let names;
+function lookup() {
+    if (!names) {
+        names = new Map();
+        for (const entry of gemoji)
+            for (const name of entry.names)
+                names.set(name, entry.emoji);
+    }
+    return names;
+}
+const SHORTCODE = /:([a-z0-9_+-]+):/g;
+/** Render time: replaces GitHub `:shortcode:` names with emoji. Unknown names stay as written. */
+export function presentEmoji(tree) {
+    const map = lookup();
+    visit(tree, 'text', (node) => {
+        if (!node.value.includes(':'))
+            return;
+        node.value = node.value.replace(SHORTCODE, (whole, name) => map.get(name) ?? whole);
+    });
+}

package/dist/plugins/frontmatter.d.ts

@@ -0,0 +1,4 @@
+import type { Root } from 'mdast';
+import type { Diagnostic } from '../types.js';
+/** Reads the first YAML or TOML frontmatter block. Invalid data is reported, never thrown. */
+export declare function readFrontmatter(tree: Root, report: (d: Diagnostic) => void): Record<string, unknown> | undefined;

package/dist/plugins/frontmatter.js

@@ -0,0 +1,37 @@
+import { parse as parseToml } from 'smol-toml';
+import { parse as parseYaml } from 'yaml';
+/** Reads the first YAML or TOML frontmatter block. Invalid data is reported, never thrown. */
+export function readFrontmatter(tree, report) {
+    const node = tree.children[0];
+    if (!node || (node.type !== 'yaml' && node.type !== 'toml'))
+        return undefined;
+    const value = node.value;
+    try {
+        const data = node.type === 'yaml' ? parseYaml(value) : parseToml(value);
+        if (data === null || data === undefined)
+            return {};
+        if (typeof data !== 'object' || Array.isArray(data)) {
+            report({
+                code: 'MM010',
+                rule: 'invalid-frontmatter',
+                severity: 'error',
+                message: 'Frontmatter must be a mapping of keys to values',
+                line: node.position?.start.line,
+                column: 1,
+            });
+            return undefined;
+        }
+        return data;
+    }
+    catch (error) {
+        report({
+            code: 'MM010',
+            rule: 'invalid-frontmatter',
+            severity: 'error',
+            message: `Invalid ${node.type.toUpperCase()} frontmatter: ${error.message.split('\n')[0]}`,
+            line: node.position?.start.line,
+            column: 1,
+        });
+        return undefined;
+    }
+}

package/dist/plugins/headings.d.ts

@@ -0,0 +1,18 @@
+import type { Heading, Root } from 'mdast';
+import type { Diagnostic } from '../types.js';
+export declare function headingId(node: Heading): string | undefined;
+/**
+ * Gives every heading a GitHub-compatible id in `data.hProperties.id`.
+ * A trailing `{#custom-id}` sets the id explicitly; the marker is kept in `data.customId` so
+ * serialization can write it back.
+ */
+export declare function addHeadingIds(tree: Root, report: (d: Diagnostic) => void): void;
+export interface OutlineItem {
+    depth: number;
+    text: string;
+    id: string;
+    line?: number;
+    children: OutlineItem[];
+}
+/** The heading tree of a document. */
+export declare function outline(tree: Root): OutlineItem[];

package/dist/plugins/headings.js

@@ -0,0 +1,69 @@
+import GithubSlugger from 'github-slugger';
+import { toString as mdToString } from 'mdast-util-to-string';
+import { visit } from 'unist-util-visit';
+const CUSTOM_ID = /\s*\{#([A-Za-z][\w:.-]*)\}\s*$/;
+export function headingId(node) {
+    const id = node.data?.hProperties?.id;
+    return typeof id === 'string' ? id : undefined;
+}
+/**
+ * Gives every heading a GitHub-compatible id in `data.hProperties.id`.
+ * A trailing `{#custom-id}` sets the id explicitly; the marker is kept in `data.customId` so
+ * serialization can write it back.
+ */
+export function addHeadingIds(tree, report) {
+    const slugger = new GithubSlugger();
+    const seen = new Map();
+    visit(tree, 'heading', (node) => {
+        let id;
+        const last = node.children[node.children.length - 1];
+        if (last && last.type === 'text') {
+            const m = CUSTOM_ID.exec(last.value);
+            if (m?.[1]) {
+                id = m[1];
+                last.value = last.value.slice(0, m.index);
+                if (last.value === '')
+                    node.children.pop();
+                node.data = { ...node.data, customId: id };
+                slugger.slug(id);
+            }
+        }
+        id ??= slugger.slug(mdToString(node));
+        if (seen.has(id)) {
+            report({
+                code: 'MM003',
+                rule: 'duplicate-heading-id',
+                severity: 'warning',
+                message: `Heading id "${id}" is already used on line ${seen.get(id)}`,
+                line: node.position?.start.line,
+                column: node.position?.start.column,
+            });
+        }
+        else
+            seen.set(id, node.position?.start.line ?? 0);
+        node.data = { ...node.data, hProperties: { ...node.data?.hProperties, id } };
+    });
+}
+/** The heading tree of a document. */
+export function outline(tree) {
+    const roots = [];
+    const stack = [];
+    visit(tree, 'heading', (node) => {
+        const item = {
+            depth: node.depth,
+            text: mdToString(node),
+            id: headingId(node) ?? '',
+            line: node.position?.start.line,
+            children: [],
+        };
+        while (stack.length > 0 && stack[stack.length - 1].depth >= item.depth)
+            stack.pop();
+        const parent = stack[stack.length - 1];
+        if (parent)
+            parent.children.push(item);
+        else
+            roots.push(item);
+        stack.push(item);
+    });
+    return roots;
+}

package/dist/plugins/toc.d.ts

@@ -0,0 +1,18 @@
+import type { List, Parent, Root } from 'mdast';
+import type { TocOptions } from '../types.js';
+/** mdast node holding a generated table of contents. Serialized between `<!-- toc -->` markers. */
+export interface TocNode extends Parent {
+    type: 'toc';
+    children: List[];
+}
+declare module 'mdast' {
+    interface RootContentMap {
+        toc: TocNode;
+    }
+}
+export declare function buildToc(tree: Root, opts?: TocOptions): TocNode;
+/**
+ * Replaces `[[toc]]`, `::toc` and `<!-- toc --> … <!-- tocstop -->` with a generated TOC.
+ * Returns true when a TOC was placed.
+ */
+export declare function insertToc(tree: Root, opts?: TocOptions): boolean;

package/dist/plugins/toc.js

@@ -0,0 +1,103 @@
+import { toString as mdToString } from 'mdast-util-to-string';
+import { outline } from './headings.js';
+const OPEN = /^<!--\s*toc\s*-->$/i;
+const CLOSE = /^<!--\s*(?:tocstop|\/toc)\s*-->$/i;
+const INLINE_MARKER = /^\[\[?toc\]\]?$/i;
+function isMarker(node) {
+    if (node.type === 'paragraph')
+        return INLINE_MARKER.test(mdToString(node).trim());
+    if (node.type === 'leafDirective')
+        return node.name === 'toc';
+    return false;
+}
+function flatten(items, min, max) {
+    const out = [];
+    for (const item of items) {
+        if (item.depth >= min && item.depth <= max) {
+            out.push({ ...item, children: flatten(item.children, min, max) });
+        }
+        else
+            out.push(...flatten(item.children, min, max));
+    }
+    return out;
+}
+function toList(items) {
+    return {
+        type: 'list',
+        ordered: false,
+        spread: false,
+        children: items.map((item) => ({
+            type: 'listItem',
+            spread: false,
+            children: [
+                {
+                    type: 'paragraph',
+                    children: [
+                        {
+                            type: 'link',
+                            url: `#${item.id}`,
+                            children: [{ type: 'text', value: item.text }],
+                        },
+                    ],
+                },
+                ...(item.children.length > 0 ? [toList(item.children)] : []),
+            ],
+        })),
+    };
+}
+export function buildToc(tree, opts = {}) {
+    const min = opts.minDepth ?? 2;
+    const max = opts.maxDepth ?? 3;
+    return {
+        type: 'toc',
+        children: [toList(flatten(outline(tree), min, max))],
+        data: {
+            hName: 'nav',
+            hProperties: { className: ['mm-toc'], ariaLabel: opts.title ?? 'Table of contents' },
+        },
+    };
+}
+/**
+ * Replaces `[[toc]]`, `::toc` and `<!-- toc --> … <!-- tocstop -->` with a generated TOC.
+ * Returns true when a TOC was placed.
+ */
+export function insertToc(tree, opts = {}) {
+    const kids = tree.children;
+    let placed = false;
+    for (let i = 0; i < kids.length; i++) {
+        const node = kids[i];
+        if (node.type === 'html' && OPEN.test(node.value.trim())) {
+            let end = i + 1;
+            while (end < kids.length) {
+                const n = kids[end];
+                if (n.type === 'html' && CLOSE.test(n.value.trim()))
+                    break;
+                end++;
+            }
+            const removeTo = end < kids.length ? end + 1 : i + 1;
+            kids.splice(i, removeTo - i, buildToc(tree, opts));
+            placed = true;
+        }
+        else if (isMarker(node)) {
+            kids.splice(i, 1, buildToc(tree, opts));
+            placed = true;
+        }
+    }
+    const empty = (buildToc(tree, opts).children[0]?.children.length ?? 0) === 0;
+    if (!placed && !empty && opts.position && opts.position !== 'marker-only') {
+        let at = 0;
+        if (opts.position === 'after-title') {
+            const h1 = kids.findIndex((n) => n.type === 'heading' && n.depth === 1);
+            at = h1 >= 0 ? h1 + 1 : kids.findIndex((n) => n.type !== 'yaml' && n.type !== 'toml');
+            if (at < 0)
+                at = kids.length;
+        }
+        else {
+            const fm = kids.findIndex((n) => n.type !== 'yaml' && n.type !== 'toml');
+            at = fm < 0 ? kids.length : fm;
+        }
+        kids.splice(at, 0, buildToc(tree, opts));
+        placed = true;
+    }
+    return placed;
+}

package/dist/processor.d.ts

@@ -0,0 +1,46 @@
+import type { Root } from 'mdast';
+import { type SerializeOptions } from './serialize.js';
+import type { Diagnostic, MarkupMeDocument, MarkupMePlugin, ParseOptions, ProcessorOptions, RenderOptions, RenderResult, Rule, TocOptions, ValidateOptions } from './types.js';
+export type BuiltinTransform = 'toc' | 'normalize';
+export interface TransformOptions {
+    /** Built-in transforms by name, or plugins. Applied in order. */
+    plugins?: (BuiltinTransform | MarkupMePlugin)[];
+    toc?: TocOptions;
+}
+export interface TransformResult {
+    document: MarkupMeDocument;
+    diagnostics: Diagnostic[];
+}
+export interface Processor {
+    readonly options: Readonly<ProcessorOptions>;
+    parse(source: string, opts?: ParseOptions): MarkupMeDocument;
+    transform(doc: MarkupMeDocument, opts?: TransformOptions): TransformResult;
+    render(input: MarkupMeDocument | string, opts?: RenderOptions): Promise<RenderResult>;
+    serialize(input: MarkupMeDocument | Root, opts?: SerializeOptions): string;
+    validate(input: MarkupMeDocument | string, opts?: ValidateOptions): Diagnostic[];
+    /** Checks whether serializing and re-parsing keeps the tree. Reports what would change. */
+    roundTrip(doc: MarkupMeDocument): {
+        lossless: boolean;
+        markdown: string;
+        diagnostics: Diagnostic[];
+    };
+    /** The rules `validate` runs (built-in plus plugin rules). */
+    rules(): Rule[];
+}
+/**
+ * Creates an isolated processor. Options and plugins are fixed at creation; there is no global
+ * registry, so two processors never affect each other.
+ */
+export declare function createProcessor(options?: ProcessorOptions): Processor;
+/** Stable error with a code. */
+export declare class MarkupMeError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Parses with default options. */
+export declare const parse: (source: string, opts?: ParseOptions) => MarkupMeDocument;
+/** Renders with default options (HTML, sanitized). */
+export declare const render: (input: MarkupMeDocument | string, opts?: RenderOptions) => Promise<RenderResult>;
+export declare const transform: (doc: MarkupMeDocument, opts?: TransformOptions) => TransformResult;
+export declare const serialize: (input: MarkupMeDocument | Root, opts?: SerializeOptions) => string;
+export declare const validate: (input: MarkupMeDocument | string, opts?: ValidateOptions) => Diagnostic[];