@emasoft/svg-matrix 1.0.27 → 1.0.29

package/src/geometry-to-path.js

@@ -1,12 +1,13 @@
-import Decimal from 'decimal.js';
-import { Matrix } from './matrix.js';
+import Decimal from "decimal.js";
+import { Matrix } from "./matrix.js";
 
-const D = x => (x instanceof Decimal ? x : new Decimal(x));
+const D = (x) => (x instanceof Decimal ? x : new Decimal(x));
 
 /**
  * Standard kappa for 90° arcs (4 Bezier curves per circle).
  * kappa = 4/3 * (sqrt(2) - 1) ≈ 0.5522847498
  * Maximum radial error: ~0.027%
+ * @returns {Decimal} The kappa constant for 90-degree arc approximation
  */
 export function getKappa() {
   const two = new Decimal(2);
@@ -90,16 +91,20 @@ export function circleToPathDataHP(cx, cy, r, arcs = 8, precision = 6) {
  */
 export function ellipseToPathDataHP(cx, cy, rx, ry, arcs = 8, precision = 6) {
   // Enforce multiple of 4 for symmetry
-  if (arcs % 4 !== 0) {
-    arcs = Math.ceil(arcs / 4) * 4;
+  let numArcs = arcs;
+  if (numArcs % 4 !== 0) {
+    numArcs = Math.ceil(numArcs / 4) * 4;
   }
-  const cxD = D(cx), cyD = D(cy), rxD = D(rx), ryD = D(ry);
-  const f = v => formatNumber(v, precision);
+  const cxD = D(cx),
+    cyD = D(cy),
+    rxD = D(rx),
+    ryD = D(ry);
+  const f = (v) => formatNumber(v, precision);
 
   // Angle per arc in radians
   const PI = Decimal.acos(-1);
   const TWO_PI = PI.mul(2);
-  const arcAngle = TWO_PI.div(arcs);
+  const arcAngle = TWO_PI.div(numArcs);
 
   // Control point distance for this arc angle
   const kappa = getKappaForArc(arcAngle);
@@ -107,7 +112,7 @@ export function ellipseToPathDataHP(cx, cy, rx, ry, arcs = 8, precision = 6) {
   // Generate path
   const commands = [];
 
-  for (let i = 0; i < arcs; i++) {
+  for (let i = 0; i < numArcs; i++) {
     const startAngle = arcAngle.mul(i);
     const endAngle = arcAngle.mul(i + 1);
 
@@ -126,10 +131,10 @@ export function ellipseToPathDataHP(cx, cy, rx, ry, arcs = 8, precision = 6) {
     // Tangent at angle θ: (-sin(θ), cos(θ))
     // Control point 1: start + kappa * tangent_at_start * radius
     // Control point 2: end - kappa * tangent_at_end * radius
-    const tx0 = sinStart.neg();  // tangent x at start
-    const ty0 = cosStart;        // tangent y at start
-    const tx3 = sinEnd.neg();    // tangent x at end
-    const ty3 = cosEnd;          // tangent y at end
+    const tx0 = sinStart.neg(); // tangent x at start
+    const ty0 = cosStart; // tangent y at start
+    const tx3 = sinEnd.neg(); // tangent x at end
+    const ty3 = cosEnd; // tangent y at end
 
     const x1 = x0.plus(kappa.mul(rxD).mul(tx0));
     const y1 = y0.plus(kappa.mul(ryD).mul(ty0));
@@ -142,77 +147,212 @@ export function ellipseToPathDataHP(cx, cy, rx, ry, arcs = 8, precision = 6) {
     commands.push(`C${f(x1)} ${f(y1)} ${f(x2)} ${f(y2)} ${f(x3)} ${f(y3)}`);
   }
 
-  commands.push('Z');
-  return commands.join(' ');
+  commands.push("Z");
+  return commands.join(" ");
 }
 
+/**
+ * Format a number with specified precision, removing trailing zeros.
+ * @param {number|Decimal} value - Value to format
+ * @param {number} precision - Number of decimal places
+ * @returns {string} Formatted number string
+ */
 function formatNumber(value, precision = 6) {
   // Format with precision then remove trailing zeros for smaller output
   let str = value.toFixed(precision);
   // Remove trailing zeros after decimal point
-  if (str.includes('.')) {
-    str = str.replace(/\.?0+$/, '');
+  if (str.includes(".")) {
+    str = str.replace(/\.?0+$/, "");
   }
   return str;
 }
 
+/**
+ * Convert a circle to SVG path data using 4 Bezier arcs (standard kappa).
+ * @param {number|Decimal} cx - Center X coordinate
+ * @param {number|Decimal} cy - Center Y coordinate
+ * @param {number|Decimal} r - Radius
+ * @param {number} precision - Decimal precision for output coordinates
+ * @returns {string} SVG path data string
+ */
 export function circleToPathData(cx, cy, r, precision = 6) {
-  const cxD = D(cx), cyD = D(cy), rD = D(r);
+  const cxD = D(cx),
+    cyD = D(cy),
+    rD = D(r);
   const k = getKappa().mul(rD);
-  const x0 = cxD.plus(rD), y0 = cyD;
-  const c1x1 = x0, c1y1 = y0.minus(k), c1x2 = cxD.plus(k), c1y2 = cyD.minus(rD), x1 = cxD, y1 = cyD.minus(rD);
-  const c2x1 = cxD.minus(k), c2y1 = y1, c2x2 = cxD.minus(rD), c2y2 = cyD.minus(k), x2 = cxD.minus(rD), y2 = cyD;
-  const c3x1 = x2, c3y1 = cyD.plus(k), c3x2 = cxD.minus(k), c3y2 = cyD.plus(rD), x3 = cxD, y3 = cyD.plus(rD);
-  const c4x1 = cxD.plus(k), c4y1 = y3, c4x2 = x0, c4y2 = cyD.plus(k);
-  const f = v => formatNumber(v, precision);
+  const x0 = cxD.plus(rD),
+    y0 = cyD;
+  const c1x1 = x0,
+    c1y1 = y0.minus(k),
+    c1x2 = cxD.plus(k),
+    c1y2 = cyD.minus(rD),
+    x1 = cxD,
+    y1 = cyD.minus(rD);
+  const c2x1 = cxD.minus(k),
+    c2y1 = y1,
+    c2x2 = cxD.minus(rD),
+    c2y2 = cyD.minus(k),
+    x2 = cxD.minus(rD),
+    y2 = cyD;
+  const c3x1 = x2,
+    c3y1 = cyD.plus(k),
+    c3x2 = cxD.minus(k),
+    c3y2 = cyD.plus(rD),
+    x3 = cxD,
+    y3 = cyD.plus(rD);
+  const c4x1 = cxD.plus(k),
+    c4y1 = y3,
+    c4x2 = x0,
+    c4y2 = cyD.plus(k);
+  const f = (v) => formatNumber(v, precision);
   return `M${f(x0)} ${f(y0)}C${f(c1x1)} ${f(c1y1)} ${f(c1x2)} ${f(c1y2)} ${f(x1)} ${f(y1)}C${f(c2x1)} ${f(c2y1)} ${f(c2x2)} ${f(c2y2)} ${f(x2)} ${f(y2)}C${f(c3x1)} ${f(c3y1)} ${f(c3x2)} ${f(c3y2)} ${f(x3)} ${f(y3)}C${f(c4x1)} ${f(c4y1)} ${f(c4x2)} ${f(c4y2)} ${f(x0)} ${f(y0)}Z`;
 }
 
+/**
+ * Convert an ellipse to SVG path data using 4 Bezier arcs (standard kappa).
+ * @param {number|Decimal} cx - Center X coordinate
+ * @param {number|Decimal} cy - Center Y coordinate
+ * @param {number|Decimal} rx - X radius
+ * @param {number|Decimal} ry - Y radius
+ * @param {number} precision - Decimal precision for output coordinates
+ * @returns {string} SVG path data string
+ */
 export function ellipseToPathData(cx, cy, rx, ry, precision = 6) {
-  const cxD = D(cx), cyD = D(cy), rxD = D(rx), ryD = D(ry);
-  const kappa = getKappa(), kx = kappa.mul(rxD), ky = kappa.mul(ryD);
-  const x0 = cxD.plus(rxD), y0 = cyD;
-  const c1x1 = x0, c1y1 = y0.minus(ky), c1x2 = cxD.plus(kx), c1y2 = cyD.minus(ryD), x1 = cxD, y1 = cyD.minus(ryD);
-  const c2x1 = cxD.minus(kx), c2y1 = y1, c2x2 = cxD.minus(rxD), c2y2 = cyD.minus(ky), x2 = cxD.minus(rxD), y2 = cyD;
-  const c3x1 = x2, c3y1 = cyD.plus(ky), c3x2 = cxD.minus(kx), c3y2 = cyD.plus(ryD), x3 = cxD, y3 = cyD.plus(ryD);
-  const c4x1 = cxD.plus(kx), c4y1 = y3, c4x2 = x0, c4y2 = cyD.plus(ky);
-  const f = v => formatNumber(v, precision);
+  const cxD = D(cx),
+    cyD = D(cy),
+    rxD = D(rx),
+    ryD = D(ry);
+  const kappa = getKappa(),
+    kx = kappa.mul(rxD),
+    ky = kappa.mul(ryD);
+  const x0 = cxD.plus(rxD),
+    y0 = cyD;
+  const c1x1 = x0,
+    c1y1 = y0.minus(ky),
+    c1x2 = cxD.plus(kx),
+    c1y2 = cyD.minus(ryD),
+    x1 = cxD,
+    y1 = cyD.minus(ryD);
+  const c2x1 = cxD.minus(kx),
+    c2y1 = y1,
+    c2x2 = cxD.minus(rxD),
+    c2y2 = cyD.minus(ky),
+    x2 = cxD.minus(rxD),
+    y2 = cyD;
+  const c3x1 = x2,
+    c3y1 = cyD.plus(ky),
+    c3x2 = cxD.minus(kx),
+    c3y2 = cyD.plus(ryD),
+    x3 = cxD,
+    y3 = cyD.plus(ryD);
+  const c4x1 = cxD.plus(kx),
+    c4y1 = y3,
+    c4x2 = x0,
+    c4y2 = cyD.plus(ky);
+  const f = (v) => formatNumber(v, precision);
   return `M${f(x0)} ${f(y0)}C${f(c1x1)} ${f(c1y1)} ${f(c1x2)} ${f(c1y2)} ${f(x1)} ${f(y1)}C${f(c2x1)} ${f(c2y1)} ${f(c2x2)} ${f(c2y2)} ${f(x2)} ${f(y2)}C${f(c3x1)} ${f(c3y1)} ${f(c3x2)} ${f(c3y2)} ${f(x3)} ${f(y3)}C${f(c4x1)} ${f(c4y1)} ${f(c4x2)} ${f(c4y2)} ${f(x0)} ${f(y0)}Z`;
 }
 
-export function rectToPathData(x, y, width, height, rx = 0, ry = null, useArcs = false, precision = 6) {
-  const xD = D(x), yD = D(y), wD = D(width), hD = D(height);
-  let rxD = D(rx || 0), ryD = ry !== null ? D(ry) : rxD;
-  const halfW = wD.div(2), halfH = hD.div(2);
+/**
+ * Convert a rectangle to SVG path data, with optional rounded corners.
+ * @param {number|Decimal} x - Top-left X coordinate
+ * @param {number|Decimal} y - Top-left Y coordinate
+ * @param {number|Decimal} width - Rectangle width
+ * @param {number|Decimal} height - Rectangle height
+ * @param {number|Decimal} rx - X-axis corner radius (default 0)
+ * @param {number|Decimal|null} ry - Y-axis corner radius (defaults to rx if null)
+ * @param {boolean} useArcs - Use arc commands instead of Bezier curves for corners
+ * @param {number} precision - Decimal precision for output coordinates
+ * @returns {string} SVG path data string
+ */
+export function rectToPathData(
+  x,
+  y,
+  width,
+  height,
+  rx = 0,
+  ry = null,
+  useArcs = false,
+  precision = 6,
+) {
+  const xD = D(x),
+    yD = D(y),
+    wD = D(width),
+    hD = D(height);
+  let rxD = D(rx || 0),
+    ryD = ry !== null ? D(ry) : rxD;
+  const halfW = wD.div(2),
+    halfH = hD.div(2);
   if (rxD.gt(halfW)) rxD = halfW;
   if (ryD.gt(halfH)) ryD = halfH;
-  const f = v => formatNumber(v, precision);
+  const f = (v) => formatNumber(v, precision);
   if (rxD.isZero() || ryD.isZero()) {
-    const x1 = xD.plus(wD), y1 = yD.plus(hD);
+    const x1 = xD.plus(wD),
+      y1 = yD.plus(hD);
     // Use H (horizontal) and V (vertical) commands for smaller output
     return `M${f(xD)} ${f(yD)}H${f(x1)}V${f(y1)}H${f(xD)}Z`;
   }
-  const left = xD, right = xD.plus(wD), top = yD, bottom = yD.plus(hD);
-  const leftInner = left.plus(rxD), rightInner = right.minus(rxD);
-  const topInner = top.plus(ryD), bottomInner = bottom.minus(ryD);
+  const left = xD,
+    right = xD.plus(wD),
+    top = yD,
+    bottom = yD.plus(hD);
+  const leftInner = left.plus(rxD),
+    rightInner = right.minus(rxD);
+  const topInner = top.plus(ryD),
+    bottomInner = bottom.minus(ryD);
   if (useArcs) {
     return `M${f(leftInner)} ${f(top)}L${f(rightInner)} ${f(top)}A${f(rxD)} ${f(ryD)} 0 0 1 ${f(right)} ${f(topInner)}L${f(right)} ${f(bottomInner)}A${f(rxD)} ${f(ryD)} 0 0 1 ${f(rightInner)} ${f(bottom)}L${f(leftInner)} ${f(bottom)}A${f(rxD)} ${f(ryD)} 0 0 1 ${f(left)} ${f(bottomInner)}L${f(left)} ${f(topInner)}A${f(rxD)} ${f(ryD)} 0 0 1 ${f(leftInner)} ${f(top)}Z`;
   }
-  const kappa = getKappa(), kx = kappa.mul(rxD), ky = kappa.mul(ryD);
+  const kappa = getKappa(),
+    kx = kappa.mul(rxD),
+    ky = kappa.mul(ryD);
   // Each corner has two Bezier control points:
   // First control point: offset from start point along the edge tangent
   // Second control point: offset from end point along the edge tangent
   return `M${f(leftInner)} ${f(top)}L${f(rightInner)} ${f(top)}C${f(rightInner.plus(kx))} ${f(top)} ${f(right)} ${f(topInner.minus(ky))} ${f(right)} ${f(topInner)}L${f(right)} ${f(bottomInner)}C${f(right)} ${f(bottomInner.plus(ky))} ${f(rightInner.plus(kx))} ${f(bottom)} ${f(rightInner)} ${f(bottom)}L${f(leftInner)} ${f(bottom)}C${f(leftInner.minus(kx))} ${f(bottom)} ${f(left)} ${f(bottomInner.plus(ky))} ${f(left)} ${f(bottomInner)}L${f(left)} ${f(topInner)}C${f(left)} ${f(topInner.minus(ky))} ${f(leftInner.minus(kx))} ${f(top)} ${f(leftInner)} ${f(top)}Z`;
 }
 
+/**
+ * Convert a line segment to SVG path data.
+ * @param {number|Decimal} x1 - Start point X coordinate
+ * @param {number|Decimal} y1 - Start point Y coordinate
+ * @param {number|Decimal} x2 - End point X coordinate
+ * @param {number|Decimal} y2 - End point Y coordinate
+ * @param {number} precision - Decimal precision for output coordinates
+ * @returns {string} SVG path data string
+ */
 export function lineToPathData(x1, y1, x2, y2, precision = 6) {
-  const f = v => formatNumber(D(v), precision);
+  const f = (v) => formatNumber(D(v), precision);
   return `M${f(x1)} ${f(y1)}L${f(x2)} ${f(y2)}`;
 }
 
+/**
+ * Parse SVG points attribute string into array of Decimal coordinate pairs.
+ * @param {string|Array|Object} points - Points string, array, or SVGAnimatedPoints object
+ * @returns {Array<Array<Decimal>>} Array of [x, y] Decimal pairs
+ */
 function parsePoints(points) {
+  // Handle null/undefined
+  if (points == null) return [];
+  // Handle arrays
   if (Array.isArray(points)) return points.map(([x, y]) => [D(x), D(y)]);
-  const nums = points.split(/[\s,]+/).filter(s => s.length > 0).map(s => D(s));
+  // Handle SVGAnimatedPoints or objects with baseVal
+  let pointsValue = points;
+  if (typeof pointsValue === "object" && pointsValue.baseVal !== undefined) {
+    pointsValue = pointsValue.baseVal;
+  }
+  // Convert to string if not already a string
+  if (typeof pointsValue !== "string") {
+    if (typeof pointsValue.toString === "function") {
+      pointsValue = pointsValue.toString();
+    } else {
+      return [];
+    }
+  }
+  const nums = pointsValue
+    .split(/[\s,]+/)
+    .filter((s) => s.length > 0)
+    .map((s) => D(s));
   const pairs = [];
   for (let i = 0; i < nums.length; i += 2) {
     if (i + 1 < nums.length) pairs.push([nums[i], nums[i + 1]]);
@@ -220,10 +360,16 @@ function parsePoints(points) {
   return pairs;
 }
 
+/**
+ * Convert polyline points to SVG path data.
+ * @param {string|Array} points - Points string or array of coordinate pairs
+ * @param {number} precision - Decimal precision for output coordinates
+ * @returns {string} SVG path data string
+ */
 export function polylineToPathData(points, precision = 6) {
   const pairs = parsePoints(points);
-  if (pairs.length === 0) return '';
-  const f = v => formatNumber(v, precision);
+  if (pairs.length === 0) return "";
+  const f = (v) => formatNumber(v, precision);
   const [x0, y0] = pairs[0];
   let path = `M${f(x0)} ${f(y0)}`;
   for (let i = 1; i < pairs.length; i++) {
@@ -233,18 +379,46 @@ export function polylineToPathData(points, precision = 6) {
   return path;
 }
 
+/**
+ * Convert polygon points to SVG path data (closed path).
+ * @param {string|Array} points - Points string or array of coordinate pairs
+ * @param {number} precision - Decimal precision for output coordinates
+ * @returns {string} SVG path data string with Z (closepath) command
+ */
 export function polygonToPathData(points, precision = 6) {
   const path = polylineToPathData(points, precision);
-  return path ? path + ' Z' : '';
+  return path ? path + " Z" : "";
 }
 
 // Parameter count for each SVG path command
 const COMMAND_PARAMS = {
-  M: 2, m: 2, L: 2, l: 2, H: 1, h: 1, V: 1, v: 1,
-  C: 6, c: 6, S: 4, s: 4, Q: 4, q: 4, T: 2, t: 2,
-  A: 7, a: 7, Z: 0, z: 0
+  M: 2,
+  m: 2,
+  L: 2,
+  l: 2,
+  H: 1,
+  h: 1,
+  V: 1,
+  v: 1,
+  C: 6,
+  c: 6,
+  S: 4,
+  s: 4,
+  Q: 4,
+  q: 4,
+  T: 2,
+  t: 2,
+  A: 7,
+  a: 7,
+  Z: 0,
+  z: 0,
 };
 
+/**
+ * Parse SVG path data string into command objects.
+ * @param {string} pathData - SVG path data string
+ * @returns {Array<Object>} Array of {command, args} objects
+ */
 export function parsePathData(pathData) {
   const commands = [];
   const commandRegex = /([MmLlHhVvCcSsQqTtAaZz])\s*([^MmLlHhVvCcSsQqTtAaZz]*)/g;
@@ -252,7 +426,14 @@ export function parsePathData(pathData) {
   while ((match = commandRegex.exec(pathData)) !== null) {
     const command = match[1];
     const argsStr = match[2].trim();
-    const allArgs = argsStr.length > 0 ? argsStr.split(/[\s,]+/).filter(s => s.length > 0).map(s => D(s)) : [];
+
+    // FIX: Use regex to extract numbers, handles implicit negative separators (e.g., "0.8-2.9" -> ["0.8", "-2.9"])
+    // Per W3C SVG spec, negative signs can act as delimiters without spaces
+    const numRegex = /-?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?/g;
+    const allArgs =
+      argsStr.length > 0
+        ? Array.from(argsStr.matchAll(numRegex), (m) => D(m[0]))
+        : [];
 
     const paramCount = COMMAND_PARAMS[command];
 
@@ -267,8 +448,8 @@ export function parsePathData(pathData) {
         if (args.length === paramCount) {
           // For M/m, first group is moveto, subsequent groups become implicit lineto (L/l)
           let effectiveCmd = command;
-          if (i > 0 && (command === 'M' || command === 'm')) {
-            effectiveCmd = command === 'M' ? 'L' : 'l';
+          if (i > 0 && (command === "M" || command === "m")) {
+            effectiveCmd = command === "M" ? "L" : "l";
           }
           commands.push({ command: effectiveCmd, args });
         }
@@ -279,62 +460,84 @@ export function parsePathData(pathData) {
   return commands;
 }
 
+/**
+ * Convert path command array back to SVG path data string.
+ * @param {Array<Object>} commands - Array of {command, args} objects
+ * @param {number} precision - Decimal precision for output coordinates
+ * @returns {string} SVG path data string
+ */
 export function pathArrayToString(commands, precision = 6) {
-  return commands.map(({ command, args }) => {
-    const argsStr = args.map(a => formatNumber(a, precision)).join(' ');
-    return argsStr.length > 0 ? `${command} ${argsStr}` : command;
-  }).join(' ');
+  return commands
+    .map(({ command, args }) => {
+      const argsStr = args.map((a) => formatNumber(a, precision)).join(" ");
+      return argsStr.length > 0 ? `${command} ${argsStr}` : command;
+    })
+    .join(" ");
 }
 
+/**
+ * Convert all path commands to absolute coordinates.
+ * @param {string} pathData - SVG path data string
+ * @returns {string} Path data with all absolute commands
+ */
 export function pathToAbsolute(pathData) {
   const commands = parsePathData(pathData);
   const result = [];
-  let currentX = new Decimal(0), currentY = new Decimal(0);
-  let subpathStartX = new Decimal(0), subpathStartY = new Decimal(0);
-  let lastControlX = new Decimal(0), lastControlY = new Decimal(0);
-  let lastCommand = '';
+  let currentX = new Decimal(0),
+    currentY = new Decimal(0);
+  let subpathStartX = new Decimal(0),
+    subpathStartY = new Decimal(0);
+  let lastControlX = new Decimal(0),
+    lastControlY = new Decimal(0);
+  let lastCommand = "";
 
   for (const { command, args } of commands) {
     const isRelative = command === command.toLowerCase();
     const upperCmd = command.toUpperCase();
-    if (upperCmd === 'M') {
+    if (upperCmd === "M") {
       const x = isRelative ? currentX.plus(args[0]) : args[0];
       const y = isRelative ? currentY.plus(args[1]) : args[1];
-      currentX = x; currentY = y; subpathStartX = x; subpathStartY = y;
-      result.push({ command: 'M', args: [x, y] });
-      lastCommand = 'M';
-    } else if (upperCmd === 'L') {
+      currentX = x;
+      currentY = y;
+      subpathStartX = x;
+      subpathStartY = y;
+      result.push({ command: "M", args: [x, y] });
+      lastCommand = "M";
+    } else if (upperCmd === "L") {
       const x = isRelative ? currentX.plus(args[0]) : args[0];
       const y = isRelative ? currentY.plus(args[1]) : args[1];
-      currentX = x; currentY = y;
-      result.push({ command: 'L', args: [x, y] });
-      lastCommand = 'L';
-    } else if (upperCmd === 'H') {
+      currentX = x;
+      currentY = y;
+      result.push({ command: "L", args: [x, y] });
+      lastCommand = "L";
+    } else if (upperCmd === "H") {
       const x = isRelative ? currentX.plus(args[0]) : args[0];
       currentX = x;
-      result.push({ command: 'L', args: [x, currentY] });
-      lastCommand = 'H';
-    } else if (upperCmd === 'V') {
+      result.push({ command: "L", args: [x, currentY] });
+      lastCommand = "H";
+    } else if (upperCmd === "V") {
       const y = isRelative ? currentY.plus(args[0]) : args[0];
       currentY = y;
-      result.push({ command: 'L', args: [currentX, y] });
-      lastCommand = 'V';
-    } else if (upperCmd === 'C') {
+      result.push({ command: "L", args: [currentX, y] });
+      lastCommand = "V";
+    } else if (upperCmd === "C") {
       const x1 = isRelative ? currentX.plus(args[0]) : args[0];
       const y1 = isRelative ? currentY.plus(args[1]) : args[1];
       const x2 = isRelative ? currentX.plus(args[2]) : args[2];
       const y2 = isRelative ? currentY.plus(args[3]) : args[3];
       const x = isRelative ? currentX.plus(args[4]) : args[4];
       const y = isRelative ? currentY.plus(args[5]) : args[5];
-      lastControlX = x2; lastControlY = y2;
-      currentX = x; currentY = y;
-      result.push({ command: 'C', args: [x1, y1, x2, y2, x, y] });
-      lastCommand = 'C';
-    } else if (upperCmd === 'S') {
+      lastControlX = x2;
+      lastControlY = y2;
+      currentX = x;
+      currentY = y;
+      result.push({ command: "C", args: [x1, y1, x2, y2, x, y] });
+      lastCommand = "C";
+    } else if (upperCmd === "S") {
       // Smooth cubic Bezier: 4 args (x2, y2, x, y)
       // First control point is reflection of previous second control point
       let x1, y1;
-      if (lastCommand === 'C' || lastCommand === 'S') {
+      if (lastCommand === "C" || lastCommand === "S") {
         x1 = currentX.mul(2).minus(lastControlX);
         y1 = currentY.mul(2).minus(lastControlY);
       } else {
@@ -345,25 +548,29 @@ export function pathToAbsolute(pathData) {
       const y2 = isRelative ? currentY.plus(args[1]) : args[1];
       const x = isRelative ? currentX.plus(args[2]) : args[2];
       const y = isRelative ? currentY.plus(args[3]) : args[3];
-      lastControlX = x2; lastControlY = y2;
-      currentX = x; currentY = y;
-      result.push({ command: 'C', args: [x1, y1, x2, y2, x, y] });
-      lastCommand = 'S';
-    } else if (upperCmd === 'Q') {
+      lastControlX = x2;
+      lastControlY = y2;
+      currentX = x;
+      currentY = y;
+      result.push({ command: "C", args: [x1, y1, x2, y2, x, y] });
+      lastCommand = "S";
+    } else if (upperCmd === "Q") {
       // Quadratic Bezier: 4 args (x1, y1, x, y)
       const x1 = isRelative ? currentX.plus(args[0]) : args[0];
       const y1 = isRelative ? currentY.plus(args[1]) : args[1];
       const x = isRelative ? currentX.plus(args[2]) : args[2];
       const y = isRelative ? currentY.plus(args[3]) : args[3];
-      lastControlX = x1; lastControlY = y1;
-      currentX = x; currentY = y;
-      result.push({ command: 'Q', args: [x1, y1, x, y] });
-      lastCommand = 'Q';
-    } else if (upperCmd === 'T') {
+      lastControlX = x1;
+      lastControlY = y1;
+      currentX = x;
+      currentY = y;
+      result.push({ command: "Q", args: [x1, y1, x, y] });
+      lastCommand = "Q";
+    } else if (upperCmd === "T") {
       // Smooth quadratic Bezier: 2 args (x, y)
       // Control point is reflection of previous control point
       let x1, y1;
-      if (lastCommand === 'Q' || lastCommand === 'T') {
+      if (lastCommand === "Q" || lastCommand === "T") {
         x1 = currentX.mul(2).minus(lastControlX);
         y1 = currentY.mul(2).minus(lastControlY);
       } else {
@@ -372,20 +579,27 @@ export function pathToAbsolute(pathData) {
       }
       const x = isRelative ? currentX.plus(args[0]) : args[0];
       const y = isRelative ? currentY.plus(args[1]) : args[1];
-      lastControlX = x1; lastControlY = y1;
-      currentX = x; currentY = y;
-      result.push({ command: 'Q', args: [x1, y1, x, y] });
-      lastCommand = 'T';
-    } else if (upperCmd === 'A') {
+      lastControlX = x1;
+      lastControlY = y1;
+      currentX = x;
+      currentY = y;
+      result.push({ command: "Q", args: [x1, y1, x, y] });
+      lastCommand = "T";
+    } else if (upperCmd === "A") {
       const x = isRelative ? currentX.plus(args[5]) : args[5];
       const y = isRelative ? currentY.plus(args[6]) : args[6];
-      currentX = x; currentY = y;
-      result.push({ command: 'A', args: [args[0], args[1], args[2], args[3], args[4], x, y] });
-      lastCommand = 'A';
-    } else if (upperCmd === 'Z') {
-      currentX = subpathStartX; currentY = subpathStartY;
-      result.push({ command: 'Z', args: [] });
-      lastCommand = 'Z';
+      currentX = x;
+      currentY = y;
+      result.push({
+        command: "A",
+        args: [args[0], args[1], args[2], args[3], args[4], x, y],
+      });
+      lastCommand = "A";
+    } else if (upperCmd === "Z") {
+      currentX = subpathStartX;
+      currentY = subpathStartY;
+      result.push({ command: "Z", args: [] });
+      lastCommand = "Z";
     } else {
       result.push({ command, args });
       lastCommand = command;
@@ -394,9 +608,33 @@ export function pathToAbsolute(pathData) {
   return pathArrayToString(result);
 }
 
-export function transformArcParams(rx, ry, xAxisRotation, largeArc, sweep, endX, endY, matrix) {
-  const rxD = D(rx), ryD = D(ry), rotD = D(xAxisRotation);
-  const endXD = D(endX), endYD = D(endY);
+/**
+ * Transform arc command parameters by an affine transformation matrix.
+ * @param {number|Decimal} rx - X radius
+ * @param {number|Decimal} ry - Y radius
+ * @param {number|Decimal} xAxisRotation - Rotation angle in degrees
+ * @param {number} largeArc - Large arc flag (0 or 1)
+ * @param {number} sweep - Sweep flag (0 or 1)
+ * @param {number|Decimal} endX - Arc end point X
+ * @param {number|Decimal} endY - Arc end point Y
+ * @param {Matrix} matrix - 3x3 transformation matrix
+ * @returns {Array} Transformed arc parameters [rx, ry, rotation, largeArc, sweep, endX, endY]
+ */
+export function transformArcParams(
+  rx,
+  ry,
+  xAxisRotation,
+  largeArc,
+  sweep,
+  endX,
+  endY,
+  matrix,
+) {
+  const rxD = D(rx),
+    ryD = D(ry),
+    rotD = D(xAxisRotation);
+  const endXD = D(endX),
+    endYD = D(endY);
 
   // Transform the endpoint
   const endPoint = Matrix.from([[endXD], [endYD], [new Decimal(1)]]);
@@ -405,8 +643,10 @@ export function transformArcParams(rx, ry, xAxisRotation, largeArc, sweep, endX,
   const newEndY = transformedEnd.data[1][0].div(transformedEnd.data[2][0]);
 
   // Extract the 2x2 linear part of the affine transformation
-  const a = matrix.data[0][0], b = matrix.data[0][1];
-  const c = matrix.data[1][0], d = matrix.data[1][1];
+  const a = matrix.data[0][0],
+    b = matrix.data[0][1];
+  const c = matrix.data[1][0],
+    d = matrix.data[1][1];
 
   // Calculate determinant to check for reflection (flips sweep direction)
   const det = a.mul(d).minus(b.mul(c));
@@ -416,7 +656,8 @@ export function transformArcParams(rx, ry, xAxisRotation, largeArc, sweep, endX,
   // For an ellipse with rotation, we need to compute the transformed ellipse parameters
   // Convert rotation to radians
   const rotRad = rotD.mul(new Decimal(Math.PI)).div(180);
-  const cosRot = Decimal.cos(rotRad), sinRot = Decimal.sin(rotRad);
+  const cosRot = Decimal.cos(rotRad),
+    sinRot = Decimal.sin(rotRad);
 
   // Unit ellipse basis vectors (before xAxisRotation)
   // The ellipse can be parameterized as: [rx*cos(t)*cos(rot) - ry*sin(t)*sin(rot), rx*cos(t)*sin(rot) + ry*sin(t)*cos(rot)]
@@ -448,30 +689,53 @@ export function transformArcParams(rx, ry, xAxisRotation, largeArc, sweep, endX,
   return [newRx, newRy, newRot, largeArc, newSweep, newEndX, newEndY];
 }
 
+/**
+ * Transform path data by an affine transformation matrix.
+ * @param {string} pathData - SVG path data string
+ * @param {Matrix} matrix - 3x3 transformation matrix
+ * @param {number} precision - Decimal precision for output coordinates
+ * @returns {string} Transformed SVG path data
+ */
 export function transformPathData(pathData, matrix, precision = 6) {
   const absPath = pathToAbsolute(pathData);
   const commands = parsePathData(absPath);
   const result = [];
   for (const { command, args } of commands) {
-    if (command === 'M' || command === 'L') {
+    if (command === "M" || command === "L") {
       const pt = Matrix.from([[args[0]], [args[1]], [new Decimal(1)]]);
       const transformed = matrix.mul(pt);
       const x = transformed.data[0][0].div(transformed.data[2][0]);
       const y = transformed.data[1][0].div(transformed.data[2][0]);
       result.push({ command, args: [x, y] });
-    } else if (command === 'C') {
+    } else if (command === "C") {
       const transformedArgs = [];
       for (let i = 0; i < 6; i += 2) {
         const pt = Matrix.from([[args[i]], [args[i + 1]], [new Decimal(1)]]);
         const transformed = matrix.mul(pt);
-        transformedArgs.push(transformed.data[0][0].div(transformed.data[2][0]));
-        transformedArgs.push(transformed.data[1][0].div(transformed.data[2][0]));
+        transformedArgs.push(
+          transformed.data[0][0].div(transformed.data[2][0]),
+        );
+        transformedArgs.push(
+          transformed.data[1][0].div(transformed.data[2][0]),
+        );
       }
       result.push({ command, args: transformedArgs });
-    } else if (command === 'A') {
+    } else if (command === "A") {
       const [newRx, newRy, newRot, newLarge, newSweep, newEndX, newEndY] =
-        transformArcParams(args[0], args[1], args[2], args[3], args[4], args[5], args[6], matrix);
-      result.push({ command, args: [newRx, newRy, newRot, newLarge, newSweep, newEndX, newEndY] });
+        transformArcParams(
+          args[0],
+          args[1],
+          args[2],
+          args[3],
+          args[4],
+          args[5],
+          args[6],
+          matrix,
+        );
+      result.push({
+        command,
+        args: [newRx, newRy, newRot, newLarge, newSweep, newEndX, newEndY],
+      });
     } else {
       result.push({ command, args });
     }
@@ -479,6 +743,16 @@ export function transformPathData(pathData, matrix, precision = 6) {
   return pathArrayToString(result, precision);
 }
 
+/**
+ * Convert quadratic Bezier to cubic Bezier control points.
+ * @param {Decimal} x0 - Start point X
+ * @param {Decimal} y0 - Start point Y
+ * @param {Decimal} x1 - Control point X
+ * @param {Decimal} y1 - Control point Y
+ * @param {Decimal} x2 - End point X
+ * @param {Decimal} y2 - End point Y
+ * @returns {Array<Decimal>} Cubic Bezier control points [cp1x, cp1y, cp2x, cp2y, x2, y2]
+ */
 function quadraticToCubic(x0, y0, x1, y1, x2, y2) {
   const twoThirds = new Decimal(2).div(3);
   const cp1x = x0.plus(twoThirds.mul(x1.minus(x0)));
@@ -488,66 +762,86 @@ function quadraticToCubic(x0, y0, x1, y1, x2, y2) {
   return [cp1x, cp1y, cp2x, cp2y, x2, y2];
 }
 
+/**
+ * Convert all path commands to cubic Bezier curves.
+ * @param {string} pathData - SVG path data string
+ * @returns {string} Path data with only M, C, and Z commands
+ */
 export function pathToCubics(pathData) {
   const absPath = pathToAbsolute(pathData);
   const commands = parsePathData(absPath);
   const result = [];
-  let currentX = new Decimal(0), currentY = new Decimal(0);
-  let lastControlX = new Decimal(0), lastControlY = new Decimal(0);
-  let lastCommand = '';
+  let currentX = new Decimal(0),
+    currentY = new Decimal(0);
+  let lastControlX = new Decimal(0),
+    lastControlY = new Decimal(0);
+  let lastCommand = "";
   for (const { command, args } of commands) {
-    if (command === 'M') {
-      currentX = args[0]; currentY = args[1];
-      result.push({ command: 'M', args: [currentX, currentY] });
-      lastCommand = 'M';
-    } else if (command === 'L') {
-      const x = args[0], y = args[1];
-      result.push({ command: 'C', args: [currentX, currentY, x, y, x, y] });
-      currentX = x; currentY = y;
-      lastCommand = 'L';
-    } else if (command === 'C') {
+    if (command === "M") {
+      currentX = args[0];
+      currentY = args[1];
+      result.push({ command: "M", args: [currentX, currentY] });
+      lastCommand = "M";
+    } else if (command === "L") {
+      const x = args[0],
+        y = args[1];
+      result.push({ command: "C", args: [currentX, currentY, x, y, x, y] });
+      currentX = x;
+      currentY = y;
+      lastCommand = "L";
+    } else if (command === "C") {
       const [x1, y1, x2, y2, x, y] = args;
-      result.push({ command: 'C', args: [x1, y1, x2, y2, x, y] });
-      lastControlX = x2; lastControlY = y2;
-      currentX = x; currentY = y;
-      lastCommand = 'C';
-    } else if (command === 'S') {
+      result.push({ command: "C", args: [x1, y1, x2, y2, x, y] });
+      lastControlX = x2;
+      lastControlY = y2;
+      currentX = x;
+      currentY = y;
+      lastCommand = "C";
+    } else if (command === "S") {
       let x1, y1;
-      if (lastCommand === 'C' || lastCommand === 'S') {
+      if (lastCommand === "C" || lastCommand === "S") {
         x1 = currentX.mul(2).minus(lastControlX);
         y1 = currentY.mul(2).minus(lastControlY);
       } else {
-        x1 = currentX; y1 = currentY;
+        x1 = currentX;
+        y1 = currentY;
       }
       const [x2, y2, x, y] = args;
-      result.push({ command: 'C', args: [x1, y1, x2, y2, x, y] });
-      lastControlX = x2; lastControlY = y2;
-      currentX = x; currentY = y;
-      lastCommand = 'S';
-    } else if (command === 'Q') {
+      result.push({ command: "C", args: [x1, y1, x2, y2, x, y] });
+      lastControlX = x2;
+      lastControlY = y2;
+      currentX = x;
+      currentY = y;
+      lastCommand = "S";
+    } else if (command === "Q") {
       const [x1, y1, x, y] = args;
       const cubic = quadraticToCubic(currentX, currentY, x1, y1, x, y);
-      result.push({ command: 'C', args: cubic });
-      lastControlX = x1; lastControlY = y1;
-      currentX = x; currentY = y;
-      lastCommand = 'Q';
-    } else if (command === 'T') {
+      result.push({ command: "C", args: cubic });
+      lastControlX = x1;
+      lastControlY = y1;
+      currentX = x;
+      currentY = y;
+      lastCommand = "Q";
+    } else if (command === "T") {
       let x1, y1;
-      if (lastCommand === 'Q' || lastCommand === 'T') {
+      if (lastCommand === "Q" || lastCommand === "T") {
         x1 = currentX.mul(2).minus(lastControlX);
         y1 = currentY.mul(2).minus(lastControlY);
       } else {
-        x1 = currentX; y1 = currentY;
+        x1 = currentX;
+        y1 = currentY;
       }
       const [x, y] = args;
       const cubic = quadraticToCubic(currentX, currentY, x1, y1, x, y);
-      result.push({ command: 'C', args: cubic });
-      lastControlX = x1; lastControlY = y1;
-      currentX = x; currentY = y;
-      lastCommand = 'T';
-    } else if (command === 'Z') {
-      result.push({ command: 'Z', args: [] });
-      lastCommand = 'Z';
+      result.push({ command: "C", args: cubic });
+      lastControlX = x1;
+      lastControlY = y1;
+      currentX = x;
+      currentY = y;
+      lastCommand = "T";
+    } else if (command === "Z") {
+      result.push({ command: "Z", args: [] });
+      lastCommand = "Z";
     } else {
       result.push({ command, args });
       lastCommand = command;
@@ -556,6 +850,65 @@ export function pathToCubics(pathData) {
   return pathArrayToString(result);
 }
 
+/**
+ * Convert SVG shape element to path element with equivalent path data.
+ * @param {Object} element - SVG shape element (circle, ellipse, rect, line, polyline, polygon)
+ * @param {number} precision - Decimal precision for output coordinates
+ * @returns {string|null} SVG path data string, or null if element type not supported
+ */
+export function convertElementToPath(element, precision = 6) {
+  const getAttr = (name, defaultValue = 0) => {
+    const rawValue = element.getAttribute
+      ? element.getAttribute(name)
+      : element[name];
+    const value =
+      rawValue !== undefined && rawValue !== null ? rawValue : defaultValue;
+    // Strip CSS units before returning (handles px, em, %, etc.)
+    return stripUnits(value);
+  };
+  const tagName = (element.tagName || element.type || "").toLowerCase();
+  if (tagName === "circle") {
+    return circleToPathData(
+      getAttr("cx", 0),
+      getAttr("cy", 0),
+      getAttr("r", 0),
+      precision,
+    );
+  } else if (tagName === "ellipse") {
+    return ellipseToPathData(
+      getAttr("cx", 0),
+      getAttr("cy", 0),
+      getAttr("rx", 0),
+      getAttr("ry", 0),
+      precision,
+    );
+  } else if (tagName === "rect") {
+    return rectToPathData(
+      getAttr("x", 0),
+      getAttr("y", 0),
+      getAttr("width", 0),
+      getAttr("height", 0),
+      getAttr("rx", 0),
+      getAttr("ry", null),
+      false,
+      precision,
+    );
+  } else if (tagName === "line") {
+    return lineToPathData(
+      getAttr("x1", 0),
+      getAttr("y1", 0),
+      getAttr("x2", 0),
+      getAttr("y2", 0),
+      precision,
+    );
+  } else if (tagName === "polyline") {
+    return polylineToPathData(getAttr("points", ""), precision);
+  } else if (tagName === "polygon") {
+    return polygonToPathData(getAttr("points", ""), precision);
+  }
+  return null;
+}
+
 /**
  * Strip CSS units from a value string (e.g., "100px" -> 100, "50%" -> 50, "2em" -> 2)
  * Returns the numeric value or 0 if parsing fails.
@@ -563,32 +916,8 @@ export function pathToCubics(pathData) {
  * @returns {number} Numeric value without units
  */
 function stripUnits(val) {
-  if (typeof val === 'string') {
+  if (typeof val === "string") {
     return parseFloat(val) || 0;
   }
   return val;
 }
-
-export function convertElementToPath(element, precision = 6) {
-  const getAttr = (name, defaultValue = 0) => {
-    const rawValue = element.getAttribute ? element.getAttribute(name) : element[name];
-    const value = rawValue !== undefined && rawValue !== null ? rawValue : defaultValue;
-    // Strip CSS units before returning (handles px, em, %, etc.)
-    return stripUnits(value);
-  };
-  const tagName = (element.tagName || element.type || '').toLowerCase();
-  if (tagName === 'circle') {
-    return circleToPathData(getAttr('cx', 0), getAttr('cy', 0), getAttr('r', 0), precision);
-  } else if (tagName === 'ellipse') {
-    return ellipseToPathData(getAttr('cx', 0), getAttr('cy', 0), getAttr('rx', 0), getAttr('ry', 0), precision);
-  } else if (tagName === 'rect') {
-    return rectToPathData(getAttr('x', 0), getAttr('y', 0), getAttr('width', 0), getAttr('height', 0), getAttr('rx', 0), getAttr('ry', null), false, precision);
-  } else if (tagName === 'line') {
-    return lineToPathData(getAttr('x1', 0), getAttr('y1', 0), getAttr('x2', 0), getAttr('y2', 0), precision);
-  } else if (tagName === 'polyline') {
-    return polylineToPathData(getAttr('points', ''), precision);
-  } else if (tagName === 'polygon') {
-    return polygonToPathData(getAttr('points', ''), precision);
-  }
-  return null;
-}