@jarenjs/md 0.34.0

package/dist/types/ast.d.ts

@@ -0,0 +1,181 @@
+/**
+ * @file The Markdown AST vocabulary: node constructors, shape guards
+ * and compiled walkers.
+ *
+ * Every node is a plain JSON object with a `type` discriminator;
+ * container nodes hold ordered content in `children`, literal nodes in
+ * `value` (normative vocabulary in docs/MD-FORMAT.md §4). The
+ * constructors exist so every node of a type is born with the same
+ * hidden class — the walkers and render tables then stay monomorphic.
+ */
+/** The document format version this package produces. */
+export declare const MD_VERSION = "0.1";
+export type MdNode = {
+    type: string;
+    [member: string]: any;
+};
+export type MdDocument = {
+    $md: string;
+    frontmatter: any;
+    ast: MdNode[];
+    meta: {
+        sourceUrl: string | null;
+        hash: string;
+        frontmatterLang: 'yaml' | 'json' | 'toml' | null;
+    };
+};
+/**
+ * @typedef {{ type: string, [member: string]: any }} MdNode
+ */
+/**
+ * @typedef {{ $md: string, frontmatter: any, ast: MdNode[],
+ *   meta: { sourceUrl: string|null, hash: string,
+ *           frontmatterLang: 'yaml'|'json'|'toml'|null } }} MdDocument
+ */
+/**
+ * Does this node hold its content in `children`? Plugin/custom nodes
+ * count when they actually carry a children array.
+ * @param {MdNode} node
+ * @returns {boolean}
+ */
+export declare function isContainerNode(node: MdNode): boolean;
+/** @param {MdNode[]} children @returns {MdNode} */
+export declare function paragraph(children: MdNode[]): MdNode;
+/** @param {number} depth @param {MdNode[]} children @returns {MdNode} */
+export declare function heading(depth: number, children: MdNode[]): MdNode;
+/** @returns {MdNode} */
+export declare function thematicBreak(): MdNode;
+/** @param {MdNode[]} children @returns {MdNode} */
+export declare function blockquote(children: MdNode[]): MdNode;
+/**
+ * @param {boolean} ordered
+ * @param {number|null} start
+ * @param {boolean} tight
+ * @param {MdNode[]} children
+ * @returns {MdNode}
+ */
+export declare function list(ordered: boolean, start: number | null, tight: boolean, children: MdNode[]): MdNode;
+/** @param {boolean|null} checked @param {MdNode[]} children @returns {MdNode} */
+export declare function listItem(checked: boolean | null, children: MdNode[]): MdNode;
+/**
+ * @param {string|null} lang
+ * @param {string|null} meta
+ * @param {string} value
+ * @returns {MdNode}
+ */
+export declare function code(lang: string | null, meta: string | null, value: string): MdNode;
+/** @param {string} value @returns {MdNode} */
+export declare function htmlBlock(value: string): MdNode;
+/**
+ * @param {(string|null)[]} align
+ * @param {MdNode[]} children
+ * @returns {MdNode}
+ */
+export declare function table(align: (string | null)[], children: MdNode[]): MdNode;
+/** @param {MdNode[]} children @returns {MdNode} */
+export declare function tableRow(children: MdNode[]): MdNode;
+/** @param {MdNode[]} children @returns {MdNode} */
+export declare function tableCell(children: MdNode[]): MdNode;
+/** @param {string} value @returns {MdNode} */
+export declare function text(value: string): MdNode;
+/** @param {MdNode[]} children @returns {MdNode} */
+export declare function emphasis(children: MdNode[]): MdNode;
+/** @param {MdNode[]} children @returns {MdNode} */
+export declare function strong(children: MdNode[]): MdNode;
+/** @param {MdNode[]} children @returns {MdNode} */
+export declare function strikethrough(children: MdNode[]): MdNode;
+/**
+ * @param {string} url
+ * @param {string|null} title
+ * @param {MdNode[]} children
+ * @returns {MdNode}
+ */
+export declare function link(url: string, title: string | null, children: MdNode[]): MdNode;
+/**
+ * A GFM literal autolink (`www.example.com`, `a@b.test`): a `link`, not
+ * a type of its own — every consumer, plugin and schema would otherwise
+ * have to learn a second spelling of the same thing. The `auto` flag is
+ * carried for the ONE consumer that has to tell them apart, the
+ * canonical printer, which prints it back bare (MD-FORMAT.md §4.7).
+ * @param {string} url the resolved destination (scheme inserted)
+ * @param {string} literal the text as the author wrote it
+ * @returns {MdNode}
+ */
+export declare function autolink(url: string, literal: string): MdNode;
+/**
+ * A GFM footnote definition: block content collected out of the flow
+ * and rendered once, at the end, if something cites it.
+ * @param {string} identifier the normalized label (matching key)
+ * @param {string} label the label as written
+ * @param {MdNode[]} children
+ * @returns {MdNode}
+ */
+export declare function footnoteDefinition(identifier: string, label: string, children: MdNode[]): MdNode;
+/**
+ * A GFM footnote reference: the citation mark in the text.
+ * @param {string} identifier the normalized label (matching key)
+ * @param {string} label the label as written
+ * @returns {MdNode}
+ */
+export declare function footnoteReference(identifier: string, label: string): MdNode;
+/**
+ * @param {string} url
+ * @param {string|null} title
+ * @param {string} alt
+ * @returns {MdNode}
+ */
+export declare function image(url: string, title: string | null, alt: string): MdNode;
+/** @param {string} value @returns {MdNode} */
+export declare function inlineCode(value: string): MdNode;
+/** @returns {MdNode} */
+export declare function hardBreak(): MdNode;
+/** @returns {MdNode} */
+export declare function softBreak(): MdNode;
+/**
+ * The generic escape hatch for constructs without a compiled-in plugin
+ * vocabulary (MD-FORMAT §4.4).
+ * @param {string} name
+ * @param {any} data
+ * @param {MdNode[]} [children]
+ * @returns {MdNode}
+ */
+export declare function custom(name: string, data: any, children?: MdNode[]): MdNode;
+/**
+ * Walk an AST (a node or an array of nodes) in document order, calling
+ * `visitor(node, parent, index)` pre-order. Returning `false` from the
+ * visitor skips the node's children.
+ *
+ * @param {MdNode | MdNode[]} root
+ * @param {(node: MdNode, parent: MdNode|null, index: number) => (boolean|void)} visitor
+ */
+export declare function walkAst(root: MdNode | MdNode[], visitor: (node: MdNode, parent: MdNode | null, index: number) => (boolean | void)): void;
+export type MdVisitFn = (node: MdNode, parent: MdNode | null, index: number) => (boolean | void);
+export type MdVisitSpec = MdVisitFn | {
+    enter?: MdVisitFn;
+    exit?: MdVisitFn;
+};
+/**
+ * @typedef {(node: MdNode, parent: MdNode|null, index: number) => (boolean|void)} MdVisitFn
+ * @typedef {MdVisitFn | { enter?: MdVisitFn, exit?: MdVisitFn }} MdVisitSpec
+ */
+/**
+ * Compile a per-type visitor spec into a dispatch table and walk with
+ * it. Handlers are keyed by node type, `'*'` matches every type; a
+ * handler is a function (pre-order) or `{ enter, exit }`. An `enter`
+ * returning `false` skips the children (exit still runs).
+ *
+ * The table is built once per call — pass the same spec object to reuse
+ * the compiled form across documents (a `WeakMap` memo keeps this
+ * allocation-free on repeat visits).
+ *
+ * @param {MdNode | MdNode[]} root
+ * @param {Record<string, MdVisitSpec>} visitors
+ */
+export declare function visitAst(root: MdNode | MdNode[], visitors: Record<string, MdVisitSpec>): void;
+/**
+ * The plain-text content of a node subtree (alt-text derivation,
+ * heading slugs, search indexing).
+ * @param {MdNode | MdNode[]} root
+ * @returns {string}
+ */
+export declare function textOf(root: MdNode | MdNode[]): string;

package/dist/types/bake.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @file `bake` — write a derived value back into the source text.
+ *
+ * A directive carries a value a machine derives and a human reads
+ * (directives.js). Baking materializes the current value INTO the
+ * committed file, which is the whole point: the document needs no
+ * runtime, GitHub renders it correctly, and the next re-derivation shows
+ * up as a diff a reviewer can look at instead of a number that quietly
+ * stopped being true.
+ *
+ * Two properties make it usable on documents people wrote by hand:
+ *
+ *  - **byte-local.** Only the spans between markers change. `toMarkdown`
+ *    is a canonicalizing printer, so re-printing a README would reflow
+ *    every list and re-wrap every table — correct markdown, and a diff
+ *    nobody can review. So `bake` splices the SOURCE, and a document
+ *    with no directives comes back the same bytes it went in as.
+ *  - **idempotent.** Baking an already-baked document changes nothing,
+ *    which is what lets a `--check` mode be "bake and compare".
+ *
+ * The trust level is different from mdx's, and the difference is the
+ * point: an mdx interpolation lands in a TEXT node and is never re-read
+ * as markdown, because it may carry untrusted data. A baked body is
+ * spliced into the source and WILL be re-parsed as markdown — a fact
+ * that is a whole table is exactly the use case. `bake` is therefore a
+ * build-time tool for input you control, and it says so here rather than
+ * leaving the two to be confused.
+ */
+export type BakeResult = {
+    text: string;
+    changed: boolean;
+    diagnostics: string[];
+    applied: {
+        key: string;
+        from: string;
+        to: string;
+    }[];
+};
+/**
+ * @typedef {{ text: string, changed: boolean, diagnostics: string[],
+ *   applied: { key: string, from: string, to: string }[] }} BakeResult
+ */
+/**
+ * Replace every directive body in `source` with a freshly resolved
+ * value.
+ *
+ * `resolve(key, directive)` returns the text to place between the
+ * markers, or `undefined` to leave that directive untouched. Throwing is
+ * allowed and is reported as a diagnostic — one bad derivation must not
+ * cost the rest of the document.
+ *
+ * @param {string} source the document text
+ * @param {{ ns: string, resolve: (key: string, directive: any) => (string|undefined),
+ *   parseOptions?: any }} options
+ * @returns {BakeResult}
+ */
+export declare function bake(source: string, options: {
+    ns: string;
+    resolve: (key: string, directive: any) => (string | undefined);
+    parseOptions?: any;
+}): BakeResult;

package/dist/types/compiler.d.ts

@@ -0,0 +1,141 @@
+/**
+ * @file compileMarkdown: parse once, then hand out specialized
+ * closures.
+ *
+ * A CompiledMd is the package's unit of work: the parsed document plus
+ * lazily-built, cached projections (vnode tree, canonical Markdown,
+ * frontmatter externals). Every projection is computed at most once
+ * per compiled document — calling `toVnode()` twice returns the same
+ * reference, which is what the view patcher's `===` fast path wants.
+ */
+export type MdNode = import('./ast.js').MdNode;
+export type MdDocument = import('./ast.js').MdDocument;
+export type MdParseOptions = import('./parser.js').MdParseOptions;
+export type MdCompileOptions = MdParseOptions & {
+    retainSource?: boolean;
+    html?: 'skip' | 'text';
+    headingIds?: boolean;
+    slugPrefix?: string;
+    headingAnchors?: boolean;
+    footnotesLabel?: string;
+    keyed?: boolean;
+};
+export type CompiledMd = {
+    /**
+     * the parsed document
+     */
+    doc: MdDocument;
+    /**
+     * `doc.ast`
+     */
+    ast: MdNode[];
+    /**
+     * `doc.frontmatter`
+     */
+    frontmatter: any;
+    /**
+     * `doc.meta.hash`
+     */
+    hash: string;
+    /**
+     * the source text (null when `retainSource: false`)
+     */
+    source: string | null;
+    /**
+     * the compiled plugin tables (internal contract)
+     */
+    tables: any;
+    /**
+     * cached vnode projection
+     */
+    toVnode: () => any;
+    /**
+     * cached canonical Markdown
+     */
+    toMarkdown: () => string;
+    /**
+     * pre-order walker over the AST
+     */
+    walk: (visitor: any) => void;
+    /**
+     * compiled per-type visitor
+     */
+    visit: (visitors: any) => void;
+    /**
+     * frontmatter as JSLT/query externals
+     */
+    externals: () => Record<string, any>;
+};
+/**
+ * @typedef {import('./ast.js').MdNode} MdNode
+ * @typedef {import('./ast.js').MdDocument} MdDocument
+ * @typedef {import('./parser.js').MdParseOptions} MdParseOptions
+ */
+/**
+ * @typedef {MdParseOptions & { retainSource?: boolean,
+ *   html?: 'skip'|'text', headingIds?: boolean, slugPrefix?: string,
+ *   headingAnchors?: boolean, footnotesLabel?: string,
+ *   keyed?: boolean }} MdCompileOptions
+ */
+/**
+ * The compiled closure bundle.
+ * @typedef {object} CompiledMd
+ * @property {MdDocument} doc the parsed document
+ * @property {MdNode[]} ast `doc.ast`
+ * @property {any} frontmatter `doc.frontmatter`
+ * @property {string} hash `doc.meta.hash`
+ * @property {string|null} source the source text (null when `retainSource: false`)
+ * @property {any} tables the compiled plugin tables (internal contract)
+ * @property {() => any} toVnode cached vnode projection
+ * @property {() => string} toMarkdown cached canonical Markdown
+ * @property {(visitor: any) => void} walk pre-order walker over the AST
+ * @property {(visitors: any) => void} visit compiled per-type visitor
+ * @property {() => Record<string, any>} externals frontmatter as JSLT/query externals
+ */
+/**
+ * Compile Markdown source (or an already-parsed MdDocument) into a
+ * closure bundle.
+ *
+ * @example
+ * const md = compileMarkdown('# Hi\n\nSome *text*.');
+ * md.toVnode();          // ['article', { class: 'md' }, ...]
+ * md.toMarkdown();       // '# Hi\n\nSome *text*.\n'
+ * md.externals();        // {} — no frontmatter
+ *
+ * @param {string | MdDocument} sourceOrDoc
+ * @param {MdCompileOptions} [options]
+ * @returns {CompiledMd}
+ */
+export declare function compileMarkdown(sourceOrDoc: string | MdDocument, options?: MdCompileOptions): CompiledMd;
+/**
+ * Flatten frontmatter into an externals object for the query/JSLT
+ * engines (MD-FORMAT.md §3.4). Only a frontmatter *object* contributes
+ * members; the engine-reserved names `root` and `path` are dropped.
+ * @param {any} frontmatter
+ * @returns {Record<string, any>}
+ */
+export declare function frontmatterExternals(frontmatter: any): Record<string, any>;
+/**
+ * Emit a `@jarenjs/forms`-consumable structure from a document whose
+ * frontmatter declares a schema (`$schema` object member or `form:`
+ * key). The caller injects the forms module (or the two functions it
+ * needs) — `@jarenjs/md` stays dependency-free:
+ *
+ * @example
+ * import * as forms from '@jarenjs/forms';
+ * const form = mdToForm(md.doc, forms);
+ * // { schema, fields, data } or null when no schema is declared
+ *
+ * @param {MdDocument} doc
+ * @param {{ buildFormModel: (schema: any) => any,
+ *           createInitialData: (schema: any) => any }} forms
+ * @returns {{ schema: any, fields: any, data: any } | null}
+ */
+export declare function mdToForm(doc: MdDocument, forms: {
+    buildFormModel: (schema: any) => any;
+    createInitialData: (schema: any) => any;
+}): {
+    schema: any;
+    fields: any;
+    data: any;
+} | null;

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

@@ -0,0 +1,101 @@
+/**
+ * @file The Markdown VISUAL COMPONENT — part two of the package.
+ *
+ * Everything below this line is presentation glue; the engine
+ * (`@jarenjs/md`) neither knows nor needs any of it. The component
+ * layer packages the engine for hosts that render:
+ *
+ *  - `createMdComponent()` — a batteries-included bundle: a memoized
+ *    `view()` projection for `@jarenjs/app` viewModels (reference-
+ *    stable, so unchanged sources patch in O(1)), `effects` entries
+ *    for the app effect registry (`md-load`, `md-parse`), and a
+ *    `hydrate()` pass for app-managed DOM;
+ *  - `styles/md.css` — the component's stylesheet (`.md` content
+ *    rhythm, `tok-*` token colors, mermaid placeholder), light/dark.
+ *
+ * The boundary is deliberate: the engine stays a headless data
+ * toolchain (text ↔ AST ↔ vnode values), the component owns defaults,
+ * memoization policy, CSS and app-registry shapes. See
+ * ARCHITECTURE.md §"Engine and component".
+ */
+export type MdDocument = import('../ast.js').MdDocument;
+export type CompiledMd = import('../compiler.js').CompiledMd;
+export type MdCompileOptions = import('../compiler.js').MdCompileOptions;
+export type MdComponentOptions = MdCompileOptions & {
+    base?: string | URL;
+    fetch?: typeof globalThis.fetch;
+    cache?: any;
+    memoLimit?: number;
+    onHydrateError?: (err: any) => void;
+};
+export type MdComponent = {
+    /**
+     * the compiled-in plugin set
+     */
+    plugins: any[];
+    /**
+     * memoized vnode projection
+     */
+    view: (sourceOrDoc: any) => any;
+    /**
+     * memoized compile
+     */
+    compile: (source: string) => CompiledMd;
+    /**
+     *   `md-load` and `md-parse` for `createApp({ effects })`
+     */
+    effects: Record<string, (props: any, dispatch: any) => any>;
+    /**
+     * run plugin hydrate hooks
+     * over already-mounted DOM (no-op without hydratable plugins)
+     */
+    hydrate: (container: any) => void;
+};
+/**
+ * @typedef {import('../ast.js').MdDocument} MdDocument
+ * @typedef {import('../compiler.js').CompiledMd} CompiledMd
+ * @typedef {import('../compiler.js').MdCompileOptions} MdCompileOptions
+ */
+/**
+ * @typedef {MdCompileOptions & {
+ *   base?: string | URL,
+ *   fetch?: typeof globalThis.fetch,
+ *   cache?: any,
+ *   memoLimit?: number,
+ *   onHydrateError?: (err: any) => void,
+ * }} MdComponentOptions
+ */
+/**
+ * The component bundle.
+ * @typedef {object} MdComponent
+ * @property {any[]} plugins the compiled-in plugin set
+ * @property {(sourceOrDoc: any) => any} view memoized vnode projection
+ * @property {(source: string) => CompiledMd} compile memoized compile
+ * @property {Record<string, (props: any, dispatch: any) => any>} effects
+ *   `md-load` and `md-parse` for `createApp({ effects })`
+ * @property {(container: any) => void} hydrate run plugin hydrate hooks
+ *   over already-mounted DOM (no-op without hydratable plugins)
+ */
+/**
+ * Create the Markdown component: one object that plugs the engine
+ * into an `@jarenjs/app` document (or any view-owning host).
+ *
+ * @example
+ * const md = createMdComponent();
+ * createApp(appDoc, {
+ *   effects: { ...md.effects },
+ *   viewModel: (state) => ({ ...state, article: md.view(state.articleSource) }),
+ * });
+ * // an action loads a document:
+ * //   { "effects": [{ "run": "md-load", "with": { "url": "$.url", "done": "article/loaded" } }] }
+ *
+ * @param {MdComponentOptions} [options]
+ * @returns {MdComponent}
+ */
+export declare function createMdComponent(options?: MdComponentOptions): MdComponent;
+/**
+ * The component's default plugin set: syntax highlighting on. A single
+ * shared array so `buildPluginTables` (and every memo hanging off it)
+ * compiles exactly once per process.
+ */
+export declare const DEFAULT_PLUGINS: import("../plugins/index.js").MdPlugin[];

package/dist/types/directives.d.ts

@@ -0,0 +1,126 @@
+/**
+ * @file Directives: comment-carried data that a machine derives and a
+ * human reads.
+ *
+ * ```markdown
+ * Jaren is <!--bm:jsonpath.ctsRatio-->23.1<!--/bm-->x faster on the CTS mean.
+ * ```
+ *
+ * Every markdown renderer on earth drops HTML comments, so GitHub, an
+ * editor preview and npm all show `Jaren is 23.1x faster` — plain,
+ * correct, static text with no runtime and no template syntax leaking
+ * into the prose. A directive-aware consumer reads the marker instead
+ * and can re-derive the value; `bake` writes the fresh value back into
+ * the source, so a re-derivation is a reviewable diff rather than a
+ * silent drift.
+ *
+ * That is the gap this closes for mdx, whose `{$.path}` spelling renders
+ * as literal gibberish anywhere the transform has not run — usable only
+ * in documents nobody reads raw.
+ *
+ * **The layer never interprets the payload.** `bm` puts a fact key
+ * there, `mdx` puts a query expression; the vocabulary belongs to the
+ * consumer, and this module owns exactly one thing — the marker grammar
+ * and the pairing — so two consumers cannot disagree about what a
+ * directive is.
+ *
+ * There are two ways in, because there are two questions:
+ *
+ *  - `scanDirectives(doc)` / `replaceDirectives(doc, …)` work on the
+ *    AST, which is what a *rendering* consumer has;
+ *  - `scanSourceDirectives(text)` works on the source, which is what a
+ *    *rewriting* consumer needs. The AST carries no source offsets (it
+ *    is plain JSON built for structural sharing, MD-FORMAT §1.1/§6), and
+ *    giving it any would change every node's shape and therefore every
+ *    content-hash key — so `bake` splices bytes instead, and both
+ *    scanners read the same grammar from the same function.
+ */
+export type MdNode = import('./ast.js').MdNode;
+export type AstDirective = {
+    ns: string;
+    key: string;
+    scope: 'block' | 'inline';
+    path: number[];
+    open: number;
+    close: number;
+    nodes: MdNode[];
+};
+export type SourceDirective = {
+    ns: string;
+    key: string;
+    scope: 'block' | 'inline';
+    start: number;
+    end: number;
+    bodyStart: number;
+    bodyEnd: number;
+    body: string;
+};
+/**
+ * Classify one comment. The single source of truth for what a directive
+ * marker IS — both scanners and every consumer go through here.
+ * @param {string} text the comment, `<!--` and `-->` included
+ * @returns {{ ns: string, key: string, closing: boolean } | null}
+ */
+export declare function parseMarker(text: string): {
+    ns: string;
+    key: string;
+    closing: boolean;
+} | null;
+/**
+ * Find every directive in a parsed document.
+ *
+ * A block directive's markers are `html` block nodes with body blocks
+ * between them; an inline directive's are `html` inline nodes inside one
+ * paragraph. Markers are paired within ONE container — an opener in a
+ * blockquote and a closer outside it are two unpaired markers, not one
+ * directive spanning a boundary that does not exist in the tree.
+ *
+ * @param {any} docOrAst an MdDocument, a CompiledMd or an AST array
+ * @param {{ ns?: string }} [options] restrict to one namespace
+ * @returns {{ directives: AstDirective[], diagnostics: string[] }}
+ */
+export declare function scanDirectives(docOrAst: any, options?: {
+    ns?: string;
+}): {
+    directives: AstDirective[];
+    diagnostics: string[];
+};
+/**
+ * Replace every directive body, returning a NEW document.
+ *
+ * The transform is pure and preserves reference equality for everything
+ * it does not touch, so the vnode emitter's per-node memo and the view
+ * patcher's `===` fast path are unaffected — the same contract the mdx
+ * pass keeps (MD-FORMAT §6).
+ *
+ * `replace` returns the nodes to put between the markers. Returning
+ * `undefined` leaves the directive alone.
+ *
+ * @param {any} docOrAst
+ * @param {{ ns?: string }} options
+ * @param {(directive: AstDirective) => (MdNode[]|undefined)} replace
+ * @returns {any} the same shape that came in (document or array)
+ */
+export declare function replaceDirectives(docOrAst: any, options: {
+    ns?: string;
+}, replace: (directive: AstDirective) => (MdNode[] | undefined)): any;
+/**
+ * Find every directive in SOURCE TEXT, with the offsets a rewriter
+ * needs.
+ *
+ * Comments inside fenced code are skipped: a fence showing a directive
+ * as an EXAMPLE is documentation about the layer, not an instance of it,
+ * and rewriting one would corrupt the very docs that explain it.
+ * (Indented code is not skipped — see the package README's note; the
+ * cross-check in `bake` is what catches the difference.)
+ *
+ * @param {string} source
+ * @param {{ ns?: string }} [options]
+ * @returns {{ directives: SourceDirective[], diagnostics: string[] }}
+ */
+export declare function scanSourceDirectives(source: string, options?: {
+    ns?: string;
+}): {
+    directives: SourceDirective[];
+    diagnostics: string[];
+};

package/dist/types/entities.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @file The HTML5 named character references, as CommonMark requires
+ * them (its "entity and numeric character references" section defers to
+ * the WHATWG HTML standard's table, all 2125 of them — a
+ * pragmatic subset is a dialect, not CommonMark).
+ *
+ * GENERATED by `scripts/generate-md-entities.js`; do not edit by hand.
+ *
+ * The table is packed as one string and split on first use rather than
+ * written as 2125 object properties: the packed form is a
+ * quarter of the source bytes and one allocation, and a document with no
+ * entity in it never pays for the Map at all.
+ */
+/**
+ * The named character reference table, built on first use.
+ * @returns {Map<string, string>}
+ */
+export declare function namedEntities(): Map<string, string>;
+/**
+ * Decode one character reference at `pos` (`&...;`). Returns null when it
+ * is not a valid reference — an `&` that starts nothing is ordinary text,
+ * which is why this reports rather than throws.
+ * @param {string} src
+ * @param {number} pos
+ * @returns {{ value: string, end: number } | null}
+ */
+export declare function scanEntity(src: string, pos: number): {
+    value: string;
+    end: number;
+} | null;
+/**
+ * Resolve backslash escapes and character references in a run of text.
+ *
+ * CommonMark processes both in the three places that are NOT inline
+ * content — link destinations, link titles and fence info strings — so
+ * they share this one pass rather than each re-deriving it.
+ * @param {string} text
+ * @returns {string}
+ */
+export declare function decodeReferences(text: string): string;