@emasoft/svg-matrix 1.0.11 → 1.0.13

package/bin/svg-matrix.js

@@ -20,6 +20,7 @@ import { join, dirname, basename, extname, resolve, isAbsolute } from 'path';
 // Import library modules
 import * as SVGFlatten from '../src/svg-flatten.js';
 import * as GeometryToPath from '../src/geometry-to-path.js';
+import * as FlattenPipeline from '../src/flatten-pipeline.js';
 import { VERSION } from '../src/index.js';
 
 // ============================================================================
@@ -81,6 +82,13 @@ let currentOutputFile = null; // Track for cleanup on interrupt
  * @property {boolean} recursive - Process folders recursively
  * @property {boolean} overwrite - Overwrite existing files
  * @property {boolean} dryRun - Show what would be done without doing it
+ * @property {boolean} transformOnly - Only flatten transforms (legacy mode)
+ * @property {boolean} resolveClipPaths - Apply clipPath boolean operations
+ * @property {boolean} resolveMasks - Convert masks to clipped geometry
+ * @property {boolean} resolveUse - Expand use/symbol references
+ * @property {boolean} resolveMarkers - Expand marker references
+ * @property {boolean} resolvePatterns - Expand pattern fills
+ * @property {boolean} bakeGradients - Bake gradientTransform into coordinates
  */
 
 const DEFAULT_CONFIG = {
@@ -95,6 +103,19 @@ const DEFAULT_CONFIG = {
   recursive: false,
   overwrite: false,
   dryRun: false,
+  // Full flatten options - all enabled by default for TRUE flattening
+  transformOnly: false,       // If true, skip all resolvers (legacy behavior)
+  resolveClipPaths: true,     // Apply clipPath boolean intersection
+  resolveMasks: true,         // Convert masks to clipped geometry
+  resolveUse: true,           // Expand use/symbol elements inline
+  resolveMarkers: true,       // Instantiate markers as path geometry
+  resolvePatterns: true,      // Expand pattern fills to tiled geometry
+  bakeGradients: true,        // Bake gradientTransform into gradient coords
+  // NOTE: Verification is ALWAYS enabled - precision is non-negotiable
+  // E2E verification precision controls
+  clipSegments: 64,           // Polygon samples for clip operations (higher = more precise)
+  bezierArcs: 8,              // Bezier arcs for circles/ellipses (multiple of 4; 8=π/4 optimal)
+  e2eTolerance: '1e-10',      // E2E verification tolerance (tighter with more segments)
 };
 
 /** @type {CLIConfig} */
@@ -487,7 +508,14 @@ ${colors.bright}USAGE:${colors.reset}
   svg-matrix <command> [options] <input> [-o <output>]
 
 ${colors.bright}COMMANDS:${colors.reset}
-  flatten     Flatten SVG transforms into path data
+  flatten     TRUE flatten: resolve ALL transform dependencies
+              - Bakes transform attributes into coordinates
+              - Applies clipPath boolean operations
+              - Converts masks to clipped geometry
+              - Expands use/symbol references inline
+              - Instantiates markers as path geometry
+              - Expands pattern fills to tiled geometry
+              - Bakes gradientTransform into coordinates
   convert     Convert shapes (rect, circle, etc.) to paths
   normalize   Convert paths to absolute cubic Bezier curves
   info        Show SVG file information
@@ -506,10 +534,35 @@ ${colors.bright}OPTIONS:${colors.reset}
   --log-file <path>       Write log to file
   -h, --help              Show help
 
+${colors.bright}FLATTEN OPTIONS:${colors.reset}
+  --transform-only        Only flatten transforms (skip resolvers)
+  --no-clip-paths         Skip clipPath boolean operations
+  --no-masks              Skip mask to clip conversion
+  --no-use                Skip use/symbol expansion
+  --no-markers            Skip marker instantiation
+  --no-patterns           Skip pattern expansion
+  --no-gradients          Skip gradient transform baking
+
+${colors.bright}E2E VERIFICATION OPTIONS:${colors.reset}
+  --clip-segments <n>     Polygon samples for clipping (default: 64)
+                          Higher = better curve approximation, tighter tolerance
+                          Recommended: 64 (balanced), 128 (high), 256 (very high)
+  --bezier-arcs <n>       Bezier arcs for circles/ellipses (default: 8)
+                          Must be multiple of 4. Multiples of 8 are optimal (π/4).
+                          8: ~0.0004% error (π/4 optimal base)
+                          16: ~0.000007% error (high precision)
+                          32: ~0.0000004% error, 64: ~0.00000001% error
+  --e2e-tolerance <exp>   E2E verification tolerance exponent (default: 1e-10)
+                          Examples: 1e-8, 1e-10, 1e-12, 1e-14
+                          Tighter tolerance requires more clip-segments
+
+  ${colors.dim}Note: Mathematical verification is ALWAYS enabled.${colors.reset}
+  ${colors.dim}Precision is non-negotiable in this library.${colors.reset}
+
 ${colors.bright}EXAMPLES:${colors.reset}
   svg-matrix flatten input.svg -o output.svg
-  svg-matrix flatten ./svgs/ -o ./output/
-  svg-matrix flatten --list files.txt -o ./output/
+  svg-matrix flatten ./svgs/ -o ./output/ --transform-only
+  svg-matrix flatten --list files.txt -o ./output/ --no-patterns
   svg-matrix convert input.svg -o output.svg --precision 10
   svg-matrix info input.svg
 
@@ -563,8 +616,19 @@ function replacePathD(attrs, newD) {
 }
 
 /**
- * Flatten transforms in SVG content by baking transforms into path data.
- * Handles: path elements, shape elements (converted to paths), and nested groups.
+ * Flatten SVG completely - no transform dependencies remain.
+ *
+ * TRUE flattening resolves ALL transform-dependent elements:
+ * - Bakes transform attributes into path coordinates
+ * - Applies clipPath boolean operations
+ * - Converts masks to clipped geometry
+ * - Expands use/symbol references inline
+ * - Instantiates markers as path geometry
+ * - Expands pattern fills to tiled geometry
+ * - Bakes gradientTransform into gradient coordinates
+ *
+ * Use --transform-only flag for legacy behavior (transforms only).
+ *
  * @param {string} inputPath - Input file path
  * @param {string} outputPath - Output file path
  * @returns {boolean} True if successful
@@ -572,152 +636,247 @@ function replacePathD(attrs, newD) {
 function processFlatten(inputPath, outputPath) {
   try {
     logDebug(`Processing: ${inputPath}`);
-    let result = readFileSync(inputPath, 'utf8');
-    let transformCount = 0;
-    let pathCount = 0;
-    let shapeCount = 0;
+    const svgContent = readFileSync(inputPath, 'utf8');
 
-    // Step 1: Flatten transforms on path elements
-    // Note: regex captures attrs without the closing /> or >
-    result = result.replace(/<path\s+([^>]*?)\s*\/?>/gi, (match, attrs) => {
-      const transform = extractTransform(attrs);
-      const pathD = extractPathD(attrs);
+    // Use legacy transform-only mode if requested
+    if (config.transformOnly) {
+      return processFlattenLegacy(inputPath, outputPath, svgContent);
+    }
+
+    // Build pipeline options from config
+    const pipelineOptions = {
+      precision: config.precision,
+      curveSegments: 20,
+      clipSegments: config.clipSegments,     // Higher segments for clip accuracy (default 64)
+      bezierArcs: config.bezierArcs,         // Bezier arcs for circles/ellipses (default 16)
+      e2eTolerance: config.e2eTolerance,     // Configurable E2E tolerance (default 1e-10)
+      resolveUse: config.resolveUse,
+      resolveMarkers: config.resolveMarkers,
+      resolvePatterns: config.resolvePatterns,
+      resolveMasks: config.resolveMasks,
+      resolveClipPaths: config.resolveClipPaths,
+      flattenTransforms: true, // Always flatten transforms
+      bakeGradients: config.bakeGradients,
+      removeUnusedDefs: true,
+      // NOTE: Verification is ALWAYS enabled - precision is non-negotiable
+    };
+
+    // Run the full flatten pipeline
+    const { svg: flattenedSvg, stats } = FlattenPipeline.flattenSVG(svgContent, pipelineOptions);
+
+    // Report statistics
+    const parts = [];
+    if (stats.transformsFlattened > 0) parts.push(`${stats.transformsFlattened} transforms`);
+    if (stats.useResolved > 0) parts.push(`${stats.useResolved} use`);
+    if (stats.markersResolved > 0) parts.push(`${stats.markersResolved} markers`);
+    if (stats.patternsResolved > 0) parts.push(`${stats.patternsResolved} patterns`);
+    if (stats.masksResolved > 0) parts.push(`${stats.masksResolved} masks`);
+    if (stats.clipPathsApplied > 0) parts.push(`${stats.clipPathsApplied} clipPaths`);
+    if (stats.gradientsProcessed > 0) parts.push(`${stats.gradientsProcessed} gradients`);
+
+    if (parts.length > 0) {
+      logInfo(`Flattened: ${parts.join(', ')}`);
+    } else {
+      logInfo('No transform dependencies found');
+    }
+
+    // Report verification results (ALWAYS - precision is non-negotiable)
+    if (stats.verifications) {
+      const v = stats.verifications;
+      const total = v.passed + v.failed;
+      if (total > 0) {
+        const verifyStatus = v.allPassed
+          ? `${colors.green}VERIFIED${colors.reset}`
+          : `${colors.red}${v.failed} FAILED${colors.reset}`;
+        logInfo(`Verification: ${v.passed}/${total} - ${verifyStatus}`);
+
+        // Show detailed results in verbose mode
+        if (config.verbose) {
+          if (v.matrices.length > 0) {
+            logDebug(`  Matrix verifications: ${v.matrices.filter(m => m.valid).length}/${v.matrices.length} passed`);
+          }
+          if (v.transforms.length > 0) {
+            logDebug(`  Transform round-trips: ${v.transforms.filter(t => t.valid).length}/${v.transforms.length} passed`);
+          }
+          if (v.polygons.length > 0) {
+            logDebug(`  Polygon intersections: ${v.polygons.filter(p => p.valid).length}/${v.polygons.length} passed`);
+          }
+          if (v.gradients.length > 0) {
+            logDebug(`  Gradient transforms: ${v.gradients.filter(g => g.valid).length}/${v.gradients.length} passed`);
+          }
+          if (v.e2e && v.e2e.length > 0) {
+            logDebug(`  E2E area conservation: ${v.e2e.filter(e => e.valid).length}/${v.e2e.length} passed`);
+          }
+        }
 
-      if (!transform || !pathD) {
-        return match; // No transform or no path data, skip
+        // Always show failed verifications (not just in verbose mode)
+        const allVerifications = [...v.matrices, ...v.transforms, ...v.polygons, ...v.gradients, ...(v.e2e || [])];
+        const failed = allVerifications.filter(vr => !vr.valid);
+        if (failed.length > 0) {
+          for (const f of failed.slice(0, 3)) {
+            logError(`${colors.red}VERIFICATION FAILED:${colors.reset} ${f.message}`);
+          }
+          if (failed.length > 3) {
+            logError(`...and ${failed.length - 3} more failed verifications`);
+          }
+        }
+      }
+    }
+
+    // Report any errors
+    if (stats.errors.length > 0) {
+      for (const err of stats.errors.slice(0, 5)) {
+        logWarn(err);
+      }
+      if (stats.errors.length > 5) {
+        logWarn(`...and ${stats.errors.length - 5} more errors`);
+      }
+    }
+
+    if (!config.dryRun) {
+      ensureDir(dirname(outputPath));
+      writeFileSync(outputPath, flattenedSvg, 'utf8');
+    }
+    logSuccess(`${basename(inputPath)} -> ${basename(outputPath)}`);
+    return true;
+  } catch (error) {
+    logError(`Failed: ${inputPath}: ${error.message}`);
+    return false;
+  }
+}
+
+/**
+ * Legacy flatten mode - only bakes transform attributes into coordinates.
+ * Does NOT resolve clipPaths, masks, use, markers, patterns, or gradients.
+ * Use this when you only need transform flattening without boolean operations.
+ * @private
+ */
+function processFlattenLegacy(inputPath, outputPath, svgContent) {
+  let result = svgContent;
+  let transformCount = 0;
+  let pathCount = 0;
+  let shapeCount = 0;
+
+  // Step 1: Flatten transforms on path elements
+  result = result.replace(/<path\s+([^>]*?)\s*\/?>/gi, (match, attrs) => {
+    const transform = extractTransform(attrs);
+    const pathD = extractPathD(attrs);
+
+    if (!transform || !pathD) {
+      return match;
+    }
+
+    try {
+      const ctm = SVGFlatten.parseTransformAttribute(transform);
+      const transformedD = SVGFlatten.transformPathData(pathD, ctm, { precision: config.precision });
+      const newAttrs = removeTransform(replacePathD(attrs, transformedD));
+      transformCount++;
+      pathCount++;
+      logDebug(`Flattened path transform: ${transform}`);
+      return `<path ${newAttrs.trim()}${match.endsWith('/>') ? '/>' : '>'}`;
+    } catch (e) {
+      logWarn(`Failed to flatten path: ${e.message}`);
+      return match;
+    }
+  });
+
+  // Step 2: Convert shapes with transforms to flattened paths
+  const shapeTypes = ['rect', 'circle', 'ellipse', 'line', 'polygon', 'polyline'];
+
+  for (const shapeType of shapeTypes) {
+    const shapeRegex = new RegExp(`<${shapeType}([^>]*)\\/>`, 'gi');
+
+    result = result.replace(shapeRegex, (match, attrs) => {
+      const transform = extractTransform(attrs);
+      if (!transform) {
+        return match;
       }
 
       try {
-        // Parse the transform and build CTM
+        const pathD = extractShapeAsPath(shapeType, attrs, config.precision);
+        if (!pathD) {
+          return match;
+        }
+
         const ctm = SVGFlatten.parseTransformAttribute(transform);
-        // Transform the path data
         const transformedD = SVGFlatten.transformPathData(pathD, ctm, { precision: config.precision });
-        // Remove transform and update path data
-        const newAttrs = removeTransform(replacePathD(attrs, transformedD));
+        const attrsToRemove = getShapeSpecificAttrs(shapeType);
+        const styleAttrs = removeShapeAttrs(removeTransform(attrs), attrsToRemove);
         transformCount++;
-        pathCount++;
-        logDebug(`Flattened path transform: ${transform}`);
-        return `<path ${newAttrs.trim()}${match.endsWith('/>') ? '/>' : '>'}`;
+        shapeCount++;
+        logDebug(`Flattened ${shapeType} transform: ${transform}`);
+        return `<path d="${transformedD}"${styleAttrs ? ' ' + styleAttrs : ''}/>`;
       } catch (e) {
-        logWarn(`Failed to flatten path: ${e.message}`);
+        logWarn(`Failed to flatten ${shapeType}: ${e.message}`);
         return match;
       }
     });
+  }
 
-    // Step 2: Convert shapes with transforms to flattened paths
-    const shapeTypes = ['rect', 'circle', 'ellipse', 'line', 'polygon', 'polyline'];
-
-    for (const shapeType of shapeTypes) {
-      const shapeRegex = new RegExp(`<${shapeType}([^>]*)\\/>`, 'gi');
-
-      result = result.replace(shapeRegex, (match, attrs) => {
-        const transform = extractTransform(attrs);
-        if (!transform) {
-          return match; // No transform, skip
-        }
+  // Step 3: Handle group transforms
+  let groupIterations = 0;
+  while (groupIterations < CONSTANTS.MAX_GROUP_ITERATIONS) {
+    const beforeResult = result;
 
+    result = result.replace(
+      /<g([^>]*transform\s*=\s*["']([^"']+)["'][^>]*)>([\s\S]*?)<\/g>/gi,
+      (match, gAttrs, groupTransform, content) => {
         try {
-          // Extract shape attributes and convert to path using helper
-          const pathD = extractShapeAsPath(shapeType, attrs, config.precision);
-
-          if (!pathD) {
-            return match; // Couldn't convert to path
-          }
-
-          // Parse the transform and build CTM
-          const ctm = SVGFlatten.parseTransformAttribute(transform);
-          // Transform the path data
-          const transformedD = SVGFlatten.transformPathData(pathD, ctm, { precision: config.precision });
-          // Build new path element, preserving style attributes
-          const attrsToRemove = getShapeSpecificAttrs(shapeType);
-          const styleAttrs = removeShapeAttrs(removeTransform(attrs), attrsToRemove);
-          transformCount++;
-          shapeCount++;
-          logDebug(`Flattened ${shapeType} transform: ${transform}`);
-          return `<path d="${transformedD}"${styleAttrs ? ' ' + styleAttrs : ''}/>`;
-        } catch (e) {
-          logWarn(`Failed to flatten ${shapeType}: ${e.message}`);
-          return match;
-        }
-      });
-    }
+          const groupCtm = SVGFlatten.parseTransformAttribute(groupTransform);
+          let modifiedContent = content;
+          let childrenModified = false;
 
-    // Step 3: Handle group transforms by propagating to children
-    // This is a simplified approach - for full support, we'd need DOM parsing
-    // For now, we handle the case where a <g> has a transform and contains paths/shapes
-    let groupIterations = 0;
+          modifiedContent = modifiedContent.replace(/<path\s+([^>]*?)\s*\/?>/gi, (pathMatch, pathAttrs) => {
+            const pathD = extractPathD(pathAttrs);
+            if (!pathD) return pathMatch;
 
-    while (groupIterations < CONSTANTS.MAX_GROUP_ITERATIONS) {
-      const beforeResult = result;
+            try {
+              const childTransform = extractTransform(pathAttrs);
+              let combinedCtm = groupCtm;
 
-      // Find groups with transforms
-      result = result.replace(
-        /<g([^>]*transform\s*=\s*["']([^"']+)["'][^>]*)>([\s\S]*?)<\/g>/gi,
-        (match, gAttrs, groupTransform, content) => {
-          try {
-            const groupCtm = SVGFlatten.parseTransformAttribute(groupTransform);
-            let modifiedContent = content;
-            let childrenModified = false;
-
-            // Apply group transform to child paths
-            modifiedContent = modifiedContent.replace(/<path\s+([^>]*?)\s*\/?>/gi, (pathMatch, pathAttrs) => {
-              const pathD = extractPathD(pathAttrs);
-              if (!pathD) return pathMatch;
-
-              try {
-                const childTransform = extractTransform(pathAttrs);
-                let combinedCtm = groupCtm;
-
-                // If child has its own transform, compose them
-                if (childTransform) {
-                  const childCtm = SVGFlatten.parseTransformAttribute(childTransform);
-                  combinedCtm = groupCtm.mul(childCtm);
-                }
-
-                const transformedD = SVGFlatten.transformPathData(pathD, combinedCtm, { precision: config.precision });
-                const newAttrs = removeTransform(replacePathD(pathAttrs, transformedD));
-                childrenModified = true;
-                transformCount++;
-                return `<path ${newAttrs.trim()}${pathMatch.endsWith('/>') ? '/>' : '>'}`;
-              } catch (e) {
-                logWarn(`Failed to apply group transform to path: ${e.message}`);
-                return pathMatch;
+              if (childTransform) {
+                const childCtm = SVGFlatten.parseTransformAttribute(childTransform);
+                combinedCtm = groupCtm.mul(childCtm);
               }
-            });
 
-            if (childrenModified) {
-              // Remove transform from group
-              const newGAttrs = removeTransform(gAttrs);
-              logDebug(`Propagated group transform to children: ${groupTransform}`);
-              return `<g${newGAttrs}>${modifiedContent}</g>`;
+              const transformedD = SVGFlatten.transformPathData(pathD, combinedCtm, { precision: config.precision });
+              const newAttrs = removeTransform(replacePathD(pathAttrs, transformedD));
+              childrenModified = true;
+              transformCount++;
+              return `<path ${newAttrs.trim()}${pathMatch.endsWith('/>') ? '/>' : '>'}`;
+            } catch (e) {
+              logWarn(`Failed to apply group transform to path: ${e.message}`);
+              return pathMatch;
             }
-            return match;
-          } catch (e) {
-            logWarn(`Failed to process group: ${e.message}`);
-            return match;
+          });
+
+          if (childrenModified) {
+            const newGAttrs = removeTransform(gAttrs);
+            logDebug(`Propagated group transform to children: ${groupTransform}`);
+            return `<g${newGAttrs}>${modifiedContent}</g>`;
           }
+          return match;
+        } catch (e) {
+          logWarn(`Failed to process group: ${e.message}`);
+          return match;
         }
-      );
-
-      // Check if anything changed
-      if (result === beforeResult) {
-        break;
       }
-      groupIterations++;
+    );
+
+    if (result === beforeResult) {
+      break;
     }
+    groupIterations++;
+  }
 
-    logInfo(`Flattened ${transformCount} transforms (${pathCount} paths, ${shapeCount} shapes)`);
+  logInfo(`Flattened ${transformCount} transforms (${pathCount} paths, ${shapeCount} shapes) [legacy mode]`);
 
-    if (!config.dryRun) {
-      ensureDir(dirname(outputPath));
-      writeFileSync(outputPath, result, 'utf8');
-    }
-    logSuccess(`${basename(inputPath)} -> ${basename(outputPath)}`);
-    return true;
-  } catch (error) {
-    logError(`Failed: ${inputPath}: ${error.message}`);
-    return false;
+  if (!config.dryRun) {
+    ensureDir(dirname(outputPath));
+    writeFileSync(outputPath, result, 'utf8');
   }
+  logSuccess(`${basename(inputPath)} -> ${basename(outputPath)}`);
+  return true;
 }
 
 function processConvert(inputPath, outputPath) {
@@ -845,6 +1004,43 @@ function parseArgs(args) {
       case '--log-file': cfg.logFile = args[++i]; break;
       case '-h': case '--help': cfg.command = 'help'; break;
       case '--version': cfg.command = 'version'; break;
+      // Full flatten pipeline options
+      case '--transform-only': cfg.transformOnly = true; break;
+      case '--no-clip-paths': cfg.resolveClipPaths = false; break;
+      case '--no-masks': cfg.resolveMasks = false; break;
+      case '--no-use': cfg.resolveUse = false; break;
+      case '--no-markers': cfg.resolveMarkers = false; break;
+      case '--no-patterns': cfg.resolvePatterns = false; break;
+      case '--no-gradients': cfg.bakeGradients = false; break;
+      // E2E verification precision options
+      case '--clip-segments': {
+        const segs = parseInt(args[++i], 10);
+        if (isNaN(segs) || segs < 8 || segs > 512) {
+          logError('clip-segments must be between 8 and 512');
+          process.exit(CONSTANTS.EXIT_ERROR);
+        }
+        cfg.clipSegments = segs;
+        break;
+      }
+      case '--bezier-arcs': {
+        const arcs = parseInt(args[++i], 10);
+        if (isNaN(arcs) || arcs < 4 || arcs > 128) {
+          logError('bezier-arcs must be between 4 and 128');
+          process.exit(CONSTANTS.EXIT_ERROR);
+        }
+        cfg.bezierArcs = arcs;
+        break;
+      }
+      case '--e2e-tolerance': {
+        const tol = args[++i];
+        if (!/^1e-\d+$/.test(tol)) {
+          logError('e2e-tolerance must be in format 1e-N (e.g., 1e-10, 1e-12)');
+          process.exit(CONSTANTS.EXIT_ERROR);
+        }
+        cfg.e2eTolerance = tol;
+        break;
+      }
+      // NOTE: --verify removed - verification is ALWAYS enabled
       default:
         if (arg.startsWith('-')) { logError(`Unknown option: ${arg}`); process.exit(CONSTANTS.EXIT_ERROR); }
         if (['flatten', 'convert', 'normalize', 'info', 'help', 'version'].includes(arg) && cfg.command === 'help') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emasoft/svg-matrix",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "description": "Arbitrary-precision matrix, vector and affine transformation library for JavaScript using decimal.js",
   "type": "module",
   "main": "src/index.js",

package/src/clip-path-resolver.js

@@ -41,6 +41,10 @@ import {
   parseTransformAttribute,
   transformPathData
 } from './svg-flatten.js';
+import {
+  circleToPathDataHP,
+  ellipseToPathDataHP
+} from './geometry-to-path.js';
 import { Logger } from './logger.js';
 
 // Alias for cleaner code
@@ -414,14 +418,32 @@ function removeDuplicateConsecutive(points) {
  * const ctm = Transforms2D.translation(10, 20);
  * const polygon = shapeToPolygon(rect, ctm, 30);
  */
-export function shapeToPolygon(element, ctm = null, samples = DEFAULT_CURVE_SAMPLES) {
+/**
+ * Convert SVG shape to polygon.
+ *
+ * @param {Object} element - Shape element (circle, ellipse, rect, etc.)
+ * @param {Matrix} ctm - Current transform matrix (optional)
+ * @param {number} samples - Samples per curve for polygon conversion
+ * @param {number} bezierArcs - Number of Bezier arcs for circles/ellipses (4=standard, 16 or 64=HP)
+ */
+export function shapeToPolygon(element, ctm = null, samples = DEFAULT_CURVE_SAMPLES, bezierArcs = 4) {
   let pathData;
   switch (element.type) {
     case 'circle':
-      pathData = circleToPath(D(element.cx || 0), D(element.cy || 0), D(element.r || 0));
+      // Use high-precision Bezier arcs for better curve approximation
+      if (bezierArcs > 4) {
+        pathData = circleToPathDataHP(element.cx || 0, element.cy || 0, element.r || 0, bezierArcs, 10);
+      } else {
+        pathData = circleToPath(D(element.cx || 0), D(element.cy || 0), D(element.r || 0));
+      }
       break;
     case 'ellipse':
-      pathData = ellipseToPath(D(element.cx || 0), D(element.cy || 0), D(element.rx || 0), D(element.ry || 0));
+      // Use high-precision Bezier arcs for better curve approximation
+      if (bezierArcs > 4) {
+        pathData = ellipseToPathDataHP(element.cx || 0, element.cy || 0, element.rx || 0, element.ry || 0, bezierArcs, 10);
+      } else {
+        pathData = ellipseToPath(D(element.cx || 0), D(element.cy || 0), D(element.rx || 0), D(element.ry || 0));
+      }
       break;
     case 'rect':
       pathData = rectToPath(D(element.x || 0), D(element.y || 0), D(element.width || 0), D(element.height || 0),