@graphty/graph-io 0.3.25 → 0.3.26

package/dist/src/common/xml.js

@@ -8,11 +8,13 @@
  * instead of re-reading the token from its `<`, and line numbers are counted from a cached next
  * line-break position, so a document without line breaks costs the same as one with them.
  *
- * What it handles: the XML declaration and processing instructions (skipped), comments (skipped),
+ * What it handles: the XML declaration and processing instructions (skipped), comments (skipped;
+ * a `--` inside one, which XML 1.0 forbids, is accepted: a comment carries no data and banner
+ * comments such as `<!-- ----- -->` are common in hand-written files),
  * CDATA sections (text), a DOCTYPE with an internal subset (skipped; entity declarations are not
  * expanded, so an unknown entity reference is a syntax error), the five predefined entities and
  * numeric character references (decimal and hexadecimal) in text and attribute values, attribute
- * value whitespace normalisation, end-of-line normalisation (CR LF and lone CR become LF), and
+ * value whitespace normalization, end-of-line normalization (CR LF and lone CR become LF), and
  * well-formedness: matching end tags, one root element, no text outside it, no duplicate
  * attributes, no unterminated markup at the end of the input. Namespaces are not resolved; element
  * and attribute names are reported as written (with their prefix).
@@ -26,7 +28,11 @@
  */
 import { XML_ILLEGAL_CHAR_CODE } from "./codes.js";
 import { isNameChar } from "./export.js";
-/** A well-formedness or syntax error, with the line it was found on. */
+import { agree, plural } from "./plural.js";
+/**
+ * A well-formedness or syntax error, with the line it was found on.
+ * @category Plugin helpers
+ */
 export class XmlSyntaxError extends Error {
     /**
      * Create the error.
@@ -39,6 +45,21 @@ export class XmlSyntaxError extends Error {
         this.line = line;
     }
 }
+/**
+ * The input holds no markup at all (empty, whitespace only, a byte order mark only): an importer
+ * reports it as E_EMPTY_INPUT rather than as a syntax error.
+ * @category Plugin helpers
+ */
+export class XmlEmptyInputError extends XmlSyntaxError {
+    /**
+     * Create the error.
+     * @param line - the 1-based line where the input ended
+     */
+    constructor(line) {
+        super("the input is empty: no root element", line);
+        this.name = "XmlEmptyInputError";
+    }
+}
 /** How far Cytoscape's bare-ampersand repair looks for the `;` that ends an entity reference. */
 const BARE_AMPERSAND_LOOKAHEAD = 7;
 /** A numeric character reference at the start of a text: `&#123;` or `&#x1F;`. */
@@ -62,6 +83,7 @@ const OPEN_BRACKET = 91;
 const CLOSE_BRACKET = 93;
 const BANG = 33;
 const DASH = 45;
+const QUESTION = 63;
 /** The longest entity reference held back at a chunk boundary (`&#x10FFFF;` is 10 characters). */
 const MAX_ENTITY_LENGTH = 16;
 /** Markup shorter than this (`<![CDATA[` is 9 characters) cannot be classified yet. */
@@ -108,10 +130,20 @@ const ILLEGAL_CHAR = new RegExp(`[${String.fromCharCode(0)}-${String.fromCharCod
  * written even as a character reference, so a conforming parser rejects the whole document.
  * @param text - the text
  * @returns true when the text cannot appear in an XML 1.0 document
+ * @category Plugin helpers
  */
 export function hasIllegalXmlChar(text) {
     return ILLEGAL_CHAR.test(text);
 }
+/**
+ * Where the first character XML 1.0 forbids is in a text.
+ * @param text - the text
+ * @returns its index, or -1
+ */
+function illegalCharIndex(text) {
+    const match = ILLEGAL_CHAR.exec(text);
+    return match === null ? -1 : match.index;
+}
 /**
  * The loss notes of the texts a snapshot holds that no XML 1.0 document can carry (see
  * hasIllegalXmlChar): one E_XML_ILLEGAL_CHAR note per column (node, edge and graph string / dict /
@@ -119,6 +151,7 @@ export function hasIllegalXmlChar(text) {
  * the first such text. Shared by the GEXF and GraphML exporters' check().
  * @param snapshot - the snapshot
  * @returns the notes, empty when every text is writable
+ * @category Plugin helpers
  */
 export function xmlIllegalTextNotes(snapshot) {
     const notes = [];
@@ -132,7 +165,7 @@ export function xmlIllegalTextNotes(snapshot) {
     if (ids > 0) {
         notes.push(Object.freeze({
             code: XML_ILLEGAL_CHAR_CODE,
-            message: `${ids} node id(s) hold a character XML 1.0 cannot carry; export() will throw`,
+            message: `${ids} node id${plural(ids)} ${agree(ids, "holds", "hold")} a character XML 1.0 cannot carry; the save fails`,
             column: null,
             count: ids,
         }));
@@ -147,7 +180,7 @@ export function xmlIllegalTextNotes(snapshot) {
             if (bad > 0) {
                 notes.push(Object.freeze({
                     code: XML_ILLEGAL_CHAR_CODE,
-                    message: `${domain} column "${column.meta.name}": ${bad} value(s) hold a character XML 1.0 cannot carry; export() will throw`,
+                    message: `${domain} column "${column.meta.name}": ${bad} value${plural(bad)} ${agree(bad, "holds", "hold")} a character XML 1.0 cannot carry; the save fails`,
                     column: column.meta.name,
                     count: bad,
                 }));
@@ -180,22 +213,44 @@ function countIllegalRows(column) {
     }
     return bad;
 }
-/** The encoding pseudo-attribute of an XML declaration at the very start of a document. */
+/**
+ * The encoding pseudo-attribute of an XML declaration at the very start of a document (one
+ * anywhere else is a syntax error of the tokenizer).
+ */
 const XML_DECLARED_ENCODING = /^<\?xml\s[^>]*?\bencoding\s*=\s*["']([A-Za-z][A-Za-z0-9._-]*)["']/;
 /**
  * The encoding an XML document declares in its prolog (`<?xml version="1.0" encoding="..."?>`),
  * for the shared byte decoder (common/input.ts).
  * @param head - the start of the document, decoded as windows-1252
  * @returns the declared label, or null when there is no declaration or it names no encoding
+ * @category Plugin helpers
  */
 export function xmlDeclaredEncoding(head) {
     const match = XML_DECLARED_ENCODING.exec(head);
     return match === null ? null : match[1];
 }
+/**
+ * The head of a document as text for an XML format's sniff(): UTF-16 when a byte order mark (or
+ * BOM-less UTF-16 `<?`, XML 1.0 Appendix F) says so, else UTF-8, never failing.
+ * @param head - the first bytes
+ * @returns the text, a leading byte order mark removed
+ * @category Plugin helpers
+ */
+export function sniffXmlText(head) {
+    let label = "utf-8";
+    if ((head[0] === 0xff && head[1] === 0xfe) || (head[0] === 0x3c && head[1] === 0x00 && head[2] === 0x3f)) {
+        label = "utf-16le";
+    }
+    else if ((head[0] === 0xfe && head[1] === 0xff) || (head[0] === 0x00 && head[1] === 0x3c && head[3] === 0x3f)) {
+        label = "utf-16be";
+    }
+    return new TextDecoder(label, { fatal: false }).decode(head);
+}
 /**
  * Whether a text is an XML Name.
  * @param text - the text
  * @returns true for a well-formed name
+ * @category Plugin helpers
  */
 export function isXmlName(text) {
     if (text.length === 0) {
@@ -230,6 +285,7 @@ function isXmlChar(cp) {
  * @param line - the line, for errors
  * @param repairs - the opt-in repairs (XGMML only); none by default
  * @returns the decoded text
+ * @category Plugin helpers
  */
 export function decodeEntities(raw, line, repairs) {
     let amp = raw.indexOf("&");
@@ -252,13 +308,14 @@ export function decodeEntities(raw, line, repairs) {
             continue;
         }
         if (semi < 0) {
-            throw new XmlSyntaxError("unterminated entity reference", line);
+            throw new XmlSyntaxError("unterminated entity reference", lineAt(raw, amp, line));
         }
         const name = raw.slice(amp + 1, semi);
         if (name.startsWith("#")) {
             const hex = name.startsWith("#x") || name.startsWith("#X");
             const digits = name.slice(hex ? 2 : 1);
-            const ok = hex ? /^[0-9a-fA-F]{1,6}$/.test(digits) : /^[0-9]{1,7}$/.test(digits);
+            // XML 1.0 puts no limit on leading zeros (&#x0000000041; is "A")
+            const ok = hex ? /^0*[\da-fA-F]{1,6}$/.test(digits) : /^0*\d{1,7}$/.test(digits);
             const cp = ok ? Number.parseInt(digits, hex ? 16 : 10) : -1;
             const low = cp >= 0xd800 && cp <= 0xdbff ? lowSurrogateAfter(raw, semi + 1, repairs) : null;
             if (low !== null) {
@@ -269,14 +326,14 @@ export function decodeEntities(raw, line, repairs) {
                 continue;
             }
             if (cp < 0 || !isXmlChar(cp)) {
-                throw new XmlSyntaxError(`invalid character reference &${name};`, line);
+                throw new XmlSyntaxError(`invalid character reference &${name};`, lineAt(raw, amp, line));
             }
             out += String.fromCodePoint(cp);
         }
         else {
             const value = NAMED_ENTITIES[name];
             if (value === undefined) {
-                throw new XmlSyntaxError(`unknown entity &${name};`, line);
+                throw new XmlSyntaxError(`unknown entity &${name};`, lineAt(raw, amp, line));
             }
             out += value;
         }
@@ -322,6 +379,7 @@ function lowSurrogateAfter(raw, at, repairs) {
  * Whether a text is whitespace only.
  * @param text - the text
  * @returns true when every character is XML whitespace (also for an empty text)
+ * @category Plugin helpers
  */
 export function isWhitespace(text) {
     for (let i = 0; i < text.length; i++) {
@@ -335,6 +393,7 @@ export function isWhitespace(text) {
  * The local part of a possibly prefixed XML name.
  * @param name - the name as written
  * @returns the text after the last colon, or the name itself
+ * @category Plugin helpers
  */
 export function localName(name) {
     const colon = name.lastIndexOf(":");
@@ -346,13 +405,39 @@ export function localName(name) {
  * @param chunks - the text (already UTF-8 decoded, BOM removed)
  * @param handler - the event sink
  * @param repairs - the opt-in repairs (XGMML only); none by default
+ * @category Plugin helpers
  */
 export async function tokenizeXml(chunks, handler, repairs) {
     const tokenizer = new XmlTokenizer(handler, repairs);
-    for await (const chunk of chunks) {
-        tokenizer.push(chunk);
+    // XML 1.0 section 2.8: nothing may precede the XML declaration, not even whitespace (template
+    // output often adds a line break, and the declared encoding would then go unread)
+    let skipped = 0;
+    let lines = 1;
+    let leading = true;
+    try {
+        for await (const chunk of chunks) {
+            if (leading) {
+                const start = chunk.search(/\S/);
+                const blank = start < 0 ? chunk : chunk.slice(0, start);
+                skipped += blank.length;
+                lines += blank.split("\n").length - 1;
+                if (start >= 0) {
+                    leading = false;
+                    if (skipped > 0 && /^<\?xml\s/.test(chunk.slice(start, start + 6))) {
+                        throw new XmlSyntaxError("the XML declaration must be at the very start of the document; whitespace precedes it", lines);
+                    }
+                }
+            }
+            tokenizer.push(chunk);
+        }
+        tokenizer.finish();
+    }
+    catch (err) {
+        if (err instanceof XmlSyntaxError && tokenizer.declaresXml11 && !err.message.includes("XML 1.1")) {
+            throw new XmlSyntaxError(`${err.message}; the document declares XML 1.1, which graph-io does not read (it reads XML 1.0)`, err.line);
+        }
+        throw err;
     }
-    tokenizer.finish();
 }
 /** The terminator of each fixed-terminator markup kind. */
 const TERMINATORS = {
@@ -361,9 +446,14 @@ const TERMINATORS = {
     pi: "?>",
     endtag: ">",
 };
+/** The namespace the `xml` prefix is bound to by definition. */
+const XML_NAMESPACE = "http://www.w3.org/XML/1998/namespace";
+/** The markup declarations a truncated `<!...` at the end of the input may have been cut from. */
+const DECLARATION_OPENERS = ["<!--", "<![CDATA[", "<!DOCTYPE"];
 /**
  * The tokenizer state: the unconsumed tail of the input, the current line, the open element
  * stack and the text run being accumulated. `push()` chunks, then `finish()`.
+ * @category Plugin helpers
  */
 export class XmlTokenizer {
     /**
@@ -393,15 +483,47 @@ export class XmlTokenizer {
         this.stack = [];
         this.rootSeen = false;
         this.rootClosed = false;
+        /** Whether any markup was consumed (an input with none is empty, not malformed). */
+        this.markupSeen = false;
+        /** Whether nothing has been consumed yet: the XML declaration may only appear here. */
+        this.atStart = true;
+        /** Whether a DOCTYPE declaration was read (one is allowed, in the prolog). */
+        this.doctypeSeen = false;
+        /** The version of the XML declaration, or null. */
+        this.version = null;
+        /** The last two characters of the character data since the last markup, for the `]]>` check. */
+        this.textTail = "";
+        /** A high surrogate held back from the end of the previous chunk (its low half may start the next). */
+        this.pendingHigh = "";
+        /** The namespace declarations in scope, innermost last. */
+        this.bindings = [];
         this.handler = handler;
         this.repairs = repairs;
     }
+    /**
+     * Whether the document's XML declaration says version 1.1 (read by the XML 1.0 rules all the
+     * same; the syntax error of a 1.1-only construct then says why).
+     * @returns true after a `<?xml version="1.1"?>` declaration
+     */
+    get declaresXml11() {
+        return this.version === "1.1";
+    }
     /**
      * Feed one chunk and emit every complete token in it.
      * @param chunk - the text
      */
     push(chunk) {
         let text = chunk;
+        if (this.pendingHigh.length > 0) {
+            text = this.pendingHigh + text;
+            this.pendingHigh = "";
+        }
+        const last = text.charCodeAt(text.length - 1); // NOSONAR(S7758): reads UTF-16 code units on purpose
+        if (last >= 0xd800 && last <= 0xdbff) {
+            // a text chunk may end between the two halves of an astral character
+            this.pendingHigh = text.slice(-1);
+            text = text.slice(0, -1);
+        }
         if (this.pendingCr) {
             text = `\r${text}`;
             this.pendingCr = false;
@@ -418,12 +540,14 @@ export class XmlTokenizer {
     /** Signal the end of the input: flush the last text run and check well-formedness. */
     finish() {
         this.final = true;
+        const held = this.pendingHigh;
+        this.pendingHigh = "";
         if (this.pendingCr) {
             this.pendingCr = false;
-            this.feed("\n");
+            this.feed(`\n${held}`);
         }
         else {
-            this.feed("");
+            this.feed(held);
         }
         if (this.pending !== null || this.buffer.length > 0) {
             throw new XmlSyntaxError("unexpected end of input inside markup", this.line);
@@ -433,13 +557,16 @@ export class XmlTokenizer {
             throw new XmlSyntaxError(`unclosed element <${this.stack[this.stack.length - 1]}>`, this.line);
         }
         if (!this.rootSeen) {
+            if (!this.markupSeen) {
+                throw new XmlEmptyInputError(this.line);
+            }
             throw new XmlSyntaxError("no root element", this.line);
         }
     }
     /**
-     * Append normalised text: continue a pending token's terminator scan over the new text alone,
+     * Append normalized text: continue a pending token's terminator scan over the new text alone,
      * and once the token is complete (or when none is pending) scan the buffer for tokens.
-     * @param text - the text, line breaks normalised
+     * @param text - the text, line breaks normalized
      */
     feed(text) {
         const { pending } = this;
@@ -546,9 +673,20 @@ export class XmlTokenizer {
      * @returns the index one past the `>`, or -1
      */
     scanDoctype(pending, text, from) {
-        let { quote, depth, comment, run } = pending;
+        let { quote, depth, comment, pi, run } = pending;
         for (let i = from; i < text.length; i++) {
             const c = text.charCodeAt(i);
+            if (pi) {
+                // a processing instruction in the subset ends at `?>`; quotes inside it are text
+                if (c === GT && run === 1) {
+                    pi = false;
+                    run = 0;
+                }
+                else {
+                    run = c === QUESTION ? 1 : 0;
+                }
+                continue;
+            }
             if (comment) {
                 if (c === DASH) {
                     run++;
@@ -582,6 +720,11 @@ export class XmlTokenizer {
                     run = 0;
                     continue;
                 }
+                if (run === 1 && c === QUESTION) {
+                    pi = true;
+                    run = 0;
+                    continue;
+                }
                 run = 0;
                 if (c === LT) {
                     run = 1;
@@ -601,6 +744,7 @@ export class XmlTokenizer {
                 pending.quote = 0;
                 pending.depth = 0;
                 pending.comment = false;
+                pending.pi = false;
                 pending.run = 0;
                 return i + 1;
             }
@@ -608,6 +752,7 @@ export class XmlTokenizer {
         pending.quote = quote;
         pending.depth = depth;
         pending.comment = comment;
+        pending.pi = pi;
         pending.run = run;
         return -1;
     }
@@ -628,7 +773,11 @@ export class XmlTokenizer {
                 if (!this.final) {
                     // an entity reference may be split across chunks: hold back from its "&"
                     const amp = buffer.lastIndexOf("&");
-                    if (amp >= pos && amp >= length - MAX_ENTITY_LENGTH && buffer.indexOf(";", amp) < 0) {
+                    if (amp >= pos &&
+                        !buffer.includes(";", amp) &&
+                        // ponytail: a zero-padded reference longer than MAX_ENTITY_LENGTH is held back
+                        // whole, so an absurdly long run of zeros is re-scanned once per chunk
+                        (amp >= length - MAX_ENTITY_LENGTH || /^&#[xX]?0[\da-fA-F]*$/.test(buffer.slice(amp)))) {
                         end = amp;
                     }
                     if (this.repairs?.surrogatePair !== undefined) {
@@ -675,6 +824,7 @@ export class XmlTokenizer {
             quote: 0,
             depth: 0,
             comment: false,
+            pi: false,
             run: 0,
         };
         if (piece.length < MIN_DECIDABLE_MARKUP) {
@@ -723,60 +873,31 @@ export class XmlTokenizer {
      * @returns the index after the markup, or -1 when the buffer ends before the markup does
      */
     consumeMarkup(pos) {
+        const end = this.markupEnd(pos);
+        if (end >= 0) {
+            this.markupSeen = true;
+            this.atStart = false;
+            // markup ends a run of character data: a `]]>` cannot straddle it
+            this.textTail = "";
+        }
+        return end;
+    }
+    /**
+     * Read the markup starting at `pos` (a `<`) and deliver what it means.
+     * @param pos - the index of the `<`
+     * @returns the index after the markup, or -1 when the buffer ends before the markup does
+     */
+    markupEnd(pos) {
         const { buffer } = this;
         if (buffer.startsWith("<!", pos)) {
-            if (buffer.length - pos < MIN_DECIDABLE_MARKUP && !this.final) {
-                // "<![CDATA[" is 9 characters; wait until the kind of declaration is decidable
-                return -1;
-            }
-            if (buffer.startsWith("<!--", pos)) {
-                const end = buffer.indexOf("-->", pos + 4);
-                if (end < 0) {
-                    return -1;
-                }
-                this.advanceLine(pos, end + 3);
-                return end + 3;
-            }
-            if (buffer.startsWith("<![CDATA[", pos)) {
-                const end = buffer.indexOf("]]>", pos + 9);
-                if (end < 0) {
-                    return -1;
-                }
-                if (this.text.length === 0) {
-                    this.textLine = this.line;
-                }
-                const cdata = buffer.slice(pos + 9, end);
-                if (hasIllegalXmlChar(cdata)) {
-                    throw new XmlSyntaxError("a character XML 1.0 forbids appears in a CDATA section", this.line);
-                }
-                this.text += cdata;
-                this.advanceLine(pos, end + 3);
-                return end + 3;
-            }
-            if (!buffer.startsWith("<!DOCTYPE", pos)) {
-                throw new XmlSyntaxError("unexpected markup declaration", this.line);
-            }
-            const state = {
-                kind: "doctype",
-                pieces: [],
-                tail: "",
-                quote: 0,
-                depth: 0,
-                comment: false,
-                run: 0,
-            };
-            const end = this.scanDoctype(state, buffer, pos + 9);
-            if (end < 0) {
-                return -1;
-            }
-            this.advanceLine(pos, end);
-            return end;
+            return this.declarationEnd(pos);
         }
         if (buffer.startsWith("<?", pos)) {
             const end = buffer.indexOf("?>", pos + 2);
             if (end < 0) {
                 return -1;
             }
+            this.processingInstruction(pos, end);
             this.advanceLine(pos, end + 2);
             return end + 2;
         }
@@ -785,7 +906,8 @@ export class XmlTokenizer {
             if (end < 0) {
                 return -1;
             }
-            const name = buffer.slice(pos + 2, end).trim();
+            // whitespace may follow the name, never precede it
+            const name = buffer.slice(pos + 2, end).trimEnd();
             if (!isXmlName(name)) {
                 throw new XmlSyntaxError(`malformed end tag </${name}>`, this.line);
             }
@@ -799,13 +921,149 @@ export class XmlTokenizer {
             return -1;
         }
         this.flushText();
-        this.startElement(tag.name, tag.attrs);
+        this.startElement(tag.name, tag.attrs, tag.declaresNamespace);
         if (tag.selfClosing) {
             this.endElement(tag.name);
         }
         this.advanceLine(pos, tag.end);
         return tag.end;
     }
+    /**
+     * Read the CDATA section at `pos` into the text.
+     * @param pos - the index of the `<`
+     * @returns the index after the section, or -1 when the buffer ends before the section does
+     */
+    cdataEnd(pos) {
+        const end = this.buffer.indexOf("]]>", pos + 9);
+        if (end < 0) {
+            return -1;
+        }
+        if (this.text.length === 0) {
+            this.textLine = this.line;
+        }
+        const cdata = this.buffer.slice(pos + 9, end);
+        const bad = illegalCharIndex(cdata);
+        if (bad >= 0) {
+            throw new XmlSyntaxError("a character XML 1.0 forbids appears in a CDATA section", this.lineIn(pos, pos + 9 + bad));
+        }
+        this.text += cdata;
+        this.advanceLine(pos, end + 3);
+        return end + 3;
+    }
+    /**
+     * Read the `<!...>` markup at `pos`: a comment, a CDATA section or the DOCTYPE.
+     * @param pos - the index of the `<`
+     * @returns the index after the markup, or -1 when the buffer ends before the markup does
+     */
+    declarationEnd(pos) {
+        const { buffer } = this;
+        if (buffer.length - pos < MIN_DECIDABLE_MARKUP) {
+            // "<![CDATA[" is 9 characters; wait until the kind of declaration is decidable, and at
+            // the end of the input read the start of one cut short as a truncation
+            const head = buffer.slice(pos);
+            if (!this.final || DECLARATION_OPENERS.some((opener) => opener.startsWith(head))) {
+                return -1;
+            }
+        }
+        if (buffer.startsWith("<!--", pos)) {
+            const end = buffer.indexOf("-->", pos + 4);
+            if (end < 0) {
+                return -1;
+            }
+            // a "--" inside, which XML 1.0 forbids, is accepted: the comment carries no data
+            this.advanceLine(pos, end + 3);
+            return end + 3;
+        }
+        if (buffer.startsWith("<![CDATA[", pos)) {
+            return this.cdataEnd(pos);
+        }
+        if (!buffer.startsWith("<!DOCTYPE", pos)) {
+            if (buffer.slice(pos + 2, pos + 9).toUpperCase() === "DOCTYPE") {
+                throw new XmlSyntaxError(`<!${buffer.slice(pos + 2, pos + 9)}> is not XML (it must be written <!DOCTYPE>); the input looks like an HTML document`, this.line);
+            }
+            throw new XmlSyntaxError("unexpected markup declaration", this.line);
+        }
+        if (this.rootSeen || this.doctypeSeen) {
+            throw new XmlSyntaxError("a DOCTYPE declaration is allowed once, before the root element", this.line);
+        }
+        const state = {
+            kind: "doctype",
+            pieces: [],
+            tail: "",
+            quote: 0,
+            depth: 0,
+            comment: false,
+            pi: false,
+            run: 0,
+        };
+        const end = this.scanDoctype(state, buffer, pos + 9);
+        if (end < 0) {
+            return -1;
+        }
+        this.doctypeSeen = true;
+        this.handler.doctype?.(buffer.slice(pos, end), this.line);
+        this.advanceLine(pos, end);
+        return end;
+    }
+    /**
+     * Check a processing instruction `<?target ...?>` (skipped otherwise): its target must be a
+     * name, and the reserved target `xml` is the XML declaration, allowed only at the very start
+     * of the document with a 1.x version.
+     * @param pos - the index of the `<`
+     * @param end - the index of the `?>`
+     */
+    processingInstruction(pos, end) {
+        const body = this.buffer.slice(pos + 2, end);
+        const target = /^[^\s]*/.exec(body)?.[0] ?? "";
+        if (!isXmlName(target)) {
+            throw new XmlSyntaxError(`a processing instruction needs a target name, not "${target}"`, this.line);
+        }
+        if (target.toLowerCase() !== "xml") {
+            return;
+        }
+        if (target !== "xml") {
+            throw new XmlSyntaxError(`<?${target} is not an XML declaration (which is written <?xml in lower case); the target is reserved`, this.line);
+        }
+        if (!this.atStart || pos !== 0) {
+            throw new XmlSyntaxError("an XML declaration (<?xml ...?>) may appear only at the very start of the document; the target xml is reserved", this.line);
+        }
+        const version = /\bversion\s*=\s*(["'])([^"']*)\1/.exec(body)?.[2];
+        if (version === undefined) {
+            throw new XmlSyntaxError("the XML declaration has no version", this.line);
+        }
+        if (!/^1\.\d+$/.test(version)) {
+            throw new XmlSyntaxError(`XML version ${version} is not supported (only 1.x)`, this.line);
+        }
+        this.version = version;
+    }
+    /**
+     * The line of a buffer position after `start`, the position the current line count refers to.
+     * Used on the error path only.
+     * @param start - a position on line `this.line`
+     * @param at - the position
+     * @returns its line
+     */
+    lineIn(start, at) {
+        return lineAt(this.buffer.slice(start, at), at - start, this.line);
+    }
+    /**
+     * Decode the entities of a text, naming XML 1.1 when a character reference XML 1.0 forbids
+     * appears in a document that declares version 1.1.
+     * @param raw - the text as written
+     * @param line - the line the text starts on
+     * @returns the decoded text
+     */
+    decode(raw, line) {
+        try {
+            return decodeEntities(raw, line, this.repairs);
+        }
+        catch (err) {
+            if (err instanceof XmlSyntaxError && this.version !== null && this.version !== "1.0") {
+                throw new XmlSyntaxError(`${err.message} (the document declares XML ${this.version}, whose character rules are not supported; it is read as XML 1.0)`, err.line);
+            }
+            throw err;
+        }
+    }
     /**
      * Parse a start tag at `pos`.
      * @param pos - the index of the `<`
@@ -825,7 +1083,9 @@ export class XmlTokenizer {
         const name = buffer.slice(i, nameEnd);
         i = nameEnd;
         const attrs = new Map();
+        let declaresNamespace = false;
         for (;;) {
+            const before = i;
             while (i < length && isSpace(buffer.charCodeAt(i))) {
                 i++;
             }
@@ -834,23 +1094,27 @@ export class XmlTokenizer {
             }
             const c = buffer.charCodeAt(i);
             if (c === GT) {
-                return { name, attrs, selfClosing: false, end: i + 1 };
+                return { name, attrs, selfClosing: false, declaresNamespace, end: i + 1 };
             }
             if (c === SLASH) {
                 if (i + 1 >= length) {
                     return null;
                 }
                 if (buffer.charCodeAt(i + 1) !== GT) {
-                    throw new XmlSyntaxError(`unexpected "/" in <${name}>`, this.line);
+                    throw new XmlSyntaxError(`unexpected "/" in <${name}>`, this.lineIn(pos, i));
                 }
-                return { name, attrs, selfClosing: true, end: i + 2 };
+                return { name, attrs, selfClosing: true, declaresNamespace, end: i + 2 };
+            }
+            if (i === before) {
+                // the name, or the previous value's closing quote, runs into the next attribute
+                throw new XmlSyntaxError(`the attributes of <${name}> must be separated by whitespace`, this.lineIn(pos, i));
             }
             const attrEnd = this.readName(i);
             if (attrEnd < 0) {
                 return null;
             }
             if (attrEnd === i) {
-                throw new XmlSyntaxError(`malformed attribute in <${name}>`, this.line);
+                throw new XmlSyntaxError(`malformed attribute in <${name}>`, this.lineIn(pos, i));
             }
             const attrName = buffer.slice(i, attrEnd);
             i = attrEnd;
@@ -861,7 +1125,7 @@ export class XmlTokenizer {
                 return null;
             }
             if (buffer.charCodeAt(i) !== EQUALS) {
-                throw new XmlSyntaxError(`attribute ${attrName} of <${name}> has no value`, this.line);
+                throw new XmlSyntaxError(`attribute ${attrName} of <${name}> has no value`, this.lineIn(pos, i));
             }
             i++;
             while (i < length && isSpace(buffer.charCodeAt(i))) {
@@ -872,20 +1136,27 @@ export class XmlTokenizer {
             }
             const quote = buffer.charCodeAt(i);
             if (quote !== QUOTE && quote !== APOS) {
-                throw new XmlSyntaxError(`attribute ${attrName} of <${name}> is not quoted`, this.line);
+                throw new XmlSyntaxError(`attribute ${attrName} of <${name}> is not quoted`, this.lineIn(pos, i));
             }
             const close = buffer.indexOf(quote === QUOTE ? '"' : "'", i + 1);
             if (close < 0) {
                 return null;
             }
+            const line = this.lineIn(pos, i);
             if (attrs.has(attrName)) {
-                throw new XmlSyntaxError(`duplicate attribute ${attrName} in <${name}>`, this.line);
+                throw new XmlSyntaxError(`duplicate attribute ${attrName} in <${name}>`, line);
             }
             const raw = buffer.slice(i + 1, close);
             if (hasIllegalXmlChar(raw)) {
-                throw new XmlSyntaxError(`a character XML 1.0 forbids appears in attribute ${attrName} of <${name}>`, this.line);
+                throw new XmlSyntaxError(`a character XML 1.0 forbids appears in attribute ${attrName} of <${name}>`, line);
             }
-            attrs.set(attrName, decodeEntities(normalizeAttributeValue(raw), this.line, this.repairs));
+            if (raw.includes("<")) {
+                throw new XmlSyntaxError(`a "<" in the value of attribute ${attrName} of <${name}> (write &lt;)`, line);
+            }
+            if (attrName.startsWith("xmlns")) {
+                declaresNamespace = true;
+            }
+            attrs.set(attrName, this.decode(normalizeAttributeValue(raw), line));
             i = close + 1;
         }
     }
@@ -946,10 +1217,20 @@ export class XmlTokenizer {
             this.textLine = this.line;
         }
         const raw = this.buffer.slice(start, end);
-        if (hasIllegalXmlChar(raw)) {
-            throw new XmlSyntaxError("a character XML 1.0 forbids appears in character data", this.line);
+        const bad = illegalCharIndex(raw);
+        if (bad >= 0) {
+            throw new XmlSyntaxError("a character XML 1.0 forbids appears in character data", lineAt(raw, bad, this.line));
         }
-        this.text += decodeEntities(raw, this.line, this.repairs);
+        if (raw.includes(">")) {
+            const probe = this.textTail + raw;
+            const close = probe.indexOf("]]>");
+            if (close >= 0) {
+                throw new XmlSyntaxError('"]]>" is not allowed in character data (write ]]&gt;)', lineAt(raw, Math.max(0, close - this.textTail.length), this.line));
+            }
+        }
+        this.textTail = raw.length >= 2 ? raw.slice(-2) : (this.textTail + raw).slice(-2);
+        this.atStart = false;
+        this.text += this.decode(raw, this.line);
         this.advanceLine(start, end);
     }
     /**
@@ -992,16 +1273,49 @@ export class XmlTokenizer {
      * Open an element.
      * @param name - the element name
      * @param attrs - its attributes
+     * @param declaresNamespace - whether an attribute name starts with `xmlns`
      */
-    startElement(name, attrs) {
+    startElement(name, attrs, declaresNamespace) {
         if (this.stack.length === 0) {
             if (this.rootClosed) {
                 throw new XmlSyntaxError(`a second root element <${name}> follows the document element`, this.line);
             }
             this.rootSeen = true;
         }
+        if (declaresNamespace) {
+            for (const [key, uri] of attrs) {
+                if (key === "xmlns") {
+                    this.bindings.push({ prefix: "", uri, depth: this.stack.length });
+                }
+                else if (key.startsWith("xmlns:")) {
+                    this.bindings.push({ prefix: key.slice(6), uri, depth: this.stack.length });
+                }
+            }
+        }
         this.stack.push(name);
-        this.handler.start(name, attrs, this.line);
+        this.handler.start(name, attrs, this.line, this.namespaceOf(name));
+    }
+    /**
+     * The namespace an element name is in (Namespaces in XML 1.0 section 6).
+     * @param name - the element name as written
+     * @returns the URI; "" for no namespace; null for an undeclared prefix or a name that is not
+     * namespace-well-formed
+     */
+    namespaceOf(name) {
+        const colon = name.indexOf(":");
+        if (colon >= 0 && (colon === 0 || colon === name.length - 1 || name.includes(":", colon + 1))) {
+            return null;
+        }
+        const prefix = colon < 0 ? "" : name.slice(0, colon);
+        for (let i = this.bindings.length - 1; i >= 0; i--) {
+            if (this.bindings[i].prefix === prefix) {
+                return this.bindings[i].uri;
+            }
+        }
+        if (prefix === "xml") {
+            return XML_NAMESPACE;
+        }
+        return prefix === "" ? "" : null;
     }
     /**
      * Close an element, checking that it matches the innermost open one.
@@ -1016,6 +1330,9 @@ export class XmlTokenizer {
             throw new XmlSyntaxError(`end tag </${name}> does not match <${open}>`, this.line);
         }
         this.stack.pop();
+        while ((this.bindings.at(-1)?.depth ?? -1) >= this.stack.length) {
+            this.bindings.pop();
+        }
         if (this.stack.length === 0) {
             this.rootClosed = true;
         }
@@ -1023,10 +1340,10 @@ export class XmlTokenizer {
     }
 }
 /**
- * Attribute value normalisation (XML 1.0 section 3.3.3): a literal tab or line break becomes a
+ * Attribute value normalization (XML 1.0 section 3.3.3): a literal tab or line break becomes a
  * space; a character reference to one is kept, which is why this runs before entity decoding.
  * @param raw - the value between the quotes
- * @returns the normalised value
+ * @returns the normalized value
  */
 function normalizeAttributeValue(raw) {
     return raw.includes("\n") || raw.includes("\t") ? raw.replace(/[\n\t]/g, " ") : raw;