svg-eslint-parser 0.1.0 → 0.3.0

package/dist/index.js

@@ -1,10 +1,14 @@
-import { t as __exportAll } from "./chunk-pbuEa-1d.js";
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
+import { isNumber } from "@ntnyq/utils";
 import { unionWith } from "eslint-visitor-keys";
 //#endregion
 //#region src/meta.ts
+/**
+* Package metadata exposed to parser consumers.
+*/
 const meta = {
 	name: "svg-eslint-parser",
-	version: "0.1.0"
+	version: "0.3.0"
 };
 //#endregion
 //#region src/parser/error.ts
@@ -15,12 +19,12 @@ var ParseError = class extends SyntaxError {
 	index;
 	lineNumber;
 	column;
-	constructor(message, offset, line, column) {
-		super(message);
+	constructor(message, options, line, column) {
+		super(message, options);
 		this.name = "ParseError";
-		this.index = offset;
-		this.lineNumber = line;
-		this.column = column;
+		this.index = isNumber(options) ? options : options.offset;
+		this.lineNumber = isNumber(options) ? line ?? 0 : options.line;
+		this.column = isNumber(options) ? column ?? 0 : options.column;
 	}
 };
 //#endregion
@@ -43,26 +47,29 @@ const XML_DECLARATION_START = "<?xml";
 const XML_DECLARATION_END = "?>";
 /**
 * regexp for open tag start
-* @regex101 https://regex101.com/?regex=%5E%3C%5Cw&flavor=javascript
+* @regex101 https://regex101.com/?regex=%5E%3C%5Cw&flags=u&flavor=javascript
 */
 const RE_OPEN_TAG_START = /^<\w/u;
 /**
 * regexp for open tag name
-* @regex101 https://regex101.com/?regex=%5E%3C%28%5CS%2B%29&flavor=javascript
+* @regex101 https://regex101.com/?regex=%5E%3C%28%3F%3CtagName%3E%5CS%2B%29&flags=u&flavor=javascript
 */
-const RE_OPEN_TAG_NAME = /^<(\S+)/u;
+const RE_OPEN_TAG_NAME = /^<(?<tagName>\S+)/u;
 /**
 * regexp for close tag name
-* @regex101 https://regex101.com/?regex=%5E%3C%5C%2F%28%28%3F%3A.%7C%5Cr%3F%5Cn%29*%29%3E%24&flavor=javascript
+* @regex101 https://regex101.com/?regex=%5E%3C%5C%2F%28%3F%3CtagName%3E%28%3F%3A.%7C%5Cr%3F%5Cn%29*%29%3E%24&flags=u&flavor=javascript
 */
-const RE_CLOSE_TAG_NAME = /^<\/((?:.|\r?\n)*)>$/u;
+const RE_CLOSE_TAG_NAME = /^<\/(?<tagName>(?:.|\r?\n)*)>$/u;
 /**
 * regexp for incomplete closing tag
-* @regex101 https://regex101.com/?regex=%3C%5C%2F%5B%5E%3E%5D%2B%24&flavor=javascript
+* @regex101 https://regex101.com/?regex=%3C%5C%2F%5B%5E%3E%5D%2B%24&flags=u&flavor=javascript
 */
 const RE_INCOMPLETE_CLOSING_TAG = /<\/[^>]+$/u;
 //#endregion
 //#region src/constants/nodeTypes.ts
+/**
+* AST node type names emitted by the parser.
+*/
 let NodeTypes = /* @__PURE__ */ function(NodeTypes) {
 	NodeTypes["Attribute"] = "Attribute";
 	NodeTypes["AttributeKey"] = "AttributeKey";
@@ -75,8 +82,6 @@ let NodeTypes = /* @__PURE__ */ function(NodeTypes) {
 	NodeTypes["Element"] = "Element";
 	NodeTypes["Error"] = "Error";
 	NodeTypes["Program"] = "Program";
-	/** @deprecated Use Element instead. */
-	NodeTypes["Tag"] = "Element";
 	NodeTypes["Text"] = "Text";
 	NodeTypes["XMLDeclaration"] = "XMLDeclaration";
 	NodeTypes["XMLDeclarationAttribute"] = "XMLDeclarationAttribute";
@@ -86,6 +91,9 @@ let NodeTypes = /* @__PURE__ */ function(NodeTypes) {
 }({});
 //#endregion
 //#region src/constants/tokenTypes.ts
+/**
+* Token type names emitted by tokenizer contexts.
+*/
 let TokenTypes = /* @__PURE__ */ function(TokenTypes) {
 	/**
 	* @pg Content tokens
@@ -133,6 +141,9 @@ let TokenTypes = /* @__PURE__ */ function(TokenTypes) {
 }({});
 //#endregion
 //#region src/constants/specialChar.ts
+/**
+* Character constants used by tokenizer handlers.
+*/
 const SPECIAL_CHAR = {
 	closingCorner: `>`,
 	colon: `:`,
@@ -156,7 +167,7 @@ const SPECIAL_CHAR = {
 * @copyright {@link https://github.com/davidohlin/svg-elements}
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element}
 */
-const SVG_ELEMENTS = new Set([
+const SVG_ELEMENTS = /* @__PURE__ */ new Set([
 	"a",
 	"animate",
 	"animateMotion",
@@ -227,7 +238,7 @@ const SVG_ELEMENTS = new Set([
 *
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element#obsolete_and_deprecated_elements}
 */
-const DEPRECATED_SVG_ELEMENTS = new Set([
+const DEPRECATED_SVG_ELEMENTS = /* @__PURE__ */ new Set([
 	"altGlyph",
 	"altGlyphDef",
 	"altGlyphItem",
@@ -249,7 +260,7 @@ const DEPRECATED_SVG_ELEMENTS = new Set([
 /**
 * self closing svg elements
 */
-const SELF_CLOSING_ELEMENTS = new Set([
+const SELF_CLOSING_ELEMENTS = /* @__PURE__ */ new Set([
 	"animate",
 	"animateMotion",
 	"animateTransform",
@@ -285,6 +296,9 @@ const SELF_CLOSING_ELEMENTS = new Set([
 ]);
 //#endregion
 //#region src/constants/tokenizerContextTypes.ts
+/**
+* Tokenizer state machine contexts.
+*/
 let TokenizerContextTypes = /* @__PURE__ */ function(TokenizerContextTypes) {
 	TokenizerContextTypes["AttributeKey"] = "AttributeKey";
 	TokenizerContextTypes["Attributes"] = "Attributes";
@@ -313,6 +327,9 @@ let TokenizerContextTypes = /* @__PURE__ */ function(TokenizerContextTypes) {
 }({});
 //#endregion
 //#region src/constants/constructTreeContextTypes.ts
+/**
+* AST construction state machine contexts.
+*/
 let ConstructTreeContextTypes = /* @__PURE__ */ function(ConstructTreeContextTypes) {
 	ConstructTreeContextTypes["Attribute"] = "Attribute";
 	ConstructTreeContextTypes["Attributes"] = "Attributes";
@@ -331,6 +348,78 @@ let ConstructTreeContextTypes = /* @__PURE__ */ function(ConstructTreeContextTyp
 	return ConstructTreeContextTypes;
 }({});
 //#endregion
+//#region src/parser/errorHandler.ts
+/**
+* Collects recoverable parse errors and warnings during parsing.
+*/
+var ErrorHandler = class {
+	errors = [];
+	warnings = [];
+	addError(error) {
+		this.errors.push(error);
+	}
+	addWarning(warning) {
+		this.warnings.push(warning);
+	}
+	hasErrors() {
+		return this.errors.length > 0;
+	}
+	hasWarnings() {
+		return this.warnings.length > 0;
+	}
+	clear() {
+		this.errors = [];
+		this.warnings = [];
+	}
+	getErrors() {
+		return [...this.errors];
+	}
+	getWarnings() {
+		return [...this.warnings];
+	}
+	/**
+	* Merge errors from another ErrorHandler
+	*/
+	mergeErrors(other) {
+		this.errors.push(...other.errors);
+		this.warnings.push(...other.warnings);
+	}
+	/**
+	* Get all issues (errors + warnings) sorted by position
+	*/
+	getAllIssues() {
+		return [...this.errors, ...this.warnings].sort((a, b) => a.range[0] - b.range[0]);
+	}
+	/**
+	* Format errors for display
+	*/
+	format() {
+		const issues = this.getAllIssues();
+		if (issues.length === 0) return "No errors or warnings";
+		return issues.map((issue) => {
+			const { loc, message, type } = issue;
+			return `${loc.start.line}:${loc.start.column} [${type}] ${message}`;
+		}).join("\n");
+	}
+};
+//#endregion
+//#region src/types/errors.ts
+/**
+* Categories of recoverable parse diagnostics.
+*/
+let ParseErrorType = /* @__PURE__ */ function(ParseErrorType) {
+	ParseErrorType["InvalidAttribute"] = "InvalidAttribute";
+	ParseErrorType["InvalidCharacter"] = "InvalidCharacter";
+	ParseErrorType["InvalidDoctypeAttribute"] = "InvalidDoctypeAttribute";
+	ParseErrorType["InvalidXMLDeclaration"] = "InvalidXMLDeclaration";
+	ParseErrorType["MalformedComment"] = "MalformedComment";
+	ParseErrorType["MismatchedTag"] = "MismatchedTag";
+	ParseErrorType["UnclosedTag"] = "UnclosedTag";
+	ParseErrorType["UnexpectedToken"] = "UnexpectedToken";
+	ParseErrorType["UnmatchedQuote"] = "UnmatchedQuote";
+	return ParseErrorType;
+}({});
+//#endregion
 //#region src/utils/cloneNode.ts
 /**
 * Deep clone a node, removing parent references
@@ -438,8 +527,14 @@ function clearParent(ast) {
 * @param code - Character code to check
 * @returns True if code is a newline character (LF, CR, LS, PS)
 */
+const LINE_BREAK_CODES = /* @__PURE__ */ new Set([
+	10,
+	13,
+	8232,
+	8233
+]);
 function isNewLine(code) {
-	return code === 10 || code === 13 || code === 8232 || code === 8233;
+	return LINE_BREAK_CODES.has(code);
 }
 /**
 * Find the next line break position in a string
@@ -474,6 +569,62 @@ function getLineInfo(input, offset) {
 	}
 }
 //#endregion
+//#region src/visitorKeys.ts
+const keys = {
+	Program: ["document"],
+	Document: ["children"],
+	XMLDeclaration: ["attributes"],
+	XMLDeclarationAttribute: ["key", "value"],
+	XMLDeclarationAttributeKey: [],
+	XMLDeclarationAttributeValue: [],
+	Doctype: ["attributes"],
+	DoctypeAttribute: ["value"],
+	DoctypeAttributeValue: [],
+	Attribute: ["key", "value"],
+	AttributeKey: [],
+	AttributeValue: [],
+	Element: ["attributes", "children"],
+	Comment: [],
+	Text: [],
+	Error: []
+};
+let vistorKeysCache = null;
+/**
+* Get ESLint visitor keys extended with parser-specific AST nodes.
+* @returns Cached visitor key map
+*/
+function getVisitorKeys() {
+	if (!vistorKeysCache) {
+		const merged = unionWith(keys);
+		vistorKeysCache = {
+			...merged,
+			Tag: merged.Element
+		};
+	}
+	return vistorKeysCache;
+}
+/**
+* Shared visitor key map used by parser traversal and ESLint integration.
+*/
+const visitorKeys = getVisitorKeys();
+//#endregion
+//#region src/utils/getChildNodes.ts
+/**
+* Get child AST nodes according to the parser visitor keys.
+* @param node - Parent AST node
+* @returns Child nodes in visitor-key order
+*/
+function getChildNodes(node) {
+	const keys = visitorKeys[node.type] ?? [];
+	const children = [];
+	for (const key of keys) {
+		const value = node[key];
+		if (Array.isArray(value)) children.push(...value);
+		else if (value) children.push(value);
+	}
+	return children;
+}
+//#endregion
 //#region src/utils/nodeHelpers.ts
 /**
 * Filter nodes by a predicate function
@@ -485,8 +636,7 @@ function filterNodes(node, predicate) {
 	const results = [];
 	function traverse(currentNode) {
 		if (predicate(currentNode)) results.push(currentNode);
-		if ("children" in currentNode && Array.isArray(currentNode.children)) for (const child of currentNode.children) traverse(child);
-		if ("attributes" in currentNode && Array.isArray(currentNode.attributes)) for (const attr of currentNode.attributes) traverse(attr);
+		for (const child of getChildNodes(currentNode)) traverse(child);
 	}
 	traverse(node);
 	return results;
@@ -499,8 +649,11 @@ function filterNodes(node, predicate) {
 */
 function mapNodes(node, mapper) {
 	const mapped = mapper(node);
-	if ("children" in mapped && Array.isArray(mapped.children)) mapped.children = mapped.children.map((child) => mapNodes(child, mapper));
-	if ("attributes" in mapped && Array.isArray(mapped.attributes)) mapped.attributes = mapped.attributes.map((attr) => mapNodes(attr, mapper));
+	for (const key of Object.keys(mapped)) {
+		const value = mapped[key];
+		if (Array.isArray(value)) mapped[key] = value.map((item) => item && typeof item === "object" && "type" in item ? mapNodes(item, mapper) : item);
+		else if (value && typeof value === "object" && "type" in value) mapped[key] = mapNodes(value, mapper);
+	}
 	return mapped;
 }
 /**
@@ -538,8 +691,7 @@ function getNodeDepth(node) {
 */
 function countNodes(node) {
 	let count = 1;
-	if ("children" in node && Array.isArray(node.children)) for (const child of node.children) count += countNodes(child);
-	if ("attributes" in node && Array.isArray(node.attributes)) for (const attr of node.attributes) count += countNodes(attr);
+	for (const child of getChildNodes(node)) count += countNodes(child);
 	return count;
 }
 //#endregion
@@ -555,10 +707,7 @@ function traverseAST(node, visitor, parent = null) {
 	if (visitor.enter) {
 		if (visitor.enter(node, parent) === false) shouldTraverseChildren = false;
 	}
-	if (shouldTraverseChildren) {
-		if ("children" in node && Array.isArray(node.children)) for (const child of node.children) traverseAST(child, visitor, node);
-		if ("attributes" in node && Array.isArray(node.attributes)) for (const attr of node.attributes) traverseAST(attr, visitor, node);
-	}
+	if (shouldTraverseChildren) for (const child of getChildNodes(node)) traverseAST(child, visitor, node);
 	if (visitor.leave) visitor.leave(node, parent);
 }
 /**
@@ -571,13 +720,19 @@ function walkAST(node, callback) {
 }
 //#endregion
 //#region src/utils/isWhitespace.ts
+const WHITESPACE_CHARS = /* @__PURE__ */ new Set([
+	SPECIAL_CHAR.space,
+	SPECIAL_CHAR.newline,
+	SPECIAL_CHAR.return,
+	SPECIAL_CHAR.tab
+]);
 /**
 * Check if a character is whitespace (space, newline, return, or tab)
 * @param char - Character to check
 * @returns True if character is whitespace
 */
 function isWhitespace(char) {
-	return char === SPECIAL_CHAR.space || char === SPECIAL_CHAR.newline || char === SPECIAL_CHAR.return || char === SPECIAL_CHAR.tab;
+	return WHITESPACE_CHARS.has(char);
 }
 //#endregion
 //#region src/utils/validateNode.ts
@@ -616,7 +771,6 @@ function validateNode(node) {
 	if (!Array.isArray(node.range) || node.range.length !== 2 || typeof node.range[0] !== "number" || typeof node.range[1] !== "number") return false;
 	if (!node.loc || !node.loc.start || !node.loc.end || typeof node.loc.start.line !== "number" || typeof node.loc.start.column !== "number" || typeof node.loc.end.line !== "number" || typeof node.loc.end.column !== "number") return false;
 	switch (node.type) {
-		case "Element":
 		case "Element": return validateElementNode(node);
 		case "Attribute": return validateAttributeNode(node);
 		case "Text": return validateTextNode(node);
@@ -694,8 +848,7 @@ function findNodeByType(node, type) {
 	const results = [];
 	function traverse(currentNode) {
 		if (currentNode.type === type) results.push(currentNode);
-		if ("children" in currentNode && Array.isArray(currentNode.children)) for (const child of currentNode.children) traverse(child);
-		if ("attributes" in currentNode && Array.isArray(currentNode.attributes)) for (const attr of currentNode.attributes) traverse(attr);
+		for (const child of getChildNodes(currentNode)) traverse(child);
 	}
 	traverse(node);
 	return results;
@@ -709,14 +862,10 @@ function findNodeByType(node, type) {
 function findFirstNodeByType(node, type) {
 	function traverse(currentNode) {
 		if (currentNode.type === type) return currentNode;
-		if ("children" in currentNode && Array.isArray(currentNode.children)) for (const child of currentNode.children) {
+		for (const child of getChildNodes(currentNode)) {
 			const result = traverse(child);
 			if (result) return result;
 		}
-		if ("attributes" in currentNode && Array.isArray(currentNode.attributes)) for (const attr of currentNode.attributes) {
-			const result = traverse(attr);
-			if (result) return result;
-		}
 	}
 	return traverse(node);
 }
@@ -737,7 +886,9 @@ function getLastAttribute(state) {
 function parseOpenTagName(openTagStartTokenContent) {
 	const match = openTagStartTokenContent.match(RE_OPEN_TAG_NAME);
 	if (match === null) throw new Error(`Unable to parse open tag name.\n${openTagStartTokenContent} does not match pattern of opening tag.`);
-	return match[1].toLowerCase();
+	const tagName = match.groups?.tagName;
+	if (tagName === void 0) throw new Error(`Unable to parse open tag name. Named capture group "tagName" is missing.`);
+	return tagName.toLowerCase();
 }
 //#endregion
 //#region src/utils/parseCloseTagName.ts
@@ -750,7 +901,9 @@ function parseOpenTagName(openTagStartTokenContent) {
 function parseCloseTagName(closeTagTokenContent) {
 	const match = closeTagTokenContent.match(RE_CLOSE_TAG_NAME);
 	if (match === null) throw new Error(`Unable to parse close tag name.\n${closeTagTokenContent} does not match pattern of closing tag.`);
-	return match[1].trim().toLowerCase();
+	const tagName = match.groups?.tagName;
+	if (tagName === void 0) throw new Error(`Unable to parse close tag name. Named capture group "tagName" is missing.`);
+	return tagName.trim().toLowerCase();
 }
 //#endregion
 //#region src/utils/calculateTokenLocation.ts
@@ -776,11 +929,7 @@ function calculateTokenLocation(source, range) {
 * @returns Array containing [startPosition, endPosition + 1]
 */
 function calculateTokenCharactersRange(state, options) {
-	const startPosition = state.sourceCode.index() - (state.accumulatedContent.length() - 1) - state.decisionBuffer.length();
-	let endPosition = 0;
-	if (options.keepBuffer) endPosition = state.sourceCode.index();
-	else endPosition = state.sourceCode.index() - state.decisionBuffer.length();
-	return [startPosition, endPosition + 1];
+	return [state.sourceCode.index() - (state.accumulatedContent.length() - 1) - state.decisionBuffer.length(), (options.keepBuffer ? state.sourceCode.index() : state.sourceCode.index() - state.decisionBuffer.length()) + 1];
 }
 //#endregion
 //#region src/utils/calculateTokenPosition.ts
@@ -829,7 +978,7 @@ const dispatch$13 = createTokenDispatcher([
 		}
 	},
 	{
-		tokenType: new Set(["AttributeKey", "AttributeAssignment"]),
+		tokenType: /* @__PURE__ */ new Set(["AttributeKey", "AttributeAssignment"]),
 		handler(_, state) {
 			state.currentContext = {
 				parentRef: state.currentContext,
@@ -844,7 +993,7 @@ const dispatch$13 = createTokenDispatcher([
 			const tagName = state.currentNode.name;
 			state.currentNode.openEnd = createNodeFrom(token);
 			updateNodeEnd(state.currentNode, token);
-			if (tagName && SELF_CLOSING_ELEMENTS.has(tagName) && state.currentNode.openEnd.value === "/>") {
+			if (tagName && state.currentNode.openEnd.value === "/>") {
 				state.currentNode.selfClosing = true;
 				state.currentNode = state.currentNode.parentRef;
 				state.currentContext = state.currentContext.parentRef;
@@ -875,6 +1024,9 @@ const dispatch$13 = createTokenDispatcher([
 	state.caretPosition++;
 	return state;
 });
+/**
+* Construct an element node after its opening tag has started.
+*/
 function construct$13(token, state) {
 	return dispatch$13(token, state);
 }
@@ -893,6 +1045,7 @@ const dispatch$12 = createTokenDispatcher([
 		tokenType: "CommentContent",
 		handler(token, state) {
 			state.currentNode.content = token.value;
+			state.currentNode.value = token.value;
 			state.caretPosition++;
 			return state;
 		}
@@ -908,6 +1061,9 @@ const dispatch$12 = createTokenDispatcher([
 		}
 	}
 ]);
+/**
+* Construct a comment node from comment tokens.
+*/
 function construct$12(token, state) {
 	return dispatch$12(token, state);
 }
@@ -935,7 +1091,7 @@ const dispatch$11 = createTokenDispatcher([
 		}
 	},
 	{
-		tokenType: new Set(["DoctypeAttributeWrapperStart", "DoctypeAttributeValue"]),
+		tokenType: /* @__PURE__ */ new Set(["DoctypeAttributeWrapperStart", "DoctypeAttributeValue"]),
 		handler(_, state) {
 			state.currentContext = {
 				parentRef: state.currentContext,
@@ -948,6 +1104,9 @@ const dispatch$11 = createTokenDispatcher([
 	state.caretPosition++;
 	return state;
 });
+/**
+* Construct a doctype node from doctype tokens.
+*/
 function construct$11(token, state) {
 	return dispatch$11(token, state);
 }
@@ -966,6 +1125,9 @@ const dispatch$10 = createTokenDispatcher([{
 	state.caretPosition++;
 	return state;
 });
+/**
+* Construct the normalized name for an element node.
+*/
 function construct$10(token, state) {
 	return dispatch$10(token, state);
 }
@@ -974,7 +1136,7 @@ function construct$10(token, state) {
 var attribute_exports = /* @__PURE__ */ __exportAll({ construct: () => construct$9 });
 const dispatch$9 = createTokenDispatcher([
 	{
-		tokenType: new Set(["OpenTagEnd"]),
+		tokenType: /* @__PURE__ */ new Set(["OpenTagEnd"]),
 		handler(_, state) {
 			state.currentContext = state.currentContext.parentRef;
 			return state;
@@ -1012,6 +1174,9 @@ const dispatch$9 = createTokenDispatcher([
 	state.caretPosition++;
 	return state;
 });
+/**
+* Construct an element attribute from attribute tokens.
+*/
 function construct$9(token, state) {
 	return dispatch$9(token, state);
 }
@@ -1019,7 +1184,7 @@ function construct$9(token, state) {
 //#region src/constructor/handlers/attributes.ts
 var attributes_exports$1 = /* @__PURE__ */ __exportAll({ construct: () => construct$8 });
 const dispatch$8 = createTokenDispatcher([{
-	tokenType: new Set(["AttributeKey", "AttributeAssignment"]),
+	tokenType: /* @__PURE__ */ new Set(["AttributeKey", "AttributeAssignment"]),
 	handler(token, state) {
 		initAttributesIfNone(state.currentNode);
 		state.currentNode.attributes.push({
@@ -1034,7 +1199,7 @@ const dispatch$8 = createTokenDispatcher([{
 		return state;
 	}
 }, {
-	tokenType: new Set(["OpenTagEnd"]),
+	tokenType: /* @__PURE__ */ new Set(["OpenTagEnd"]),
 	handler(_, state) {
 		state.currentContext = state.currentContext.parentRef;
 		return state;
@@ -1043,18 +1208,54 @@ const dispatch$8 = createTokenDispatcher([{
 	state.caretPosition++;
 	return state;
 });
+/**
+* Construct the attributes collection for an element node.
+*/
 function construct$8(token, state) {
 	return dispatch$8(token, state);
 }
 //#endregion
 //#region src/constructor/handlers/tagContent.ts
 var tagContent_exports = /* @__PURE__ */ __exportAll({ construct: () => construct$7 });
+function addUnclosedTagError(state, node) {
+	state.errorHandler.addError({
+		type: "UnclosedTag",
+		message: `Unclosed tag "${node.name ?? "unknown"}".`,
+		range: cloneRange(node.range),
+		loc: cloneLocation(node.loc),
+		recovery: "The parser kept the partial element in the AST."
+	});
+}
 const dispatch$7 = createTokenDispatcher([
+	{
+		tokenType: "XMLDeclarationOpen",
+		handler(token, state) {
+			if (state.currentNode.type !== "Document") {
+				state.caretPosition++;
+				return state;
+			}
+			initChildrenIfNone(state.currentNode);
+			const declarationNode = {
+				type: "XMLDeclaration",
+				parentRef: state.currentNode,
+				range: cloneRange(token.range),
+				loc: cloneLocation(token.loc),
+				attributes: []
+			};
+			state.currentNode.children.push(declarationNode);
+			state.currentNode = declarationNode;
+			state.currentContext = {
+				parentRef: state.currentContext,
+				type: "XMLDeclaration"
+			};
+			return state;
+		}
+	},
 	{
 		tokenType: "OpenTagStart",
 		handler(token, state) {
 			initChildrenIfNone(state.currentNode);
-			const tagNode = {
+			const elementNode = {
 				type: "Element",
 				parentRef: state.currentNode,
 				range: cloneRange(token.range),
@@ -1062,8 +1263,8 @@ const dispatch$7 = createTokenDispatcher([
 				attributes: [],
 				children: []
 			};
-			state.currentNode.children.push(tagNode);
-			state.currentNode = tagNode;
+			state.currentNode.children.push(elementNode);
+			state.currentNode = elementNode;
 			state.currentContext = {
 				parentRef: state.currentContext,
 				type: "Tag"
@@ -1108,7 +1309,31 @@ const dispatch$7 = createTokenDispatcher([
 	{
 		tokenType: "CloseTag",
 		handler(token, state) {
-			if (parseCloseTagName(token.value) !== state.currentNode.name) {
+			const closeTagName = parseCloseTagName(token.value);
+			if (closeTagName !== state.currentNode.name) {
+				state.errorHandler.addError({
+					type: "MismatchedTag",
+					message: `Expected closing tag for "${state.currentNode.name ?? "unknown"}" but found "${closeTagName}".`,
+					range: cloneRange(token.range),
+					loc: cloneLocation(token.loc),
+					recovery: "The mismatched closing tag was skipped."
+				});
+				let ancestor = state.currentNode.parentRef;
+				let context = state.currentContext.parentRef?.parentRef;
+				while (ancestor && ancestor.type !== "Document") {
+					if (ancestor.name === closeTagName) {
+						let unclosedNode = state.currentNode;
+						while (unclosedNode && unclosedNode !== ancestor) {
+							addUnclosedTagError(state, unclosedNode);
+							unclosedNode = unclosedNode.parentRef;
+						}
+						state.currentNode = ancestor;
+						state.currentContext = context;
+						return state;
+					}
+					ancestor = ancestor.parentRef;
+					context = context?.parentRef?.parentRef;
+				}
 				state.caretPosition++;
 				return state;
 			}
@@ -1139,6 +1364,9 @@ const dispatch$7 = createTokenDispatcher([
 	state.caretPosition++;
 	return state;
 });
+/**
+* Construct document or element children from content tokens.
+*/
 function construct$7(token, state) {
 	return dispatch$7(token, state);
 }
@@ -1147,7 +1375,7 @@ function construct$7(token, state) {
 var attributeValue_exports$1 = /* @__PURE__ */ __exportAll({ construct: () => construct$6 });
 const dispatch$6 = createTokenDispatcher([
 	{
-		tokenType: new Set([
+		tokenType: /* @__PURE__ */ new Set([
 			"OpenTagEnd",
 			"AttributeKey",
 			"AttributeAssignment"
@@ -1192,6 +1420,9 @@ const dispatch$6 = createTokenDispatcher([
 	state.caretPosition++;
 	return state;
 });
+/**
+* Construct an element attribute value from value tokens.
+*/
 function construct$6(token, state) {
 	return dispatch$6(token, state);
 }
@@ -1199,10 +1430,12 @@ function construct$6(token, state) {
 //#region src/constructor/handlers/xmlDeclaration.ts
 var xmlDeclaration_exports = /* @__PURE__ */ __exportAll({ construct: () => construct$5 });
 const dispatch$5 = createTokenDispatcher([{
-	tokenType: "OpenTagStart",
-	handler(token, state) {
-		state.currentNode.name = parseOpenTagName(token.value);
-		state.currentContext = state.currentContext.parentRef;
+	tokenType: "XMLDeclarationOpen",
+	handler(_, state) {
+		state.currentContext = {
+			parentRef: state.currentContext,
+			type: "XMLDeclarationAttributes"
+		};
 		state.caretPosition++;
 		return state;
 	}
@@ -1210,6 +1443,9 @@ const dispatch$5 = createTokenDispatcher([{
 	state.caretPosition++;
 	return state;
 });
+/**
+* Construct an XML declaration node after its opening token.
+*/
 function construct$5(token, state) {
 	return dispatch$5(token, state);
 }
@@ -1265,6 +1501,9 @@ const dispatch$4 = createTokenDispatcher([
 	state.caretPosition++;
 	return state;
 });
+/**
+* Construct a doctype attribute from value and wrapper tokens.
+*/
 function construct$4(token, state) {
 	return dispatch$4(token, state);
 }
@@ -1278,7 +1517,7 @@ const dispatch$3 = createTokenDispatcher([{
 		return state;
 	}
 }, {
-	tokenType: new Set(["DoctypeAttributeWrapperStart", "DoctypeAttributeValue"]),
+	tokenType: /* @__PURE__ */ new Set(["DoctypeAttributeWrapperStart", "DoctypeAttributeValue"]),
 	handler(token, state) {
 		initAttributesIfNone(state.currentNode);
 		state.currentNode.attributes.push({
@@ -1296,6 +1535,9 @@ const dispatch$3 = createTokenDispatcher([{
 	state.caretPosition++;
 	return state;
 });
+/**
+* Construct the attributes collection for a doctype node.
+*/
 function construct$3(token, state) {
 	return dispatch$3(token, state);
 }
@@ -1304,40 +1546,36 @@ function construct$3(token, state) {
 var xmlDeclarationAttribute_exports = /* @__PURE__ */ __exportAll({ construct: () => construct$2 });
 const dispatch$2 = createTokenDispatcher([
 	{
-		tokenType: new Set([
-			"OpenTagEnd",
-			"AttributeKey",
-			"AttributeAssignment"
-		]),
+		tokenType: /* @__PURE__ */ new Set(["XMLDeclarationClose"]),
 		handler(_, state) {
 			state.currentContext = state.currentContext.parentRef;
 			return state;
 		}
 	},
 	{
-		tokenType: "AttributeValue",
+		tokenType: "XMLDeclarationAttributeKey",
 		handler(token, state) {
 			const attribute = getLastAttribute(state);
-			attribute.value = createNodeFrom(token);
-			updateNodeEnd(attribute, token);
-			state.caretPosition++;
-			return state;
-		}
-	},
-	{
-		tokenType: "AttributeValueWrapperStart",
-		handler(token, state) {
-			const attribute = getLastAttribute(state);
-			attribute.quoteChar = token.value;
-			if (!attribute.key) attribute.range = cloneRange(token.range);
+			if (attribute.key !== void 0 || attribute.value !== void 0) {
+				state.currentContext = state.currentContext.parentRef;
+				return state;
+			}
+			attribute.key = createNodeFrom(token);
 			state.caretPosition++;
 			return state;
 		}
 	},
 	{
-		tokenType: "AttributeValueWrapperEnd",
-		handler(token, state) {
-			updateNodeEnd(getLastAttribute(state), token);
+		tokenType: "XMLDeclarationAttributeAssignment",
+		handler(_, state) {
+			if (getLastAttribute(state).value !== void 0) {
+				state.currentContext = state.currentContext.parentRef;
+				return state;
+			}
+			state.currentContext = {
+				parentRef: state.currentContext,
+				type: "XMLDeclarationAttributeValue"
+			};
 			state.caretPosition++;
 			return state;
 		}
@@ -1346,6 +1584,9 @@ const dispatch$2 = createTokenDispatcher([
 	state.caretPosition++;
 	return state;
 });
+/**
+* Construct an XML declaration attribute key and value transition.
+*/
 function construct$2(token, state) {
 	return dispatch$2(token, state);
 }
@@ -1353,17 +1594,20 @@ function construct$2(token, state) {
 //#region src/constructor/handlers/xmlDeclarationAttributes.ts
 var xmlDeclarationAttributes_exports$1 = /* @__PURE__ */ __exportAll({ construct: () => construct$1 });
 const dispatch$1 = createTokenDispatcher([{
-	tokenType: "OpenTagEnd",
-	handler(_, state) {
+	tokenType: "XMLDeclarationClose",
+	handler(token, state) {
+		updateNodeEnd(state.currentNode, token);
+		state.currentNode = state.currentNode.parentRef;
 		state.currentContext = state.currentContext.parentRef;
+		state.caretPosition++;
 		return state;
 	}
 }, {
-	tokenType: new Set(["AttributeKey", "AttributeAssignment"]),
+	tokenType: /* @__PURE__ */ new Set(["XMLDeclarationAttributeKey", "XMLDeclarationAttributeAssignment"]),
 	handler(token, state) {
 		initAttributesIfNone(state.currentNode);
 		state.currentNode.attributes.push({
-			type: "Attribute",
+			type: "XMLDeclarationAttribute",
 			range: cloneRange(token.range),
 			loc: cloneLocation(token.loc)
 		});
@@ -1377,6 +1621,9 @@ const dispatch$1 = createTokenDispatcher([{
 	state.caretPosition++;
 	return state;
 });
+/**
+* Construct the attributes collection for an XML declaration node.
+*/
 function construct$1(token, state) {
 	return dispatch$1(token, state);
 }
@@ -1385,14 +1632,14 @@ function construct$1(token, state) {
 var xmlDeclarationAttributeValue_exports$1 = /* @__PURE__ */ __exportAll({ construct: () => construct });
 const dispatch = createTokenDispatcher([
 	{
-		tokenType: "OpenTagEnd",
+		tokenType: "XMLDeclarationClose",
 		handler(_, state) {
 			state.currentContext = state.currentContext.parentRef;
 			return state;
 		}
 	},
 	{
-		tokenType: "AttributeValue",
+		tokenType: "XMLDeclarationAttributeValue",
 		handler(token, state) {
 			const attribute = getLastAttribute(state);
 			if (attribute.value !== void 0) {
@@ -1406,7 +1653,7 @@ const dispatch = createTokenDispatcher([
 		}
 	},
 	{
-		tokenType: "AttributeValueWrapperStart",
+		tokenType: "XMLDeclarationAttributeValueWrapperStart",
 		handler(token, state) {
 			const attribute = getLastAttribute(state);
 			if (attribute.value !== void 0) {
@@ -1420,7 +1667,7 @@ const dispatch = createTokenDispatcher([
 		}
 	},
 	{
-		tokenType: "AttributeValueWrapperEnd",
+		tokenType: "XMLDeclarationAttributeValueWrapperEnd",
 		handler(token, state) {
 			updateNodeEnd(getLastAttribute(state), token);
 			state.currentContext = state.currentContext.parentRef;
@@ -1432,6 +1679,9 @@ const dispatch = createTokenDispatcher([
 	state.caretPosition++;
 	return state;
 });
+/**
+* Construct an XML declaration attribute value from value tokens.
+*/
 function construct(token, state) {
 	return dispatch(token, state);
 }
@@ -1474,6 +1724,24 @@ function processTokens(tokens, state, positionOffset) {
 	}
 	return state;
 }
+function reportUnclosedNodes(state) {
+	let node = state.currentNode;
+	while (node && node !== state.rootNode) {
+		if (node.type === "Element" && !node.selfClosing && !node.close) state.errorHandler.addError({
+			type: "UnclosedTag",
+			message: `Unclosed tag "${node.name ?? "unknown"}".`,
+			range: cloneRange(node.range),
+			loc: cloneLocation(node.loc),
+			recovery: "The parser kept the partial element in the AST."
+		});
+		node = node.parentRef;
+	}
+}
+/**
+* Build the document AST from tokenizer output.
+* @param tokens - Tokens produced from SVG source
+* @returns Constructed AST, final constructor state, and recoverable diagnostics
+*/
 function constructTree(tokens) {
 	const rootContext = {
 		type: "TagContent",
@@ -1498,48 +1766,84 @@ function constructTree(tokens) {
 		caretPosition: 0,
 		currentContext: rootContext,
 		currentNode: rootNode,
+		errorHandler: new ErrorHandler(),
 		rootNode
 	};
 	const positionOffset = state.caretPosition;
-	processTokens(tokens, state, positionOffset);
+	reportUnclosedNodes(processTokens(tokens, state, positionOffset));
 	return {
 		state,
-		ast: state.rootNode
+		ast: state.rootNode,
+		errors: state.errorHandler.getErrors(),
+		warnings: state.errorHandler.getWarnings()
 	};
 }
 //#endregion
 //#region src/tokenizer/charsBuffer.ts
+/**
+* Mutable buffer used by tokenizer handlers while deciding token boundaries.
+*/
 var CharsBuffer = class {
 	charsBuffer = [];
+	/**
+	* Append a character wrapper to the buffer.
+	*/
 	concat(chars) {
 		const theLast = this.last();
-		if (theLast) theLast.concat(chars);
+		if (theLast) theLast.append(chars);
 		else this.charsBuffer.push(chars);
 	}
+	/**
+	* Append another buffer without merging its entries.
+	*/
 	concatBuffer(buffer) {
 		this.charsBuffer.push(...buffer.charsBuffer);
 	}
+	/**
+	* Get the total buffered character length.
+	*/
 	length() {
 		return this.charsBuffer.map((chars) => chars.length()).reduce((a, b) => a + b, 0);
 	}
+	/**
+	* Clear all buffered characters.
+	*/
 	clear() {
 		this.charsBuffer = [];
 	}
+	/**
+	* Get the concatenated buffered string.
+	*/
 	value() {
 		return this.charsBuffer.map((chars) => chars.value).join("");
 	}
+	/**
+	* Get the last buffered character wrapper.
+	*/
 	last() {
 		return last(this.charsBuffer);
 	}
+	/**
+	* Get the first buffered character wrapper.
+	*/
 	first() {
 		return first(this.charsBuffer);
 	}
+	/**
+	* Remove the last buffered entry.
+	*/
 	removeLast() {
 		this.charsBuffer.splice(-1, 1);
 	}
+	/**
+	* Remove the first buffered entry.
+	*/
 	removeFirst() {
 		this.charsBuffer.splice(0, 1);
 	}
+	/**
+	* Replace this buffer with a copy of another buffer.
+	*/
 	replace(other) {
 		this.charsBuffer = [...other.charsBuffer];
 	}
@@ -1550,7 +1854,7 @@ var data_exports = /* @__PURE__ */ __exportAll({
 	handleContentEnd: () => handleContentEnd,
 	parse: () => parse$22
 });
-const INCOMPLETE_DOCTYPE_CHARS = new Set([
+const INCOMPLETE_DOCTYPE_CHARS = /* @__PURE__ */ new Set([
 	"<!",
 	"<!D",
 	"<!DO",
@@ -1559,6 +1863,17 @@ const INCOMPLETE_DOCTYPE_CHARS = new Set([
 	"<!DOCTY",
 	"<!DOCTYP"
 ]);
+const INCOMPLETE_COMMENT_START_CHARS = /* @__PURE__ */ new Set([
+	SPECIAL_CHAR.openingCorner,
+	"<!",
+	"<!-"
+]);
+const INCOMPLETE_XML_DECLARATION_START_CHARS = /* @__PURE__ */ new Set([
+	SPECIAL_CHAR.openingCorner,
+	"<?",
+	"<?x",
+	"<?xm"
+]);
 function generateTextToken(state) {
 	const position = calculateTokenPosition(state, { keepBuffer: false });
 	return {
@@ -1608,17 +1923,28 @@ function parseDoctypeOpen(state) {
 }
 function parseXMLDeclarationOpen(state) {
 	if (state.accumulatedContent.length() !== 0) state.tokens.push(generateTextToken(state));
+	const range = [state.sourceCode.index() - 4, state.sourceCode.index() + 1];
+	state.tokens.push({
+		type: "XMLDeclarationOpen",
+		value: state.decisionBuffer.value(),
+		range,
+		loc: state.sourceCode.getLocationOf(range)
+	});
 	state.accumulatedContent.clear();
 	state.decisionBuffer.clear();
 	state.currentContext = "XMLDeclarationAttributes";
 	state.sourceCode.next();
 }
+/**
+* Tokenize top-level text and dispatch into markup-specific contexts.
+*/
 function parse$22(chars, state) {
 	const value = chars.value();
 	if (value === "<?xml") return parseXMLDeclarationOpen(state);
+	if (INCOMPLETE_XML_DECLARATION_START_CHARS.has(value)) return state.sourceCode.next();
 	if (RE_OPEN_TAG_START.test(value)) return parseOpeningCornerBraceWithText(state);
 	if (value === "</") return parseOpeningCornerBraceWithSlash(state);
-	if (value === SPECIAL_CHAR.openingCorner || value === "<!" || value === "<!-") return state.sourceCode.next();
+	if (INCOMPLETE_COMMENT_START_CHARS.has(value)) return state.sourceCode.next();
 	if (value === "<!--") return parseCommentOpen(state);
 	if (isIncompleteDoctype(value)) return state.sourceCode.next();
 	if (value.toUpperCase() === "<!DOCTYPE") return parseDoctypeOpen(state);
@@ -1626,6 +1952,9 @@ function parse$22(chars, state) {
 	state.decisionBuffer.clear();
 	state.sourceCode.next();
 }
+/**
+* Flush buffered text when the source ends in data context.
+*/
 function handleContentEnd(state) {
 	const textContent = state.accumulatedContent.value() + state.decisionBuffer.value();
 	if (textContent.length !== 0) {
@@ -1654,6 +1983,9 @@ function parseClosingCornerBrace$5(state) {
 	state.currentContext = "Data";
 	state.sourceCode.next();
 }
+/**
+* Tokenize a closing tag.
+*/
 function parse$21(chars, state) {
 	if (chars.value() === SPECIAL_CHAR.closingCorner) return parseClosingCornerBrace$5(state);
 	state.accumulatedContent.concatBuffer(state.decisionBuffer);
@@ -1671,7 +2003,7 @@ function parseTagEnd$3(state) {
 	state.contextParams["OpenTagEnd"] = { tagName };
 	state.contextParams["Attributes"] = void 0;
 }
-function parseEqual(state) {
+function parseEqual$1(state) {
 	const position = calculateTokenPosition(state, { keepBuffer: true });
 	state.tokens.push({
 		type: "AttributeAssignment",
@@ -1684,17 +2016,20 @@ function parseEqual(state) {
 	state.currentContext = "AttributeValue";
 	state.sourceCode.next();
 }
-function parseNoneWhitespace(chars, state) {
+function parseNoneWhitespace$1(chars, state) {
 	state.accumulatedContent.replace(state.decisionBuffer);
 	state.currentContext = "AttributeKey";
 	state.decisionBuffer.clear();
 	state.sourceCode.next();
 }
+/**
+* Tokenize whitespace, assignments, and attribute starts inside an open tag.
+*/
 function parse$20(chars, state) {
 	const value = chars.value();
 	if (value === SPECIAL_CHAR.closingCorner || value === SPECIAL_CHAR.slash) return parseTagEnd$3(state);
-	if (value === SPECIAL_CHAR.equal) return parseEqual(state);
-	if (!isWhitespace(value)) return parseNoneWhitespace(chars, state);
+	if (value === SPECIAL_CHAR.equal) return parseEqual$1(state);
+	if (!isWhitespace(value)) return parseNoneWhitespace$1(chars, state);
 	state.decisionBuffer.clear();
 	state.sourceCode.next();
 }
@@ -1715,6 +2050,9 @@ function parseClosingCornerBrace$4(state) {
 	state.sourceCode.next();
 	state.contextParams["OpenTagEnd"] = void 0;
 }
+/**
+* Tokenize the end of an opening tag.
+*/
 function parse$19(chars, state) {
 	if (chars.value() === SPECIAL_CHAR.closingCorner) return parseClosingCornerBrace$4(state);
 	state.accumulatedContent.concatBuffer(state.decisionBuffer);
@@ -1745,6 +2083,9 @@ function parseClosingCornerBrace$3(state) {
 	state.decisionBuffer.clear();
 	state.currentContext = "DoctypeClose";
 }
+/**
+* Tokenize the opening delimiter of a doctype declaration.
+*/
 function parse$18(chars, state) {
 	const value = chars.value();
 	if (isWhitespace(value)) return parseWhitespace$1(state);
@@ -1771,6 +2112,9 @@ function parseKeyEnd$1(state) {
 	state.decisionBuffer.clear();
 	state.currentContext = "Attributes";
 }
+/**
+* Tokenize an element attribute key.
+*/
 function parse$17(chars, state) {
 	if (isKeyBreak$1(chars)) return parseKeyEnd$1(state);
 	state.accumulatedContent.concatBuffer(state.decisionBuffer);
@@ -1780,6 +2124,9 @@ function parse$17(chars, state) {
 //#endregion
 //#region src/tokenizer/handlers/doctypeClose.ts
 var doctypeClose_exports = /* @__PURE__ */ __exportAll({ parse: () => parse$16 });
+/**
+* Tokenize the closing delimiter of a doctype declaration.
+*/
 function parse$16(chars, state) {
 	const position = calculateTokenPosition(state, { keepBuffer: true });
 	state.tokens.push({
@@ -1825,6 +2172,9 @@ function parseWhitespace(state) {
 	state.contextParams["Attributes"] = { tagName };
 	state.sourceCode.next();
 }
+/**
+* Tokenize the start of an opening tag.
+*/
 function parse$15(chars, state) {
 	const value = chars.value();
 	if (value === SPECIAL_CHAR.closingCorner || value === SPECIAL_CHAR.slash) return parseTagEnd$2(state);
@@ -1862,6 +2212,9 @@ function parseBare$2(state) {
 	state.currentContext = "AttributeValueBare";
 	state.sourceCode.next();
 }
+/**
+* Tokenize the start of an element attribute value.
+*/
 function parse$14(chars, state) {
 	const value = chars.value();
 	if (value === SPECIAL_CHAR.doubleQuote || value === SPECIAL_CHAR.singleQuote) return parseWrapper$5(state);
@@ -1893,6 +2246,9 @@ function parseCommentClose(state) {
 	state.currentContext = "Data";
 	state.sourceCode.next();
 }
+/**
+* Tokenize comment content until the closing delimiter.
+*/
 function parse$13(chars, state) {
 	const value = chars.value();
 	if (value === SPECIAL_CHAR.hyphen || value === "--") return state.sourceCode.next();
@@ -1930,6 +2286,9 @@ function parseBare$1(state) {
 	state.currentContext = "DoctypeAttributeBare";
 	state.sourceCode.next();
 }
+/**
+* Tokenize doctype attributes and the doctype close transition.
+*/
 function parse$12(chars, state) {
 	const value = chars.value();
 	if (value === SPECIAL_CHAR.doubleQuote || value === SPECIAL_CHAR.singleQuote) return parseWrapper$4(state);
@@ -1953,6 +2312,9 @@ function parseValueEnd(state) {
 	state.decisionBuffer.clear();
 	state.currentContext = "Attributes";
 }
+/**
+* Tokenize an unquoted element attribute value.
+*/
 function parse$11(chars, state) {
 	const value = chars.value();
 	if (isWhitespace(value) || value === SPECIAL_CHAR.closingCorner || value === SPECIAL_CHAR.slash) return parseValueEnd(state);
@@ -1977,6 +2339,9 @@ function parseClosingCornerBrace$1(state) {
 	state.sourceCode.next();
 	state.contextParams["OpenTagEnd"] = void 0;
 }
+/**
+* Tokenize the opening delimiter of an XML declaration.
+*/
 function parse$10(chars, state) {
 	if (chars.value() === SPECIAL_CHAR.closingCorner) return parseClosingCornerBrace$1(state);
 	state.accumulatedContent.concatBuffer(state.decisionBuffer);
@@ -2000,6 +2365,9 @@ function parseClosingCornerBrace(state) {
 	state.sourceCode.next();
 	state.contextParams["OpenTagEnd"] = void 0;
 }
+/**
+* Tokenize the closing delimiter of an XML declaration.
+*/
 function parse$9(chars, state) {
 	if (chars.value() === SPECIAL_CHAR.closingCorner) return parseClosingCornerBrace(state);
 	state.accumulatedContent.concatBuffer(state.decisionBuffer);
@@ -2021,6 +2389,9 @@ function parseAttributeEnd(state) {
 	state.decisionBuffer.clear();
 	state.currentContext = "DoctypeAttributes";
 }
+/**
+* Tokenize an unquoted doctype attribute value.
+*/
 function parse$8(chars, state) {
 	const value = chars.value();
 	if (isWhitespace(value) || value === SPECIAL_CHAR.closingCorner) return parseAttributeEnd(state);
@@ -2053,6 +2424,9 @@ function parseWrapper$3(state) {
 	state.sourceCode.next();
 	state.contextParams["AttributeValueWrapped"] = void 0;
 }
+/**
+* Tokenize a quoted element attribute value.
+*/
 function parse$7(chars, state) {
 	const wrapperChar = state.contextParams["AttributeValueWrapped"]?.wrapper;
 	if (chars.value() === wrapperChar) return parseWrapper$3(state);
@@ -2085,6 +2459,9 @@ function parseWrapper$2(state) {
 	state.sourceCode.next();
 	state.contextParams["DoctypeAttributeWrapped"] = void 0;
 }
+/**
+* Tokenize a quoted doctype attribute value.
+*/
 function parse$6(chars, state) {
 	if (chars.value() === state.contextParams["DoctypeAttributeWrapped"]?.wrapper) return parseWrapper$2(state);
 	state.accumulatedContent.concatBuffer(state.decisionBuffer);
@@ -2108,11 +2485,34 @@ function parseXMLDeclarationClose(state) {
 	state.currentContext = "Data";
 	state.sourceCode.next();
 }
+function parseEqual(state) {
+	const position = calculateTokenPosition(state, { keepBuffer: true });
+	state.tokens.push({
+		type: "XMLDeclarationAttributeAssignment",
+		value: state.decisionBuffer.value(),
+		range: position.range,
+		loc: position.loc
+	});
+	state.accumulatedContent.clear();
+	state.decisionBuffer.clear();
+	state.currentContext = "XMLDeclarationAttributeValue";
+	state.sourceCode.next();
+}
+function parseNoneWhitespace(state) {
+	state.accumulatedContent.replace(state.decisionBuffer);
+	state.currentContext = "XMLDeclarationAttributeKey";
+	state.decisionBuffer.clear();
+	state.sourceCode.next();
+}
+/**
+* Tokenize XML declaration attributes and the declaration close transition.
+*/
 function parse$5(chars, state) {
 	const value = chars.value();
-	if (value === SPECIAL_CHAR.question || value === SPECIAL_CHAR.closingCorner) return parseXMLDeclarationClose(state);
+	if (value === SPECIAL_CHAR.question) return state.sourceCode.next();
 	if (value === "?>") return parseXMLDeclarationClose(state);
-	state.accumulatedContent.concatBuffer(state.decisionBuffer);
+	if (value === SPECIAL_CHAR.equal) return parseEqual(state);
+	if (!isWhitespace(value)) return parseNoneWhitespace(state);
 	state.decisionBuffer.clear();
 	state.sourceCode.next();
 }
@@ -2135,6 +2535,9 @@ function parseKeyEnd(state) {
 	state.decisionBuffer.clear();
 	state.currentContext = "XMLDeclarationAttributes";
 }
+/**
+* Tokenize an XML declaration attribute key.
+*/
 function parse$4(chars, state) {
 	if (isKeyBreak(chars)) return parseKeyEnd(state);
 	state.accumulatedContent.concatBuffer(state.decisionBuffer);
@@ -2148,28 +2551,38 @@ function parseWrapper$1(state) {
 	const wrapper = state.decisionBuffer.value();
 	const range = [state.sourceCode.index(), state.sourceCode.index() + 1];
 	state.tokens.push({
-		type: "AttributeValueWrapperStart",
+		type: "XMLDeclarationAttributeValueWrapperStart",
 		value: wrapper,
 		range,
 		loc: state.sourceCode.getLocationOf(range)
 	});
 	state.accumulatedContent.clear();
 	state.decisionBuffer.clear();
-	state.currentContext = "AttributeValueWrapped";
-	state.contextParams["AttributeValueWrapped"] = { wrapper };
+	state.currentContext = "XMLDeclarationAttributeValueWrapped";
+	state.contextParams["XMLDeclarationAttributeValueWrapped"] = { wrapper };
 	state.sourceCode.next();
 }
 function parseTagEnd(state) {
 	state.accumulatedContent.clear();
 	state.decisionBuffer.clear();
-	state.currentContext = "Attributes";
+	state.currentContext = "XMLDeclarationAttributes";
 }
 function parseBare(state) {
-	state.accumulatedContent.replace(state.decisionBuffer);
+	const range = [state.sourceCode.index(), state.sourceCode.index() + 1];
+	state.tokens.push({
+		type: "XMLDeclarationAttributeValue",
+		value: state.decisionBuffer.value(),
+		range,
+		loc: state.sourceCode.getLocationOf(range)
+	});
+	state.accumulatedContent.clear();
 	state.decisionBuffer.clear();
-	state.currentContext = "AttributeValueBare";
+	state.currentContext = "XMLDeclarationAttributes";
 	state.sourceCode.next();
 }
+/**
+* Tokenize the start of an XML declaration attribute value.
+*/
 function parse$3(chars, state) {
 	const value = chars.value();
 	if (value === SPECIAL_CHAR.doubleQuote || value === SPECIAL_CHAR.singleQuote) return parseWrapper$1(state);
@@ -2185,26 +2598,29 @@ function parseWrapper(state) {
 	const position = calculateTokenPosition(state, { keepBuffer: false });
 	const endWrapperPosition = position.range[1];
 	state.tokens.push({
-		type: "AttributeValue",
+		type: "XMLDeclarationAttributeValue",
 		value: state.accumulatedContent.value(),
 		range: position.range,
 		loc: position.loc
 	});
 	const range = [endWrapperPosition, endWrapperPosition + 1];
 	state.tokens.push({
-		type: "AttributeValueWrapperEnd",
+		type: "XMLDeclarationAttributeValueWrapperEnd",
 		value: state.decisionBuffer.value(),
 		range,
 		loc: state.sourceCode.getLocationOf(range)
 	});
 	state.accumulatedContent.clear();
 	state.decisionBuffer.clear();
-	state.currentContext = "Attributes";
+	state.currentContext = "XMLDeclarationAttributes";
 	state.sourceCode.next();
-	state.contextParams["AttributeValueWrapped"] = void 0;
+	state.contextParams["XMLDeclarationAttributeValueWrapped"] = void 0;
 }
+/**
+* Tokenize a quoted XML declaration attribute value.
+*/
 function parse$2(chars, state) {
-	const wrapperChar = state.contextParams["AttributeValueWrapped"]?.wrapper;
+	const wrapperChar = state.contextParams["XMLDeclarationAttributeValueWrapped"]?.wrapper;
 	if (chars.value() === wrapperChar) return parseWrapper(state);
 	state.accumulatedContent.concatBuffer(state.decisionBuffer);
 	state.decisionBuffer.clear();
@@ -2212,9 +2628,15 @@ function parse$2(chars, state) {
 }
 //#endregion
 //#region src/tokenizer/handlers/index.ts
+/**
+* Tokenizer handler for contexts that intentionally consume no content.
+*/
 const noop = { parse: () => {} };
 //#endregion
 //#region src/tokenizer/chars.ts
+/**
+* Buffered source characters with their source range.
+*/
 var Chars = class {
 	value;
 	range;
@@ -2222,19 +2644,31 @@ var Chars = class {
 		this.value = value;
 		this.range = range;
 	}
-	concat(chars) {
+	/**
+	* Append adjacent characters into this range.
+	*/
+	append(chars) {
 		this.value += chars.value;
 		this.range[1] = chars.range[1];
 	}
+	/**
+	* Compare the buffered value with raw text.
+	*/
 	equals(chars) {
 		return this.value === chars;
 	}
+	/**
+	* Get the buffered string length.
+	*/
 	length() {
 		return this.value.length;
 	}
 };
 //#endregion
 //#region src/tokenizer/sourceCode.ts
+/**
+* Cursor-based view over source text for tokenizer handlers.
+*/
 var SourceCode = class {
 	source;
 	charsList;
@@ -2243,24 +2677,42 @@ var SourceCode = class {
 		this.source = source;
 		this.charsList = this.createCharsList();
 	}
+	/**
+	* Convert a character range to source locations.
+	*/
 	getLocationOf(range) {
 		return {
 			start: getLineInfo(this.source, range[0]),
 			end: getLineInfo(this.source, range[1])
 		};
 	}
+	/**
+	* Get the current character wrapper.
+	*/
 	current() {
 		return this.charsList[this.charsIndex];
 	}
+	/**
+	* Advance to the next character.
+	*/
 	next() {
 		this.charsIndex++;
 	}
+	/**
+	* Move back to the previous character.
+	*/
 	prev() {
 		this.charsIndex--;
 	}
+	/**
+	* Check whether the cursor has reached the end of source.
+	*/
 	isEof() {
 		return this.charsIndex >= this.charsList.length;
 	}
+	/**
+	* Get the current zero-based character index.
+	*/
 	index() {
 		return this.current().range[1] - 1;
 	}
@@ -2311,6 +2763,11 @@ function tokenizeChars(state) {
 	state.sourceCode.prev();
 	if (handler.handleContentEnd !== void 0) handler.handleContentEnd(state);
 }
+/**
+* Tokenize SVG source into parser tokens.
+* @param source - SVG source code
+* @returns Tokenizer state and emitted tokens
+*/
 function tokenize(source) {
 	const tokens = [];
 	const state = {
@@ -2331,48 +2788,29 @@ function tokenize(source) {
 }
 //#endregion
 //#region src/parser/parse.ts
+/**
+* Parse SVG source into a document AST and token list.
+* @param source - SVG source code
+* @param _options - Parser options reserved for API compatibility
+* @returns Direct parser result with document AST, tokens, and diagnostics
+*/
 function parse$1(source, _options = {}) {
 	const { tokens } = tokenize(source);
-	const { ast } = constructTree(tokens);
+	const { ast, errors, warnings } = constructTree(tokens);
 	return {
 		ast: clearParent(ast),
-		tokens
+		errors,
+		tokens,
+		warnings
 	};
 }
 //#endregion
-//#region src/visitorKeys.ts
-const keys = {
-	Program: ["document"],
-	Document: ["children"],
-	XMLDeclaration: ["attributes"],
-	XMLDeclarationAttribute: ["key", "value"],
-	XMLDeclarationAttributeKey: [],
-	XMLDeclarationAttributeValue: [],
-	Doctype: ["attributes"],
-	DoctypeAttribute: ["value"],
-	DoctypeAttributeValue: [],
-	Attribute: ["key", "value"],
-	AttributeKey: [],
-	AttributeValue: [],
-	Element: ["attributes", "children"],
-	Comment: [],
-	Text: [],
-	Error: []
-};
-let vistorKeysCache = null;
-function getVisitorKeys() {
-	if (!vistorKeysCache) {
-		const merged = unionWith(keys);
-		vistorKeysCache = {
-			...merged,
-			Tag: merged.Element
-		};
-	}
-	return vistorKeysCache;
-}
-const visitorKeys = getVisitorKeys();
-//#endregion
 //#region src/parser/traverse.ts
+/**
+* Walk an AST node tree using the parser visitor keys.
+* @param node - Root node to visit
+* @param visitor - Callback invoked for each reachable node
+*/
 function traverse(node, visitor) {
 	if (!node) return;
 	visitor(node);
@@ -2386,8 +2824,14 @@ function traverse(node, visitor) {
 }
 //#endregion
 //#region src/parser/parseForESLint.ts
+/**
+* Parse SVG source into an ESLint-compatible parser result.
+* @param source - SVG source code
+* @param options - Parser options forwarded to the base parser
+* @returns ESLint parser result with visitor keys, services, tokens, and comments
+*/
 function parseForESLint(source, options = {}) {
-	const { ast, tokens } = parse$1(source, options);
+	const { ast, errors, tokens, warnings } = parse$1(source, options);
 	const programNode = {
 		type: "Program",
 		body: [],
@@ -2411,15 +2855,31 @@ function parseForESLint(source, options = {}) {
 		ast: programNode,
 		visitorKeys,
 		scopeManager: null,
-		services: { isSVG: true }
+		services: {
+			errors,
+			isSVG: true,
+			warnings
+		}
 	};
 }
 //#endregion
 //#region src/index.ts
+/**
+* Parser package name.
+*/
 const name = meta.name;
+/**
+* ESLint visitor keys for parser-specific nodes.
+*/
 const VisitorKeys = visitorKeys;
+/**
+* Parse SVG source and return the document node directly.
+* @param code - SVG source code
+* @param options - Parser options
+* @returns Parsed SVG document node
+*/
 function parse(code, options = {}) {
 	return parseForESLint(code, options).ast.document;
 }
 //#endregion
-export { COMMENT_END, COMMENT_START, ConstructTreeContextTypes, DEPRECATED_SVG_ELEMENTS, NodeTypes, ParseError, RE_CLOSE_TAG_NAME, RE_INCOMPLETE_CLOSING_TAG, RE_OPEN_TAG_NAME, RE_OPEN_TAG_START, SELF_CLOSING_ELEMENTS, SPECIAL_CHAR, SVG_ELEMENTS, TokenTypes, TokenizerContextTypes, VisitorKeys, XML_DECLARATION_END, XML_DECLARATION_START, cloneNode, cloneNodeWithParent, countNodes, filterNodes, findFirstNodeByType, findNodeByType, getNodeDepth, getParentChain, isNodeType, mapNodes, meta, name, parse, parseForESLint, traverseAST, validateNode, walkAST };
+export { COMMENT_END, COMMENT_START, ConstructTreeContextTypes, DEPRECATED_SVG_ELEMENTS, NodeTypes, ParseError, ParseErrorType, RE_CLOSE_TAG_NAME, RE_INCOMPLETE_CLOSING_TAG, RE_OPEN_TAG_NAME, RE_OPEN_TAG_START, SELF_CLOSING_ELEMENTS, SPECIAL_CHAR, SVG_ELEMENTS, TokenTypes, TokenizerContextTypes, VisitorKeys, XML_DECLARATION_END, XML_DECLARATION_START, cloneNode, cloneNodeWithParent, countNodes, filterNodes, findFirstNodeByType, findNodeByType, getNodeDepth, getParentChain, isNodeType, mapNodes, meta, name, parse, parseForESLint, traverseAST, validateNode, walkAST };