/**
 * XML Encoding / Decoding Utilities
 *
 * Self-contained XML entity encoding and decoding functions.
 */
/**
 * Decode XML entities in a string.
 *
 * Handles named entities (`<`, `>`, `&`, `"`, `'`)
 * and numeric character references (`{`, `{`).
 *
 * Security: validates numeric code points against the XML 1.0 `Char`
 * production (rejects NUL, forbidden C0 controls, surrogates,
 * noncharacters, and out-of-range code points). Malformed numeric
 * refs are left untouched in the output so downstream layers (e.g. a
 * re-encoder that strips them) can distinguish "author meant this" from
 * "we couldn't decode this".
 *
 * Fast-path: returns the original string if no `&` is found.
 */
export declare function xmlDecode(text: string): string;
/**
 * Encode special characters for XML output.
 *
 * Escapes `<`, `>`, `&`, `"`, `'` to their entity equivalents.
 * Strips invalid XML control characters (0x00-0x08, 0x0B-0x0C, 0x0E-0x1F, 0x7F)
 * and lone surrogates (0xD800-0xDFFF without a pair).
 *
 * Optimized: uses a lookup table and manual scan instead of regex for
 * maximum throughput on the hot path (called per attribute/text value).
 */
export declare function xmlEncode(text: string): string;
/**
 * Encode a value for use in a double-quoted XML attribute.
 *
 * Does everything {@link xmlEncode} does (escape `<>&"'`, strip invalid
 * control chars and lone surrogates) PLUS encodes `\t`, `\n`, `\r` as
 * numeric character references (`&#x9;`, `&#xA;`, `&#xD;`).
 *
 * The extra whitespace handling is required by XML 1.0 §3.3.3
 * (attribute-value normalisation), which replaces every literal
 * whitespace character inside an attribute value with a single space
 * at parse time. Without the numeric-ref encoding, `"foo\nbar"` written
 * into an attribute round-trips as `"foo bar"` — the newline is gone.
 * Parsers / validators never collapse numeric character references, so
 * `&#xA;` survives verbatim.
 *
 * Use this for every attribute value in XML output that needs to
 * round-trip exactly (OOXML chart / sidecar / pivot content, relationship
 * targets, anything later re-parsed by another tool).
 */
export declare function xmlEncodeAttr(value: string): string;
/**
 * Validate an XML element or attribute name against injection attacks.
 *
 * Rejects:
 * - Empty names
 * - Names containing whitespace, `<`, `>`, `"`, `'`, `/`, `=`, `&`
 * - Names starting with a digit, `-`, or `.`
 *
 * This is NOT a full XML Name validation (which requires Unicode NameStartChar
 * tables). It is a focused security check to prevent markup injection.
 */
export declare function validateXmlName(name: string): void;
/**
 * Encode text for a CDATA section, stripping XML 1.0-illegal
 * characters first and then splitting on `]]>` to produce valid
 * output.
 *
 * CDATA is not a magic passthrough: only the five structural entities
 * are skipped, but every other XML Char production rule still applies.
 * A user string that carries `\x08` or a lone surrogate half wraps
 * into a CDATA section that every conformant parser rejects. Strip
 * them first (same sanitisation as {@link xmlEncode} / the chart
 * module's `escapeXml`) so CDATA output stays well-formed.
 *
 * The sequence `]]>` cannot appear inside CDATA, so each occurrence is split
 * into adjacent CDATA sections: `<![CDATA[...]]]]><![CDATA[>...]]>`.
 */
export declare function encodeCData(text: string): string;
/**
 * Strip characters that XML 1.0 forbids from text / attribute /
 * CDATA content, plus DEL (0x7F) as a project-policy extension.
 *
 * The XML 1.0 Char production allows: `#x9 | #xA | #xD |
 * [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]`. So the
 * disallowed ranges are:
 *   - C0 controls other than `\t` `\n` `\r` (`0x00-0x08`, `0x0B`,
 *     `0x0C`, `0x0E-0x1F`),
 *   - lone UTF-16 surrogate halves (`0xD800-0xDFFF` not in a valid
 *     pair),
 *   - the noncharacters `0xFFFE` / `0xFFFF`.
 *
 * `0x7F` (DEL) is TECHNICALLY legal per the XML spec — it falls
 * within the `[#x20-#xD7FF]` range — but some downstream consumers
 * (older Excel versions, strict SAX libraries) choke on it. We strip
 * it as a defence-in-depth measure; the comment that previously
 * claimed "XML 1.0 forbids DEL" was incorrect.
 *
 * Exported so `chart-utils.ts` and any other module that needs the
 * same sanitisation can share a single implementation instead of
 * carrying a local copy that drifts on edge cases.
 */
export declare function stripXmlIllegalChars(text: string): string;
/**
 * Validate that text is legal for an XML comment.
 *
 * XML spec: comments must not contain `--` and must not end with `-`.
 * @throws {XmlError} if the text is invalid.
 */
export declare function validateCommentText(text: string): void;
/** Default XML declaration attributes (`version`, `encoding`, `standalone`). */
export declare const StdDocAttributes: Readonly<Record<string, string>>;