/**
 * HTML <-> the pivot document.
 *
 * The other converters in this package each serve one CMS. This one serves a
 * shape no CMS produces and most templates do: a prop that is a string of HTML,
 * rendered with Astro's `set:html`, React's `dangerouslySetInnerHTML` or Vue's
 * `v-html`. A site that renders its own components stores those strings as
 * content, because from the template's point of view that is what they are.
 *
 * Before this existed the only declarable kind close enough was `richtext`, and
 * it is the wrong one: `richtext` means *a document*, and what arrives is a
 * string. The panel therefore rendered the markup literally —
 *
 *     Free template for <span class="hidden xl:inline">creating websites with</span> …
 *
 * — which a person cannot edit without breaking, and which is written back to
 * the site's own source file if they edit it anyway.
 *
 * ## What survives
 *
 * Tags with a pivot equivalent become nodes and marks. Everything else is
 * **preserved, not dropped**, which is the decision this file turns on. A
 * converter that discarded an unrecognised tag would corrupt the source on the
 * first save of a neighbouring field — the failure mode is silent, and the
 * content is gone by the time anyone reads the page. So:
 *
 *   - An unknown element wrapping text (`<span class="hidden xl:inline">…`)
 *     becomes a mark named `MARK.unknownHtml`, carrying its tag and its
 *     attributes in source order. The text inside stays editable; the wrapper
 *     rides along and is re-emitted around whatever the text became.
 *   - An unknown element with no children (`<div class="absolute inset-0 …">`,
 *     an `<img>`) becomes `avocadoUnknownBlock` holding its source markup. The
 *     panel shows it read-only, and `toHtml` re-emits it byte for byte.
 *
 * ## Round trip
 *
 * `toHtml(fromHtml(s))` is the contract, and it is *semantic* equality, not
 * byte equality. It **is** idempotent from the first pass —
 * `toHtml(fromHtml(toHtml(fromHtml(s))))` equals `toHtml(fromHtml(s))` — which
 * is the property that actually matters, because that is what decides whether
 * opening a page in the editor and saving it produces a diff for ever after.
 *
 * Measured against the pilot page's nineteen markup-bearing values, sixteen
 * come back byte-identical and three are normalised once:
 *
 *   - attribute quoting becomes double quotes, and a boolean attribute becomes
 *     `attr=""`;
 *   - stray whitespace inside a tag is dropped — `</span >` and `class="x" >`
 *     come back closed up;
 *   - loose text sitting after a block element is wrapped in the paragraph it
 *     already was — `<h3>Title</h3> Body` becomes `<h3>Title</h3><p> Body</p>`.
 *
 * All three are the parse writing down what the markup already meant. None of
 * them loses a character of content, and none of them recurs.
 *
 * One deliberate asymmetry: an input with no block-level tag at all — which is
 * every headline field we have seen — parses to a single paragraph and is
 * emitted back **without** a `<p>` wrapper. Emitting one would mean that
 * opening a page and saving it changed every title on it.
 */
import { type RichTextDoc } from "./doc.ts";
export declare function decodeEntities(s: string): string;
/**
 * Text, escaped for a text node.
 *
 * ` ` goes back out as `&nbsp;` rather than as a literal byte: it is
 * invisible in a diff otherwise, and a non-breaking space in a headline is
 * usually load-bearing — it is what keeps "Astro + Tailwind" off two lines.
 */
export declare function escapeHtmlText(s: string): string;
export declare function fromHtml(html: unknown): RichTextDoc;
export declare function toHtml(doc: unknown): string;