@emasoft/svg-matrix 1.0.28 → 1.0.30

package/src/svg-parser.js

@@ -7,16 +7,39 @@
  * @module svg-parser
  */
 
-import Decimal from 'decimal.js';
+import Decimal from "decimal.js";
 
 Decimal.set({ precision: 80 });
 
+/**
+ * Recursively set ownerDocument on an element and all its descendants.
+ * @param {SVGElement} el - Element to set ownerDocument on
+ * @param {SVGDocument} doc - The document object
+ * @returns {void}
+ */
+function setOwnerDocument(el, doc) {
+  el.ownerDocument = doc;
+  for (const child of el.children) {
+    // eslint-disable-next-line no-use-before-define -- Class hoisting is intentional
+    if (child instanceof SVGElement) {
+      setOwnerDocument(child, doc);
+    }
+  }
+}
+
 /**
  * Parse an SVG string into a DOM-like element tree.
  * @param {string} svgString - Raw SVG content
  * @returns {SVGElement} Root element with DOM-like interface
  */
 export function parseSVG(svgString) {
+  if (typeof svgString !== 'string') {
+    throw new Error('parseSVG: input must be a string');
+  }
+  if (svgString.trim().length === 0) {
+    throw new Error('parseSVG: input cannot be empty');
+  }
+
   // Normalize whitespace but preserve content
   const normalized = svgString.trim();
 
@@ -24,25 +47,86 @@ export function parseSVG(svgString) {
   const root = parseElement(normalized, 0);
 
   if (!root.element) {
-    throw new Error('Failed to parse SVG: no root element found');
+    throw new Error("Failed to parse SVG: no root element found");
   }
 
+  // Create document and set ownerDocument on all elements
+  // eslint-disable-next-line no-use-before-define -- Class hoisting is intentional
+  const doc = new SVGDocument(root.element);
+  setOwnerDocument(root.element, doc);
+
   return root.element;
 }
 
+/**
+ * Simple document-like object that provides createElement functionality.
+ * Used by ownerDocument to allow element creation in DOM manipulation functions.
+ * @class
+ * @property {SVGElement|null} documentElement - Root SVG element of the document
+ */
+class SVGDocument {
+  /**
+   * Creates a new SVGDocument instance.
+   * @param {SVGElement|null} rootElement - The root element of the document
+   */
+  constructor(rootElement = null) {
+    this.documentElement = rootElement;
+  }
+
+  /**
+   * Create a new SVGElement with the given tag name.
+   * @param {string} tagName - Element tag name
+   * @returns {SVGElement}
+   */
+  createElement(tagName) {
+    // eslint-disable-next-line no-use-before-define -- Class hoisting is intentional
+    const el = new SVGElement(tagName);
+    el.ownerDocument = this;
+    return el;
+  }
+
+  /**
+   * Create a new SVGElement with namespace (for compatibility).
+   * @param {string} namespace - Namespace URI (ignored, always SVG)
+   * @param {string} tagName - Element tag name
+   * @returns {SVGElement}
+   */
+  createElementNS(namespace, tagName) {
+    return this.createElement(tagName);
+  }
+}
+
 /**
  * SVG Element class with DOM-like interface.
  * Provides getAttribute, querySelectorAll, children, etc.
+ * @class
+ * @property {string} tagName - Element tag name (preserves original case)
+ * @property {string} nodeName - Uppercase element tag name
+ * @property {Object} _attributes - Internal attributes storage
+ * @property {Array<SVGElement|string>} children - Child elements and text nodes
+ * @property {Array<SVGElement|string>} childNodes - Alias for children
+ * @property {string} textContent - Text content of the element
+ * @property {SVGElement|null} parentNode - Parent element reference
+ * @property {SVGDocument|null} ownerDocument - Document that owns this element
  */
 export class SVGElement {
-  constructor(tagName, attributes = {}, children = [], textContent = '') {
-    this.tagName = tagName.toLowerCase();
+  /**
+   * Creates a new SVGElement instance.
+   * @param {string} tagName - Element tag name
+   * @param {Object} attributes - Element attributes (key-value pairs)
+   * @param {Array<SVGElement|string>} children - Child elements and text nodes
+   * @param {string} textContent - Text content of the element
+   */
+  constructor(tagName, attributes = {}, children = [], textContent = "") {
+    // Preserve original case for W3C SVG compliance (linearGradient, clipPath, etc.)
+    this.tagName = tagName;
     this.nodeName = tagName.toUpperCase();
     this._attributes = { ...attributes };
     this.children = children;
     this.childNodes = children;
     this.textContent = textContent;
     this.parentNode = null;
+    this.ownerDocument = null; // Will be set by parseSVG or SVGDocument.createElement
 
     // Set parent references
     for (const child of children) {
@@ -107,7 +191,8 @@ export class SVGElement {
     const search = (el) => {
       for (const child of el.children) {
         if (child instanceof SVGElement) {
-          if (child.tagName === tag || tag === '*') {
+          // Case-insensitive tag matching (tagName preserves original case)
+          if (child.tagName.toLowerCase() === tag || tag === "*") {
             results.push(child);
           }
           search(child);
@@ -126,7 +211,7 @@ export class SVGElement {
    */
   getElementById(id) {
     const search = (el) => {
-      if (el.getAttribute('id') === id) {
+      if (el.getAttribute("id") === id) {
         return el;
       }
       for (const child of el.children) {
@@ -188,31 +273,59 @@ export class SVGElement {
 
   /**
    * Clone element (deep by default).
+   * DOM spec: Cloned nodes preserve ownerDocument from original.
    * @param {boolean} deep - Clone children too
    * @returns {SVGElement}
    */
   cloneNode(deep = true) {
     const clonedChildren = deep
-      ? this.children.map(c => c instanceof SVGElement ? c.cloneNode(true) : c)
+      ? // eslint-disable-next-line no-confusing-arrow -- Prettier multiline format
+        this.children.map((c) =>
+          c instanceof SVGElement ? c.cloneNode(true) : c,
+        )
       : [];
-    return new SVGElement(this.tagName, { ...this._attributes }, clonedChildren, this.textContent);
+    const cloned = new SVGElement(
+      this.tagName,
+      { ...this._attributes },
+      clonedChildren,
+      this.textContent,
+    );
+    // Preserve ownerDocument - set on cloned element and all its children
+    if (this.ownerDocument) {
+      const setDocRecursive = (el, doc) => {
+        el.ownerDocument = doc;
+        for (const child of el.children) {
+          if (child instanceof SVGElement) setDocRecursive(child, doc);
+        }
+      };
+      setDocRecursive(cloned, this.ownerDocument);
+    }
+    return cloned;
   }
 
   /**
    * Append child element.
+   * DOM spec: If child already has a parent, remove it first.
    * @param {SVGElement} child
+   * @returns {SVGElement} The appended child
    */
   appendChild(child) {
+    // DOM spec: Remove child from its current parent before appending
+    if (child instanceof SVGElement && child.parentNode) {
+      child.parentNode.removeChild(child);
+    }
     if (child instanceof SVGElement) {
       child.parentNode = this;
     }
     this.children.push(child);
     this.childNodes = this.children;
+    return child;
   }
 
   /**
    * Remove child element.
    * @param {SVGElement} child
+   * @returns {SVGElement} The removed child
    */
   removeChild(child) {
     const idx = this.children.indexOf(child);
@@ -223,14 +336,21 @@ export class SVGElement {
         child.parentNode = null;
       }
     }
+    return child;
   }
 
   /**
    * Insert child before reference node.
+   * DOM spec: Removes newChild from its current parent before inserting.
    * @param {SVGElement} newChild
    * @param {SVGElement} refChild
+   * @returns {SVGElement} The inserted child
    */
   insertBefore(newChild, refChild) {
+    // DOM spec: Remove newChild from its current parent first
+    if (newChild instanceof SVGElement && newChild.parentNode) {
+      newChild.parentNode.removeChild(newChild);
+    }
     const idx = this.children.indexOf(refChild);
     if (idx >= 0) {
       if (newChild instanceof SVGElement) {
@@ -241,14 +361,21 @@ export class SVGElement {
     } else {
       this.appendChild(newChild);
     }
+    return newChild;
   }
 
   /**
    * Replace child element.
+   * DOM spec: Removes newChild from its current parent before replacing.
    * @param {SVGElement} newChild
    * @param {SVGElement} oldChild
+   * @returns {SVGElement} The replaced (old) child
    */
   replaceChild(newChild, oldChild) {
+    // DOM spec: Remove newChild from its current parent first
+    if (newChild instanceof SVGElement && newChild.parentNode) {
+      newChild.parentNode.removeChild(newChild);
+    }
     const idx = this.children.indexOf(oldChild);
     if (idx >= 0) {
       if (oldChild instanceof SVGElement) {
@@ -260,6 +387,7 @@ export class SVGElement {
       this.children[idx] = newChild;
       this.childNodes = this.children;
     }
+    return oldChild;
   }
 
   /**
@@ -267,10 +395,10 @@ export class SVGElement {
    * @returns {Object}
    */
   get style() {
-    const styleAttr = this.getAttribute('style') || '';
+    const styleAttr = this.getAttribute("style") || "";
     const styles = {};
-    styleAttr.split(';').forEach(pair => {
-      const [key, val] = pair.split(':').map(s => s.trim());
+    styleAttr.split(";").forEach((pair) => {
+      const [key, val] = pair.split(":").map((s) => s.trim());
       if (key && val) {
         styles[key] = val;
       }
@@ -323,35 +451,57 @@ export class SVGElement {
    * @returns {string}
    */
   serialize(indent = 0, minify = false) {
-    const pad = minify ? '' : '  '.repeat(indent);
+    const pad = minify ? "" : "  ".repeat(indent);
+
+    // Check for CDATA pending marker (used by embedExternalDependencies for scripts)
+    const needsCDATA = this._attributes["data-cdata-pending"] === "true";
+
+    // Build attributes string, excluding internal marker attributes
     const attrs = Object.entries(this._attributes)
+      .filter(([k]) => k !== "data-cdata-pending") // Remove internal marker
       .map(([k, v]) => `${k}="${escapeAttr(v)}"`)
-      .join(' ');
+      .join(" ");
 
-    const attrStr = attrs ? ' ' + attrs : '';
+    const attrStr = attrs ? " " + attrs : "";
 
     // Self-closing tag for empty elements
     if (this.children.length === 0 && !this.textContent) {
       return `${pad}<${this.tagName}${attrStr}/>`;
     }
 
-    const separator = minify ? '' : '\n';
+    const separator = minify ? "" : "\n";
 
     // Serialize children (including animation elements inside text elements)
+    /* eslint-disable no-confusing-arrow -- Prettier multiline format */
     const childStr = this.children
-      .map(c => c instanceof SVGElement ? c.serialize(indent + 1, minify) : escapeText(c))
+      .map((c) =>
+        c instanceof SVGElement
+          ? c.serialize(indent + 1, minify)
+          : escapeText(c),
+      )
       .join(separator);
+    /* eslint-enable no-confusing-arrow */
 
     // CRITICAL FIX: Elements can have BOTH textContent AND children
     // Example: <text>Some text<set attributeName="display" .../></text>
     // We must include both, not choose one or the other
-    let content = '';
+    let content = "";
     if (this.textContent && this.children.length > 0) {
       // Both text and children - combine them
-      content = escapeText(this.textContent) + separator + childStr;
+      if (needsCDATA) {
+        // Wrap textContent in CDATA without escaping for script/style elements
+        content = `<![CDATA[\n${this.textContent}\n]]>` + separator + childStr;
+      } else {
+        content = escapeText(this.textContent) + separator + childStr;
+      }
     } else if (this.textContent) {
       // Only text content
-      content = escapeText(this.textContent);
+      if (needsCDATA) {
+        // Wrap in CDATA without escaping for script/style elements
+        content = `<![CDATA[\n${this.textContent}\n]]>`;
+      } else {
+        content = escapeText(this.textContent);
+      }
     } else {
       // Only children
       content = childStr;
@@ -378,8 +528,8 @@ export class SVGElement {
    */
   get innerHTML() {
     return this.children
-      .map(c => c instanceof SVGElement ? c.serialize(0) : escapeText(c))
-      .join('\n');
+      .map((c) => (c instanceof SVGElement ? c.serialize(0) : escapeText(c)))
+      .join("\n");
   }
 }
 
@@ -391,13 +541,15 @@ export class SVGElement {
  * Check if whitespace should be preserved based on xml:space attribute.
  * BUG FIX 2: Helper function to check xml:space="preserve" on element or ancestors
  * @private
+ * @param {SVGElement} element - Element to check for xml:space attribute
+ * @returns {boolean} True if whitespace should be preserved, false otherwise
  */
-function shouldPreserveWhitespace(element) {
+function _shouldPreserveWhitespace(element) {
   let current = element;
   while (current) {
-    const xmlSpace = current.getAttribute('xml:space');
-    if (xmlSpace === 'preserve') return true;
-    if (xmlSpace === 'default') return false;
+    const xmlSpace = current.getAttribute("xml:space");
+    if (xmlSpace === "preserve") return true;
+    if (xmlSpace === "default") return false;
     current = current.parentNode;
   }
   return false;
@@ -409,49 +561,53 @@ function shouldPreserveWhitespace(element) {
  * @param {string} str - SVG string to parse
  * @param {number} pos - Current position in string
  * @param {boolean} inheritPreserveSpace - Whether xml:space="preserve" is inherited from ancestor
+ * @returns {{element: SVGElement|null, endPos: number}} Parsed element and final position
  */
 function parseElement(str, pos, inheritPreserveSpace = false) {
+  // Use local variable to avoid reassigning parameter (ESLint no-param-reassign)
+  let position = pos;
+
   // Skip whitespace and comments
-  while (pos < str.length) {
-    const ws = str.slice(pos).match(/^(\s+)/);
+  while (position < str.length) {
+    const ws = str.slice(position).match(/^(\s+)/);
     if (ws) {
-      pos += ws[1].length;
+      position += ws[1].length;
       continue;
     }
 
     // Skip comments
-    if (str.slice(pos, pos + 4) === '<!--') {
-      const endComment = str.indexOf('-->', pos + 4);
+    if (str.slice(position, position + 4) === "<!--") {
+      const endComment = str.indexOf("-->", position + 4);
       if (endComment === -1) break;
-      pos = endComment + 3;
+      position = endComment + 3;
       continue;
     }
 
     // Skip CDATA
-    if (str.slice(pos, pos + 9) === '<![CDATA[') {
-      const endCdata = str.indexOf(']]>', pos + 9);
+    if (str.slice(position, position + 9) === "<![CDATA[") {
+      const endCdata = str.indexOf("]]>", position + 9);
       if (endCdata === -1) break;
-      pos = endCdata + 3;
+      position = endCdata + 3;
       continue;
     }
 
     // Skip processing instructions (<?xml ...?>)
-    if (str.slice(pos, pos + 2) === '<?') {
-      const endPI = str.indexOf('?>', pos + 2);
+    if (str.slice(position, position + 2) === "<?") {
+      const endPI = str.indexOf("?>", position + 2);
       if (endPI === -1) break;
-      pos = endPI + 2;
+      position = endPI + 2;
       continue;
     }
 
     // Skip DOCTYPE (can contain internal subset with brackets)
-    if (str.slice(pos, pos + 9).toUpperCase() === '<!DOCTYPE') {
+    if (str.slice(position, position + 9).toUpperCase() === "<!DOCTYPE") {
       let depth = 0;
-      let i = pos + 9;
+      let i = position + 9;
       while (i < str.length) {
-        if (str[i] === '[') depth++;
-        else if (str[i] === ']') depth--;
-        else if (str[i] === '>' && depth === 0) {
-          pos = i + 1;
+        if (str[i] === "[") depth++;
+        else if (str[i] === "]") depth--;
+        else if (str[i] === ">" && depth === 0) {
+          position = i + 1;
           break;
         }
         i++;
@@ -466,151 +622,169 @@ function parseElement(str, pos, inheritPreserveSpace = false) {
     break;
   }
 
-  if (pos >= str.length || str[pos] !== '<') {
-    return { element: null, endPos: pos };
+  if (position >= str.length || str[position] !== "<") {
+    return { element: null, endPos: position };
   }
 
   // Parse opening tag
-  const tagMatch = str.slice(pos).match(/^<([a-zA-Z][a-zA-Z0-9_:-]*)/);
+  const tagMatch = str.slice(position).match(/^<([a-zA-Z][a-zA-Z0-9_:-]*)/);
   if (!tagMatch) {
-    return { element: null, endPos: pos };
+    return { element: null, endPos: position };
   }
 
   const tagName = tagMatch[1];
-  pos += tagMatch[0].length;
+  position += tagMatch[0].length;
 
   // Parse attributes
   const attributes = {};
-  while (pos < str.length) {
+  while (position < str.length) {
     // Skip whitespace
-    const ws = str.slice(pos).match(/^(\s+)/);
+    const ws = str.slice(position).match(/^(\s+)/);
     if (ws) {
-      pos += ws[1].length;
+      position += ws[1].length;
     }
 
     // Check for end of tag
-    if (str[pos] === '>') {
-      pos++;
+    if (str[position] === ">") {
+      position++;
       break;
     }
 
-    if (str.slice(pos, pos + 2) === '/>') {
-      pos += 2;
+    if (str.slice(position, position + 2) === "/>") {
+      position += 2;
       // Self-closing tag
       return {
         element: new SVGElement(tagName, attributes, []),
-        endPos: pos
+        endPos: position,
       };
     }
 
     // Parse attribute
-    const attrMatch = str.slice(pos).match(/^([a-zA-Z][a-zA-Z0-9_:-]*)\s*=\s*(?:"([^"]*)"|'([^']*)')/);
+    const attrMatch = str
+      .slice(position)
+      .match(/^([a-zA-Z][a-zA-Z0-9_:-]*)\s*=\s*(?:"([^"]*)"|'([^']*)')/);
     if (attrMatch) {
       const attrName = attrMatch[1];
-      const attrValue = attrMatch[2] !== undefined ? attrMatch[2] : attrMatch[3];
+      const attrValue =
+        attrMatch[2] !== undefined ? attrMatch[2] : attrMatch[3];
       attributes[attrName] = unescapeAttr(attrValue);
-      pos += attrMatch[0].length;
+      position += attrMatch[0].length;
     } else {
       // Boolean attribute or malformed - skip
-      const boolAttr = str.slice(pos).match(/^([a-zA-Z][a-zA-Z0-9_:-]*)/);
+      const boolAttr = str.slice(position).match(/^([a-zA-Z][a-zA-Z0-9_:-]*)/);
       if (boolAttr) {
-        attributes[boolAttr[1]] = '';
-        pos += boolAttr[0].length;
+        attributes[boolAttr[1]] = "";
+        position += boolAttr[0].length;
       } else {
-        pos++;
+        position++;
       }
     }
   }
 
   // Parse children
   const children = [];
-  let textContent = '';
+  let textContent = "";
   const closingTag = `</${tagName}>`;
 
-  while (pos < str.length) {
+  while (position < str.length) {
     // Check for closing tag
-    if (str.slice(pos, pos + closingTag.length).toLowerCase() === closingTag.toLowerCase()) {
-      pos += closingTag.length;
+    if (
+      str.slice(position, position + closingTag.length).toLowerCase() ===
+      closingTag.toLowerCase()
+    ) {
+      position += closingTag.length;
       break;
     }
 
     // Check for child element
-    if (str[pos] === '<' && str[pos + 1] !== '/') {
+    if (str[position] === "<" && str[position + 1] !== "/") {
       // Check for CDATA
-      if (str.slice(pos, pos + 9) === '<![CDATA[') {
-        const endCdata = str.indexOf(']]>', pos + 9);
+      if (str.slice(position, position + 9) === "<![CDATA[") {
+        const endCdata = str.indexOf("]]>", position + 9);
         if (endCdata !== -1) {
-          textContent += str.slice(pos + 9, endCdata);
-          pos = endCdata + 3;
+          textContent += str.slice(position + 9, endCdata);
+          position = endCdata + 3;
           continue;
         }
       }
 
       // Check for comment
-      if (str.slice(pos, pos + 4) === '<!--') {
-        const endComment = str.indexOf('-->', pos + 4);
+      if (str.slice(position, position + 4) === "<!--") {
+        const endComment = str.indexOf("-->", position + 4);
         if (endComment !== -1) {
-          pos = endComment + 3;
+          position = endComment + 3;
           continue;
         }
       }
 
       // BUG FIX 1: Pass down xml:space inheritance to children
       // Determine what to pass: if current element has xml:space, use it; otherwise inherit
-      const currentXmlSpace = attributes['xml:space'];
-      const childInheritPreserve = currentXmlSpace === 'preserve' ? true :
-                                   currentXmlSpace === 'default' ? false :
-                                   inheritPreserveSpace;
-
-      const child = parseElement(str, pos, childInheritPreserve);
+      const currentXmlSpace = attributes["xml:space"];
+      const childInheritPreserve =
+        currentXmlSpace === "preserve"
+          ? true
+          : currentXmlSpace === "default"
+            ? false
+            : inheritPreserveSpace;
+
+      const child = parseElement(str, position, childInheritPreserve);
       if (child.element) {
         children.push(child.element);
-        pos = child.endPos;
+        position = child.endPos;
       } else {
-        pos++;
+        position++;
       }
-    } else if (str[pos] === '<' && str[pos + 1] === '/') {
+    } else if (str[position] === "<" && str[position + 1] === "/") {
       // Closing tag for this element
-      const closeMatch = str.slice(pos).match(/^<\/([a-zA-Z][a-zA-Z0-9_:-]*)>/);
+      const closeMatch = str
+        .slice(position)
+        .match(/^<\/([a-zA-Z][a-zA-Z0-9_:-]*)>/);
       if (closeMatch && closeMatch[1].toLowerCase() === tagName.toLowerCase()) {
-        pos += closeMatch[0].length;
+        position += closeMatch[0].length;
         break;
       }
-      pos++;
+      position++;
     } else {
       // Text content
-      const nextTag = str.indexOf('<', pos);
+      const nextTag = str.indexOf("<", position);
       if (nextTag === -1) {
-        textContent += str.slice(pos);
-        pos = str.length;
+        textContent += str.slice(position);
+        position = str.length;
       } else {
-        textContent += str.slice(pos, nextTag);
-        pos = nextTag;
+        textContent += str.slice(position, nextTag);
+        position = nextTag;
       }
     }
   }
 
   // BUG FIX 1: Create element first to set up parent references
-  const element = new SVGElement(tagName, attributes, children, '');
+  const element = new SVGElement(tagName, attributes, children, "");
 
   // BUG FIX 1: Check xml:space on this element, otherwise use inherited value
   // xml:space="preserve" means preserve whitespace
   // xml:space="default" means collapse/trim whitespace
   // If not specified, inherit from ancestor
-  const currentXmlSpace = attributes['xml:space'];
-  const preserveWhitespace = currentXmlSpace === 'preserve' ? true :
-                             currentXmlSpace === 'default' ? false :
-                             inheritPreserveSpace;
-
-  const processedText = preserveWhitespace ? unescapeText(textContent) : unescapeText(textContent.trim());
+  const currentXmlSpace = attributes["xml:space"];
+  const preserveWhitespace =
+    currentXmlSpace === "preserve"
+      ? true
+      : currentXmlSpace === "default"
+        ? false
+        : inheritPreserveSpace;
+
+  const processedText = preserveWhitespace
+    ? unescapeText(textContent)
+    : unescapeText(textContent.trim());
   element.textContent = processedText;
 
-  return { element, endPos: pos };
+  return { element, endPos: position };
 }
 
 /**
  * Parse CSS-like selector into matchers.
  * @private
+ * @param {string} selector - CSS-like selector string
+ * @returns {Array<{tag: string|null, id: string|null, classes: Array<string>, attrs: Array<{name: string, value: string|undefined}>}>} Array of matcher objects
  */
 function parseSelector(selector) {
   const matchers = [];
@@ -633,7 +807,7 @@ function parseSelector(selector) {
     const idMatch = remaining.match(/#([a-zA-Z][a-zA-Z0-9_-]*)/);
     if (idMatch) {
       matcher.id = idMatch[1];
-      remaining = remaining.replace(idMatch[0], '');
+      remaining = remaining.replace(idMatch[0], "");
     }
 
     // Classes
@@ -643,7 +817,9 @@ function parseSelector(selector) {
     }
 
     // Attributes [attr] or [attr=value]
-    const attrMatches = remaining.matchAll(/\[([a-zA-Z][a-zA-Z0-9_:-]*)(?:=["']?([^"'\]]+)["']?)?\]/g);
+    const attrMatches = remaining.matchAll(
+      /\[([a-zA-Z][a-zA-Z0-9_:-]*)(?:=["']?([^"'\]]+)["']?)?\]/g,
+    );
     for (const m of attrMatches) {
       matcher.attrs.push({ name: m[1], value: m[2] });
     }
@@ -657,20 +833,25 @@ function parseSelector(selector) {
 /**
  * Check if element matches all selector matchers.
  * @private
+ * @param {SVGElement} el - Element to check
+ * @param {Array<{tag: string|null, id: string|null, classes: Array<string>, attrs: Array<{name: string, value: string|undefined}>}>} matchers - Array of matcher objects
+ * @returns {boolean} True if element matches any matcher
  */
 function matchesAllSelectors(el, matchers) {
-  return matchers.some(matcher => {
-    if (matcher.tag && el.tagName !== matcher.tag) return false;
-    if (matcher.id && el.getAttribute('id') !== matcher.id) return false;
+  return matchers.some((matcher) => {
+    // Case-insensitive tag matching (tagName preserves original case)
+    if (matcher.tag && el.tagName.toLowerCase() !== matcher.tag) return false;
+    if (matcher.id && el.getAttribute("id") !== matcher.id) return false;
 
-    const elClasses = (el.getAttribute('class') || '').split(/\s+/);
+    const elClasses = (el.getAttribute("class") || "").split(/\s+/);
     for (const cls of matcher.classes) {
       if (!elClasses.includes(cls)) return false;
     }
 
     for (const attr of matcher.attrs) {
       if (!el.hasAttribute(attr.name)) return false;
-      if (attr.value !== undefined && el.getAttribute(attr.name) !== attr.value) return false;
+      if (attr.value !== undefined && el.getAttribute(attr.name) !== attr.value)
+        return false;
     }
 
     return true;
@@ -680,124 +861,159 @@ function matchesAllSelectors(el, matchers) {
 /**
  * Escape text content for XML.
  * @private
+ * @param {string|undefined|null} str - Text to escape
+ * @returns {string} Escaped text
  */
 function escapeText(str) {
-  if (typeof str !== 'string') return String(str);
-  return str
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;');
+  // Filter out undefined/null values to prevent "undefined" string in output
+  if (str === undefined || str === null) return "";
+  if (typeof str !== "string") return String(str);
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 
 /**
  * Escape attribute value for XML.
  * @private
+ * @param {string} str - Attribute value to escape
+ * @returns {string} Escaped attribute value
  */
 function escapeAttr(str) {
-  if (typeof str !== 'string') return String(str);
+  if (typeof str !== "string") return String(str);
   return str
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&#39;');
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
 }
 
 /**
  * Unescape attribute value from XML.
  * Handles numeric entities (decimal and hex) and named entities.
  * @private
+ * @param {string} str - Attribute value to unescape
+ * @returns {string} Unescaped attribute value
  */
 function unescapeAttr(str) {
   if (!str) return str;
-  return str
-    // Decode hex entities first: &#x41; or &#X41; -> A (case-insensitive)
-    // BUG FIX 1 & 4: Use fromCodePoint for surrogate pairs, validate code point range
-    .replace(/&#[xX]([0-9A-Fa-f]+);/g, (match, hex) => {
-      const codePoint = parseInt(hex, 16);
-      // BUG FIX 2: Validate XML-invalid characters (NULL and control characters)
-      const isXMLInvalid = codePoint === 0 ||
-        (codePoint >= 0x1 && codePoint <= 0x8) ||
-        (codePoint >= 0xB && codePoint <= 0xC) ||
-        (codePoint >= 0xE && codePoint <= 0x1F) ||
-        codePoint === 0xFFFE || codePoint === 0xFFFF;
-      // BUG FIX 4: Validate code point range (0x0 to 0x10FFFF, excluding surrogates)
-      if (isXMLInvalid || codePoint > 0x10FFFF || (codePoint >= 0xD800 && codePoint <= 0xDFFF)) {
-        return '\uFFFD'; // Replacement character for invalid code points
-      }
-      return String.fromCodePoint(codePoint);
-    })
-    // Decode decimal entities: &#65; -> A
-    // BUG FIX 1 & 4: Use fromCodePoint for surrogate pairs, validate code point range
-    .replace(/&#(\d+);/g, (match, dec) => {
-      const codePoint = parseInt(dec, 10);
-      // BUG FIX 2: Validate XML-invalid characters (NULL and control characters)
-      const isXMLInvalid = codePoint === 0 ||
-        (codePoint >= 0x1 && codePoint <= 0x8) ||
-        (codePoint >= 0xB && codePoint <= 0xC) ||
-        (codePoint >= 0xE && codePoint <= 0x1F) ||
-        codePoint === 0xFFFE || codePoint === 0xFFFF;
-      // BUG FIX 4: Validate code point range (0x0 to 0x10FFFF, excluding surrogates)
-      if (isXMLInvalid || codePoint > 0x10FFFF || (codePoint >= 0xD800 && codePoint <= 0xDFFF)) {
-        return '\uFFFD'; // Replacement character for invalid code points
-      }
-      return String.fromCodePoint(codePoint);
-    })
-    // Then named entities (order matters - & last to avoid double-decoding)
-    .replace(/&quot;/g, '"')
-    .replace(/&#39;/g, "'")
-    .replace(/&apos;/g, "'")
-    .replace(/&nbsp;/g, '\u00A0')  // BUG FIX 3: Add support for non-breaking space entity
-    .replace(/&lt;/g, '<')
-    .replace(/&gt;/g, '>')
-    .replace(/&amp;/g, '&');
+  return (
+    str
+      // Decode hex entities first: &#x41; or &#X41; -> A (case-insensitive)
+      // BUG FIX 1 & 4: Use fromCodePoint for surrogate pairs, validate code point range
+      .replace(/&#[xX]([0-9A-Fa-f]+);/g, (match, hex) => {
+        const codePoint = parseInt(hex, 16);
+        // BUG FIX 2: Validate XML-invalid characters (NULL and control characters)
+        const isXMLInvalid =
+          codePoint === 0 ||
+          (codePoint >= 0x1 && codePoint <= 0x8) ||
+          (codePoint >= 0xb && codePoint <= 0xc) ||
+          (codePoint >= 0xe && codePoint <= 0x1f) ||
+          codePoint === 0xfffe ||
+          codePoint === 0xffff;
+        // BUG FIX 4: Validate code point range (0x0 to 0x10FFFF, excluding surrogates)
+        if (
+          isXMLInvalid ||
+          codePoint > 0x10ffff ||
+          (codePoint >= 0xd800 && codePoint <= 0xdfff)
+        ) {
+          return "\uFFFD"; // Replacement character for invalid code points
+        }
+        return String.fromCodePoint(codePoint);
+      })
+      // Decode decimal entities: &#65; -> A
+      // BUG FIX 1 & 4: Use fromCodePoint for surrogate pairs, validate code point range
+      .replace(/&#(\d+);/g, (match, dec) => {
+        const codePoint = parseInt(dec, 10);
+        // BUG FIX 2: Validate XML-invalid characters (NULL and control characters)
+        const isXMLInvalid =
+          codePoint === 0 ||
+          (codePoint >= 0x1 && codePoint <= 0x8) ||
+          (codePoint >= 0xb && codePoint <= 0xc) ||
+          (codePoint >= 0xe && codePoint <= 0x1f) ||
+          codePoint === 0xfffe ||
+          codePoint === 0xffff;
+        // BUG FIX 4: Validate code point range (0x0 to 0x10FFFF, excluding surrogates)
+        if (
+          isXMLInvalid ||
+          codePoint > 0x10ffff ||
+          (codePoint >= 0xd800 && codePoint <= 0xdfff)
+        ) {
+          return "\uFFFD"; // Replacement character for invalid code points
+        }
+        return String.fromCodePoint(codePoint);
+      })
+      // Then named entities (order matters - & last to avoid double-decoding)
+      .replace(/&quot;/g, '"')
+      .replace(/&#39;/g, "'")
+      .replace(/&apos;/g, "'")
+      .replace(/&nbsp;/g, "\u00A0") // BUG FIX 3: Add support for non-breaking space entity
+      .replace(/&lt;/g, "<")
+      .replace(/&gt;/g, ">")
+      .replace(/&amp;/g, "&")
+  );
 }
 
 /**
  * Unescape text content from XML.
  * Handles numeric entities (decimal and hex) and named entities.
  * @private
+ * @param {string} str - Text content to unescape
+ * @returns {string} Unescaped text content
  */
 function unescapeText(str) {
   if (!str) return str;
-  return str
-    // Decode hex entities: &#x41; or &#X41; -> A (case-insensitive)
-    // BUG FIX 1 & 4: Use fromCodePoint for surrogate pairs, validate code point range
-    .replace(/&#[xX]([0-9A-Fa-f]+);/g, (match, hex) => {
-      const codePoint = parseInt(hex, 16);
-      // BUG FIX 2: Validate XML-invalid characters (NULL and control characters)
-      const isXMLInvalid = codePoint === 0 ||
-        (codePoint >= 0x1 && codePoint <= 0x8) ||
-        (codePoint >= 0xB && codePoint <= 0xC) ||
-        (codePoint >= 0xE && codePoint <= 0x1F) ||
-        codePoint === 0xFFFE || codePoint === 0xFFFF;
-      // BUG FIX 4: Validate code point range (0x0 to 0x10FFFF, excluding surrogates)
-      if (isXMLInvalid || codePoint > 0x10FFFF || (codePoint >= 0xD800 && codePoint <= 0xDFFF)) {
-        return '\uFFFD'; // Replacement character for invalid code points
-      }
-      return String.fromCodePoint(codePoint);
-    })
-    // Decode decimal entities: &#65; -> A
-    // BUG FIX 1 & 4: Use fromCodePoint for surrogate pairs, validate code point range
-    .replace(/&#(\d+);/g, (match, dec) => {
-      const codePoint = parseInt(dec, 10);
-      // BUG FIX 2: Validate XML-invalid characters (NULL and control characters)
-      const isXMLInvalid = codePoint === 0 ||
-        (codePoint >= 0x1 && codePoint <= 0x8) ||
-        (codePoint >= 0xB && codePoint <= 0xC) ||
-        (codePoint >= 0xE && codePoint <= 0x1F) ||
-        codePoint === 0xFFFE || codePoint === 0xFFFF;
-      // BUG FIX 4: Validate code point range (0x0 to 0x10FFFF, excluding surrogates)
-      if (isXMLInvalid || codePoint > 0x10FFFF || (codePoint >= 0xD800 && codePoint <= 0xDFFF)) {
-        return '\uFFFD'; // Replacement character for invalid code points
-      }
-      return String.fromCodePoint(codePoint);
-    })
-    // Named entities (& last)
-    .replace(/&nbsp;/g, '\u00A0')  // BUG FIX 3: Add support for non-breaking space entity
-    .replace(/&lt;/g, '<')
-    .replace(/&gt;/g, '>')
-    .replace(/&amp;/g, '&');
+  return (
+    str
+      // Decode hex entities: &#x41; or &#X41; -> A (case-insensitive)
+      // BUG FIX 1 & 4: Use fromCodePoint for surrogate pairs, validate code point range
+      .replace(/&#[xX]([0-9A-Fa-f]+);/g, (match, hex) => {
+        const codePoint = parseInt(hex, 16);
+        // BUG FIX 2: Validate XML-invalid characters (NULL and control characters)
+        const isXMLInvalid =
+          codePoint === 0 ||
+          (codePoint >= 0x1 && codePoint <= 0x8) ||
+          (codePoint >= 0xb && codePoint <= 0xc) ||
+          (codePoint >= 0xe && codePoint <= 0x1f) ||
+          codePoint === 0xfffe ||
+          codePoint === 0xffff;
+        // BUG FIX 4: Validate code point range (0x0 to 0x10FFFF, excluding surrogates)
+        if (
+          isXMLInvalid ||
+          codePoint > 0x10ffff ||
+          (codePoint >= 0xd800 && codePoint <= 0xdfff)
+        ) {
+          return "\uFFFD"; // Replacement character for invalid code points
+        }
+        return String.fromCodePoint(codePoint);
+      })
+      // Decode decimal entities: &#65; -> A
+      // BUG FIX 1 & 4: Use fromCodePoint for surrogate pairs, validate code point range
+      .replace(/&#(\d+);/g, (match, dec) => {
+        const codePoint = parseInt(dec, 10);
+        // BUG FIX 2: Validate XML-invalid characters (NULL and control characters)
+        const isXMLInvalid =
+          codePoint === 0 ||
+          (codePoint >= 0x1 && codePoint <= 0x8) ||
+          (codePoint >= 0xb && codePoint <= 0xc) ||
+          (codePoint >= 0xe && codePoint <= 0x1f) ||
+          codePoint === 0xfffe ||
+          codePoint === 0xffff;
+        // BUG FIX 4: Validate code point range (0x0 to 0x10FFFF, excluding surrogates)
+        if (
+          isXMLInvalid ||
+          codePoint > 0x10ffff ||
+          (codePoint >= 0xd800 && codePoint <= 0xdfff)
+        ) {
+          return "\uFFFD"; // Replacement character for invalid code points
+        }
+        return String.fromCodePoint(codePoint);
+      })
+      // Named entities (& last)
+      .replace(/&nbsp;/g, "\u00A0") // BUG FIX 3: Add support for non-breaking space entity
+      .replace(/&lt;/g, "<")
+      .replace(/&gt;/g, ">")
+      .replace(/&amp;/g, "&")
+  );
 }
 
 // ============================================================================
@@ -815,7 +1031,7 @@ export function buildDefsMap(svgRoot) {
 
   // Find all elements with IDs
   const addToMap = (el) => {
-    const id = el.getAttribute('id');
+    const id = el.getAttribute("id");
     if (id) {
       defsMap.set(id, el);
     }
@@ -873,9 +1089,20 @@ export function parseUrlReference(urlValue) {
  * @returns {string}
  */
 export function serializeSVG(root, options = {}) {
+  if (!root) {
+    throw new Error('serializeSVG: document is required');
+  }
+  // Validate that root is a proper SVGElement with serialize method
+  if (typeof root.serialize !== "function") {
+    // If root is already a string, return it directly
+    if (typeof root === "string") return root;
+    throw new Error(
+      `serializeSVG: expected SVGElement with serialize method, got ${root?.constructor?.name || typeof root}`,
+    );
+  }
   const minify = options.minify || false;
   const xmlDecl = '<?xml version="1.0" encoding="UTF-8"?>';
-  const separator = minify ? '' : '\n';
+  const separator = minify ? "" : "\n";
   return xmlDecl + separator + root.serialize(0, minify);
 }
 
@@ -885,5 +1112,5 @@ export default {
   buildDefsMap,
   findElementsWithAttribute,
   parseUrlReference,
-  serializeSVG
+  serializeSVG,
 };