@jarenjs/md 0.34.0

package/dist/types/footnotes.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @file GFM footnotes: which definitions a document actually cites, in
+ * which order, and what to call them.
+ *
+ * Definitions stay where the author wrote them (the AST is the
+ * document, not the rendering), so both emitters need the same answer to
+ * the same three questions before they emit anything: which definitions
+ * are cited, what number each one gets, and which identifiers the
+ * reference and its back-references carry. That answer lives here once —
+ * two emitters minting ids from two implementations is exactly how a
+ * back-reference ends up pointing at nothing.
+ */
+export type MdNode = import('./ast.js').MdNode;
+export type Footnotes = {
+    defs: MdNode[];
+    numbers: Map<string, number>;
+    counts: Map<string, number>;
+    refs: WeakMap<MdNode, {
+        number: number;
+        occurrence: number;
+    }>;
+};
+/**
+ * @typedef {import('./ast.js').MdNode} MdNode
+ */
+/**
+ * @typedef {{ defs: MdNode[],
+ *   numbers: Map<string, number>,
+ *   counts: Map<string, number>,
+ *   refs: WeakMap<MdNode, { number: number, occurrence: number }> }} Footnotes
+ */
+/**
+ * The default identifier prefix for footnotes — GitHub's own.
+ *
+ * Unlike a heading id (MD-FORMAT.md §4.5), which defaults to no prefix
+ * because CommonMark asserts a bare heading and the primary consumer is
+ * a document the host wrote, a footnote id is emitted by the DEFAULT
+ * rendering of a feature whose whole point is a link between two places
+ * on one page. No spec example asserts a bare `fn-1`, so the safe
+ * default costs nothing and a host page keeps its own `#fn-1` for
+ * itself. `slugPrefix`, when given, replaces it.
+ */
+export declare const FOOTNOTE_PREFIX = "user-content-";
+/** The back-reference glyph GitHub uses. */
+export declare const BACKREF_MARK = "\u21A9";
+/**
+ * Collect a document's cited footnotes.
+ *
+ * Returns `null` when the AST holds no `footnoteDefinition` at all — the
+ * overwhelmingly common case, and the one that must cost nothing: the
+ * emitters compare that `null` to decide whether anything about footnote
+ * rendering can differ between two emissions.
+ *
+ * The result is memoized on the AST array, so re-rendering one document
+ * reuses it (and with it the vnode emitter's per-node memo); a
+ * transformed document is a different array and correctly gets fresh
+ * numbering.
+ *
+ * @param {MdNode[]} ast
+ * @returns {Footnotes|null}
+ */
+export declare function collectFootnotes(ast: MdNode[]): Footnotes | null;
+/**
+ * The `id` of a rendered footnote (the `<li>` in the section).
+ * @param {string} prefix @param {number} number
+ * @returns {string}
+ */
+export declare function footnoteId(prefix: string, number: number): string;
+/**
+ * The `id` of one citation. A footnote cited more than once needs one
+ * landing place per citation, or every back-reference would return the
+ * reader to the first.
+ * @param {string} prefix @param {number} number @param {number} occurrence
+ * @returns {string}
+ */
+export declare function footnoteRefId(prefix: string, number: number, occurrence: number): string;
+/**
+ * The accessible name of a back-reference: `↩` alone names nothing, and
+ * a footnote with several of them needs them told apart.
+ * @param {number} number @param {number} occurrence
+ * @returns {string}
+ */
+export declare function backrefLabel(number: number, occurrence: number): string;

package/dist/types/frontmatter.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @file Frontmatter extraction: YAML subset, JSON and TOML → plain JSON.
+ *
+ * Frontmatter is detected at the very top of the source only:
+ *
+ *  - `---`     opens a YAML-subset block, closed by `---` or `...`
+ *  - `---json` opens a JSON block, closed by `---`
+ *  - `{`       (as the first character) opens a JSON object closed by a
+ *              line that is exactly `}`
+ *  - `+++`     opens a TOML block, closed by `+++`
+ *
+ * Whatever the syntax, the result normalizes to one plain JSON value on
+ * the document. The parsers are written from scratch and dependency-free;
+ * an external TOML parser (e.g. `parseToml` from `@jarenjs/josl`) can be
+ * injected through `options.toml` to replace the built-in TOML subset.
+ *
+ * The YAML subset (normative limits in docs/MD-FORMAT.md §3):
+ * scalars (null/booleans/numbers/strings), single- and double-quoted
+ * strings, block maps and sequences by indentation, flow arrays and
+ * maps (multi-line while brackets are open), literal `|` and folded `>`
+ * block scalars with `-` chomping, and `#` comments. No anchors, no
+ * aliases, no tags, no multi-document streams, no complex keys.
+ */
+/** Raised for malformed frontmatter inside a detected fence. */
+export declare class MdFrontmatterError extends Error {
+    line: number;
+    /**
+     * @param {string} message
+     * @param {number} line 0-based line index inside the frontmatter block
+     */
+    constructor(message: string, line: number);
+}
+/**
+ * Split frontmatter off the top of a Markdown source.
+ *
+ * @param {string} source
+ * @param {{ toml?: (text: string) => any }} [options]
+ * @returns {{ data: any, body: string, lang: 'yaml'|'json'|'toml'|null }}
+ */
+export declare function parseFrontmatter(source: string, options?: {
+    toml?: (text: string) => any;
+}): {
+    data: any;
+    body: string;
+    lang: 'yaml' | 'json' | 'toml' | null;
+};
+/**
+ * Parse the YAML subset into plain JSON.
+ * @param {string} text
+ * @returns {any}
+ */
+export declare function parseYamlSubset(text: string): any;
+export type YamlState = {
+    lines: string[];
+    pos: number;
+};
+/**
+ * Parse the built-in TOML subset: `[table]` and `[[array-of-tables]]`
+ * headers with dotted paths, bare/quoted/dotted keys, basic and literal
+ * strings, integers (decimal/hex/octal/binary, `_` separators), floats,
+ * booleans, single- or multi-line flow arrays, inline tables, and `#`
+ * comments. Datetimes are kept as strings; multi-line strings are not
+ * supported (normative limits in docs/MD-FORMAT.md §3.3).
+ * @param {string} text
+ * @returns {Record<string, any>}
+ */
+export declare function parseTomlSubset(text: string): Record<string, any>;

package/dist/types/html.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @file Raw HTML in Markdown, parsed to vnodes through an allow-list.
+ *
+ * The vnode format has no unescaped output — deliberately: a tree of
+ * arrays cannot carry a half-open tag or an injected `<script>`, which
+ * is why `mdToVnode` has always either dropped raw HTML or shown it as
+ * text. This module is the third answer: PARSE the HTML and keep what an
+ * allow-list recognises, so `<details>` and `<img>` in a document render
+ * as themselves.
+ *
+ * The safety argument is structural rather than a promise about
+ * filtering strings. The output is a vnode tree, so:
+ *
+ * - an element not on the list contributes nothing but its children's
+ *   text — there is no path by which its markup reaches the DOM;
+ * - an attribute not on the list is dropped, so `on*` handlers,
+ *   `style` and `srcdoc` never exist to begin with;
+ * - `href`/`src` go through the same {@link sanitizeUrl} policy as
+ *   Markdown's own links, so `javascript:` cannot ride in on raw HTML
+ *   when it cannot ride in on `[x](…)`.
+ *
+ * What this is NOT: an HTML5 parser. It does not implement implicit
+ * end tags, foster parenting, or the tokenizer's error recovery, and it
+ * does not attempt to reproduce what a browser would build from
+ * malformed input. Unbalanced input closes at the end of the fragment.
+ * For hostile input the goal is that nothing survives that should not,
+ * not that the shape matches what a browser would have made of it.
+ *
+ * A host that wants different rules injects its own parser instead
+ * (`mdToVnode`'s `parseHtml` option) — this is the default, not the
+ * only, implementation.
+ */
+export type HtmlParseOptions = {
+    /**
+     * URL policy for
+     * `href`/`src` (default: the shared deny-list, as Markdown links use)
+     */
+    sanitizeUrl?: (url: string) => (string | null);
+};
+/**
+ * @typedef {object} HtmlParseOptions
+ * @property {(url: string) => (string|null)} [sanitizeUrl] URL policy for
+ *  `href`/`src` (default: the shared deny-list, as Markdown links use)
+ */
+/**
+ * Parse an HTML fragment into vnodes, keeping only what the allow-list
+ * recognises.
+ *
+ * @param {string} source the raw HTML of one Markdown html node
+ * @param {HtmlParseOptions} [options]
+ * @returns {any[]} vnodes and strings; empty when nothing survived
+ * @example
+ * parseHtmlFragment('<details><summary>More</summary>text</details>');
+ * // [['details', {}, ['summary', {}, 'More'], 'text']]
+ */
+export declare function parseHtmlFragment(source: string, options?: HtmlParseOptions): any[];
+/**
+ * Classify ONE tag — what CommonMark's inline phase hands out, since at
+ * that level a tag is not an element (`<b>bold</b>` is three siblings).
+ * Returns null when the source is not exactly one tag.
+ * @param {string} source
+ * @param {HtmlParseOptions} [options]
+ * @returns {{name: string, closing: boolean, complete: boolean,
+ *   drop: boolean, props: Record<string, any>|null} | null}
+ */
+export declare function parseHtmlTag(source: string, options?: HtmlParseOptions): {
+    name: string;
+    closing: boolean;
+    complete: boolean;
+    drop: boolean;
+    props: Record<string, any> | null;
+} | null;

package/dist/types/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @jarenjs/md - Markdown + frontmatter as JSON documents.
+ *
+ * parseMarkdown turns Markdown (CommonMark core + GFM tables,
+ * strikethrough, task lists, footnotes and autolink literals +
+ * YAML/JSON/TOML frontmatter) into a plain
+ * JSON AST the rest of the suite consumes natively: JSLT/JTLT and
+ * query documents transform it, `mdToVnode` projects it to
+ * @jarenjs/view vnodes with content-hash keys, `toMarkdown` prints
+ * canonical round-trip text, and `loadMarkdown`/`streamMarkdown` pull
+ * documents lazily from any URL with caching, AbortSignal and
+ * block-by-block streaming. Extensibility is compile-time plugins
+ * (`definePlugin`, `@jarenjs/md/plugins`) baked into dispatch tables.
+ *
+ * The normative contracts: docs/MD-FORMAT.md (AST + frontmatter),
+ * docs/PLUGINS.md (plugin system), docs/LOADER.md (loader).
+ */
+export { parseMarkdown, createIncrementalParser, buildPluginTables, } from './parser.js';
+export { compileMarkdown, frontmatterExternals, mdToForm, } from './compiler.js';
+export { loadMarkdown, streamMarkdown, createMdCache, defaultMdCache, } from './loader.js';
+export { toMarkdown } from './to-md.js';
+export { toHtml } from './to-html.js';
+export { mdToVnode, createMdRenderer, } from './to-vnode.js';
+export { scanDirectives, replaceDirectives, scanSourceDirectives, parseMarker, } from './directives.js';
+export { bake } from './bake.js';
+export { definePlugin } from './plugins/index.js';
+export { parseHtmlFragment, parseHtmlTag } from './html.js';
+export { MD_VERSION, walkAst, visitAst, textOf, isContainerNode, } from './ast.js';
+export { parseFrontmatter, parseYamlSubset, parseTomlSubset, MdFrontmatterError, } from './frontmatter.js';
+export { hashContent } from './utils.js';

package/dist/types/loader.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @file The lazy URL loader (docs/LOADER.md): cache, abort, streaming.
+ *
+ * `loadMarkdown` resolves any URL the platform `fetch` accepts into a
+ * compiled document. The shared LRU cache keys on normalized URL +
+ * plugin set, remembers `ETag`/`Last-Modified` validators, shares
+ * in-flight fetches, and revalidates stale entries in the background.
+ * When the response body is a `ReadableStream` the parser runs
+ * block-by-block as chunks arrive — `streamMarkdown` exposes that as
+ * an async iterator of completed top-level blocks.
+ */
+export type MdNode = import('./ast.js').MdNode;
+export type MdDocument = import('./ast.js').MdDocument;
+export type CompiledMd = import('./compiler.js').CompiledMd;
+export type MdCompileOptions = import('./compiler.js').MdCompileOptions;
+export type MdLoadOptions = MdCompileOptions & {
+    base?: string | URL;
+    signal?: AbortSignal;
+    cache?: MdCache | false;
+    fetch?: typeof globalThis.fetch;
+};
+export type MdCache = {
+    get: (key: string) => any;
+    set: (key: string, entry: any) => void;
+    delete: (key: string) => boolean;
+    clear: () => void;
+};
+/**
+ * @typedef {import('./ast.js').MdNode} MdNode
+ * @typedef {import('./ast.js').MdDocument} MdDocument
+ * @typedef {import('./compiler.js').CompiledMd} CompiledMd
+ * @typedef {import('./compiler.js').MdCompileOptions} MdCompileOptions
+ */
+/**
+ * @typedef {MdCompileOptions & {
+ *   base?: string | URL,
+ *   signal?: AbortSignal,
+ *   cache?: MdCache | false,
+ *   fetch?: typeof globalThis.fetch,
+ * }} MdLoadOptions
+ */
+/**
+ * @typedef {object} MdCache
+ * @property {(key: string) => any} get
+ * @property {(key: string, entry: any) => void} set
+ * @property {(key: string) => boolean} delete
+ * @property {() => void} clear
+ */
+/**
+ * A small LRU cache (Map re-insertion order).
+ * @param {number} [limit]
+ * @returns {MdCache}
+ */
+export declare function createMdCache(limit?: number): MdCache;
+/** The shared default cache instance. */
+export declare const defaultMdCache: MdCache;
+/**
+ * Load and compile a Markdown document from a URL (docs/LOADER.md §1).
+ *
+ * @example
+ * const md = await loadMarkdown('/docs/intro.md', { base: location.href });
+ * md.frontmatter; md.toVnode();
+ *
+ * @param {string | URL} url
+ * @param {MdLoadOptions} [options]
+ * @returns {Promise<CompiledMd>}
+ */
+export declare function loadMarkdown(url: string | URL, options?: MdLoadOptions): Promise<CompiledMd>;
+/**
+ * Stream a Markdown source, yielding completed top-level block nodes
+ * as their end becomes certain; the generator's return value is the
+ * finished MdDocument (docs/LOADER.md §4).
+ *
+ * Accepts a URL, a `Response`, a `ReadableStream`, or any (async)
+ * iterable of string/Uint8Array chunks.
+ *
+ * @example
+ * for await (const block of streamMarkdown('/big.md')) render(block);
+ *
+ * @param {any} urlOrStream
+ * @param {MdLoadOptions} [options]
+ * @returns {AsyncGenerator<MdNode, MdDocument>}
+ */
+export declare function streamMarkdown(urlOrStream: any, options?: MdLoadOptions): AsyncGenerator<MdNode, MdDocument>;

package/dist/types/mdx.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @file mdx = markdown × data. A markdown document renders DYNAMICALLY
+ * against a data document: inline interpolation, conditional sections
+ * and repeated sections, all driven by the data — still a pure
+ * `(doc, data) → doc` transform over the parsed AST, so everything
+ * downstream (`mdToVnode`, `toMarkdown`, the plugins) works unchanged.
+ *
+ * The template vocabulary reuses the suite's own query expressions —
+ * no new mini-language:
+ *
+ *  - `{$.path}` inline in TEXT interpolates a query expression over the
+ *    data (`$` is the data document; `$name` externals come from the
+ *    frontmatter and the enclosing `each` bindings). Code spans, code
+ *    blocks and raw HTML never interpolate.
+ *  - a paragraph of exactly `{#if <expr>}` … `{/if}` keeps its section
+ *    only when the expression is truthy (the query engine's boolean
+ *    view: null/false/''/0/[] are false).
+ *  - a paragraph of exactly `{#each <expr> as <name>}` … `{/each}`
+ *    repeats its section once per item, binding each as the external
+ *    `$<name>`. Sections nest.
+ *
+ * A directive must form its OWN paragraph — surround it with blank
+ * lines, or markdown's lazy continuation folds the next line into it
+ * and the directive reads as plain text.
+ *
+ * The expression COMPILER is injected (`compileJsonQuery` from
+ * `@jarenjs/json`), so this package's engine layer keeps its
+ * core+view-only dependency contract — the same seam philosophy the
+ * play surface uses for its renderers.
+ */
+/**
+ * Build the mdx transformer around an injected expression compiler.
+ * @param {{ compileQuery: (expr: string) => (data: any, externals?: any) => any }} options
+ *   `compileQuery` compiles one query expression (e.g. `compileJsonQuery`
+ *   from `@jarenjs/json`); compiled expressions are cached per source text
+ * @returns {{ transform: (doc: any, data: any) => any }}
+ *   `transform(doc, data)` — a parsed markdown doc + a data document in,
+ *   a NEW doc (directives resolved, text interpolated) out; never throws
+ *   on a bad expression — the error message renders in place, honestly
+ */
+export declare function createMdx(options: {
+    compileQuery: (expr: string) => (data: any, externals?: any) => any;
+}): {
+    transform: (doc: any, data: any) => any;
+};

package/dist/types/parser.d.ts

@@ -0,0 +1,116 @@
+/**
+ * @file The Markdown parser: block structure + inline parsing → AST.
+ *
+ * One pass over the source builds the block tree (a container stack of
+ * blockquotes/lists/items plus one open leaf), buffering each leaf's
+ * raw text; inline parsing runs once per leaf when it closes. Plugin
+ * extension points — fence claims, block rules, inline rules — are
+ * prebuilt tables consulted by indexed lookup in the hot loop
+ * (docs/PLUGINS.md); with no plugins the tables are shared empty maps.
+ *
+ * The same machinery runs batch (`parseMarkdown`) and incrementally
+ * (`createIncrementalParser`): blocks land in the output only when
+ * closed, so the incremental parser can hand out completed top-level
+ * blocks while later chunks are still arriving (docs/LOADER.md §4).
+ */
+export type MdNode = import('./ast.js').MdNode;
+export type MdDocument = import('./ast.js').MdDocument;
+export type MdParseOptions = {
+    /**
+     * compiled-in plugins (docs/PLUGINS.md)
+     */
+    plugins?: any[];
+    /**
+     * GFM tables/strikethrough/task lists (default true)
+     */
+    gfm?: boolean;
+    /**
+     * detect frontmatter (default true)
+     */
+    frontmatter?: boolean;
+    /**
+     * injectable TOML frontmatter parser
+     */
+    toml?: (text: string) => any;
+    /**
+     * recorded in `meta.sourceUrl`
+     */
+    sourceUrl?: string | null;
+};
+/**
+ * Merge a plugin array into the four dispatch tables (first plugin
+ * wins on every collision). Memoized by array identity so module-level
+ * plugin arrays compile exactly once.
+ * @param {any[] | undefined} plugins
+ */
+export declare function buildPluginTables(plugins: any[] | undefined): any;
+export type InlineCtx = {
+    defs: Map<string, {
+        url: string;
+        title: string | null;
+    }>;
+    footnotes?: Map<string, MdNode>;
+    inlines: Map<number, any[]>;
+    gfm: boolean;
+    ctx: any;
+    unresolved?: boolean;
+    deferred?: {
+        node: any;
+        raw: string;
+    }[];
+};
+/**
+ * The inline parsing context threaded through one document.
+ * @typedef {{ defs: Map<string, {url: string, title: string|null}>,
+ *   footnotes?: Map<string, MdNode>,
+ *   inlines: Map<number, any[]>, gfm: boolean, ctx: any,
+ *   unresolved?: boolean, deferred?: {node: any, raw: string}[] }} InlineCtx
+ */
+/**
+ * Parse inline Markdown text into inline AST nodes.
+ * @param {string} src
+ * @param {InlineCtx} ictx
+ * @returns {MdNode[]}
+ */
+export declare function parseInlines(src: string, ictx: InlineCtx): MdNode[];
+/**
+ * Resolve the buffered raw text of finished blocks into inline
+ * children (paragraphs, headings, table cells, task-list markers).
+ * Runs once per block, after which the `raw` buffers are gone.
+ * @param {MdNode[]} blocks
+ * @param {InlineCtx} ictx
+ */
+export declare function finishBlocks(blocks: MdNode[], ictx: InlineCtx): void;
+/**
+ * Parse Markdown source into an MdDocument (frontmatter + AST).
+ *
+ * @example
+ * parseMarkdown('# Hi').ast
+ * // [{ type: 'heading', depth: 1, children: [{ type: 'text', value: 'Hi' }] }]
+ *
+ * @param {string} source
+ * @param {MdParseOptions} [options]
+ * @returns {MdDocument}
+ */
+export declare function parseMarkdown(source: string, options?: MdParseOptions): MdDocument;
+/**
+ * The incremental parsing core behind `streamMarkdown` (docs/LOADER.md
+ * §4): feed chunks, collect completed top-level blocks per feed, and
+ * flush the tail with `end()`.
+ *
+ * Frontmatter resolves as soon as its closing fence arrives; reference
+ * definitions apply to blocks completed after them (the documented
+ * streaming limitation).
+ *
+ * @param {MdParseOptions} [options]
+ * @returns {{
+ *   feed: (chunk: string) => MdNode[],
+ *   end: () => MdDocument,
+ *   frontmatter: any,
+ * }}
+ */
+export declare function createIncrementalParser(options?: MdParseOptions): {
+    feed: (chunk: string) => MdNode[];
+    end: () => MdDocument;
+    frontmatter: any;
+};

package/dist/types/plugins/highlight.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @file Syntax highlighting for fenced code blocks (PLUGINS.md §6.2).
+ *
+ * Built-in mode is a zero-dependency single-pass tokenizer driven by
+ * compact grammar tables — a keyword set, comment/string delimiters
+ * and punctuation classes — compiled to closures once at module load.
+ * No regex runs in the token loop. Adapter mode puts shiki/prism/
+ * highlight.js behind the same `{ kind, value }` token contract.
+ *
+ * Token kinds: kw str num com pun id op lit — rendered as
+ * `span.tok-{kind}` (plain `id` runs render as bare text).
+ */
+export type Token = {
+    kind: 'kw' | 'str' | 'num' | 'com' | 'pun' | 'id' | 'op' | 'lit';
+    value: string;
+};
+export type MdGrammar = {
+    keywords?: string[];
+    literals?: string[];
+    /**
+     * comment-to-end-of-line prefixes
+     */
+    lineComments?: string[];
+    /**
+     * open/close pair
+     */
+    blockComment?: [string, string];
+    /**
+     * string delimiter characters
+     */
+    strings?: string;
+    /**
+     * recognize number literals
+     */
+    numbers?: boolean;
+    /**
+     * extra identifier characters (e.g. `-` for CSS)
+     */
+    extraId?: string;
+};
+/** The canonical names of the shipped grammars (aliases resolve too). */
+export declare const GRAMMAR_NAMES: readonly string[];
+/**
+ * Tokenize `code` with the built-in grammar for `lang`. Returns null
+ * when no grammar covers the language.
+ * @param {string} code
+ * @param {string|null} lang
+ * @returns {Token[] | null}
+ */
+export declare function tokenizeCode(code: string, lang: string | null): Token[] | null;
+/**
+ * The syntax-highlighting plugin: takes over rendering of `code`
+ * nodes. `adapter(code, lang)` may return tokens (shiki/prism/hljs
+ * behind the shared contract) or null to fall back to the built-in
+ * grammars, then to plain text.
+ *
+ * @param {{ grammars?: Record<string, MdGrammar>,
+ *           adapter?: (code: string, lang: string|null) => (Token[] | null) }} [config]
+ * @returns {import('./index.js').MdPlugin}
+ */
+export declare function highlightPlugin(config?: {
+    grammars?: Record<string, MdGrammar>;
+    adapter?: (code: string, lang: string | null) => (Token[] | null);
+}): import('./index.js').MdPlugin;

package/dist/types/plugins/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @file Plugin registry helpers and the reference plugins.
+ *
+ * A plugin is data, validated and frozen at definition time; the
+ * parser and vnode emitter bake plugin arrays into dispatch tables at
+ * compile time (the normative contract lives in docs/PLUGINS.md).
+ */
+export type MdPlugin = {
+    /**
+     * unique kebab-case identifier
+     */
+    name: string;
+    /**
+     * fenced-code claims by info-string first word
+     */
+    fences?: string[];
+    /**
+     * block rule descriptors ({ chars, start, continue, close })
+     */
+    blocks?: any[];
+    /**
+     * inline rule descriptors ({ char, scan })
+     */
+    inlines?: any[];
+    /**
+     * the AST type this plugin emits/renders
+     */
+    node?: string;
+    /**
+     * pure vnode renderer
+     */
+    render?: (node: any, h: any, ctx: any) => any;
+    /**
+     * pure HTML-string
+     * renderer, for `toHtml`. Independent of `render`: a plugin may serve
+     * one emitter, the other, or both (docs/PLUGINS.md §5.1)
+     */
+    toHtml?: (node: any, ctx: any) => string;
+    /**
+     * browser-only upgrade
+     */
+    hydrate?: (el: any, node: any, ctx: any) => any;
+};
+/**
+ * @typedef {object} MdPlugin
+ * @property {string} name unique kebab-case identifier
+ * @property {string[]} [fences] fenced-code claims by info-string first word
+ * @property {any[]} [blocks] block rule descriptors ({ chars, start, continue, close })
+ * @property {any[]} [inlines] inline rule descriptors ({ char, scan })
+ * @property {string} [node] the AST type this plugin emits/renders
+ * @property {(node: any, h: any, ctx: any) => any} [render] pure vnode renderer
+ * @property {(node: any, ctx: any) => string} [toHtml] pure HTML-string
+ *   renderer, for `toHtml`. Independent of `render`: a plugin may serve
+ *   one emitter, the other, or both (docs/PLUGINS.md §5.1)
+ * @property {(el: any, node: any, ctx: any) => any} [hydrate] browser-only upgrade
+ */
+/**
+ * Validate and freeze a plugin spec (docs/PLUGINS.md §1).
+ * @param {MdPlugin} spec
+ * @returns {MdPlugin}
+ */
+export declare function definePlugin(spec: MdPlugin): MdPlugin;
+export { highlightPlugin, tokenizeCode, GRAMMAR_NAMES } from './highlight.js';
+export { mermaidPlugin } from './mermaid.js';

package/dist/types/plugins/mermaid.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @file Mermaid diagram support (PLUGINS.md §6.1).
+ *
+ * The **native** plugin from `@jarenjs/mermaid`: a self-frozen
+ * `MdPlugin`-shaped object whose `render` parses the fence source and
+ * emits pure-vnode SVG synchronously (SSR-safe, no injected `mermaid`
+ * instance, no `innerHTML`). The dependency arrow points md → mermaid
+ *, and `@jarenjs/mermaid/plugin` does not import
+ * `definePlugin`, so there is no cycle. Consumers who never use it
+ * tree-shake it away (`sideEffects:false`).
+ */
+export { mermaidPlugin, refreshMermaidFence } from '@jarenjs/mermaid/plugin';