@emasoft/svg-matrix 1.0.12 → 1.0.13

package/bin/svg-matrix.js

@@ -111,6 +111,11 @@ const DEFAULT_CONFIG = {
   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} */
@@ -538,6 +543,22 @@ ${colors.bright}FLATTEN OPTIONS:${colors.reset}
   --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/ --transform-only
@@ -626,6 +647,9 @@ function processFlatten(inputPath, outputPath) {
     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,
@@ -634,6 +658,7 @@ function processFlatten(inputPath, outputPath) {
       flattenTransforms: true, // Always flatten transforms
       bakeGradients: config.bakeGradients,
       removeUnusedDefs: true,
+      // NOTE: Verification is ALWAYS enabled - precision is non-negotiable
     };
 
     // Run the full flatten pipeline
@@ -655,6 +680,49 @@ function processFlatten(inputPath, outputPath) {
       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`);
+          }
+        }
+
+        // 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)) {
@@ -944,6 +1012,35 @@ function parseArgs(args) {
       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.12",
+  "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),

package/src/flatten-pipeline.js

@@ -26,6 +26,7 @@ import * as MeshGradient from './mesh-gradient.js';
 import * as GeometryToPath from './geometry-to-path.js';
 import { parseSVG, SVGElement, buildDefsMap, parseUrlReference, serializeSVG, findElementsWithAttribute } from './svg-parser.js';
 import { Logger } from './logger.js';
+import * as Verification from './verification.js';
 
 Decimal.set({ precision: 80 });
 
@@ -36,7 +37,11 @@ const D = x => (x instanceof Decimal ? x : new Decimal(x));
  */
 const DEFAULT_OPTIONS = {
   precision: 6,              // Decimal places in output coordinates
-  curveSegments: 20,         // Samples per curve for polygon conversion
+  curveSegments: 20,         // Samples per curve for polygon conversion (visual output)
+  clipSegments: 64,          // Higher samples for clip polygon accuracy (affects E2E precision)
+  bezierArcs: 8,             // Bezier arcs for circles/ellipses (must be multiple of 4)
+                             // 8: π/4 optimal base (~0.0004% error)
+                             // 16: π/8 (~0.000007% error), 32: π/16, 64: π/32 (~0.00000001% error)
   resolveUse: true,          // Expand <use> elements
   resolveMarkers: true,      // Expand marker instances
   resolvePatterns: true,     // Expand pattern fills to geometry
@@ -46,6 +51,9 @@ const DEFAULT_OPTIONS = {
   bakeGradients: true,       // Bake gradientTransform into gradient coords
   removeUnusedDefs: true,    // Remove defs that are no longer referenced
   preserveIds: false,        // Keep original IDs on expanded elements
+  // NOTE: Verification is ALWAYS enabled - precision is non-negotiable
+  // E2E verification tolerance (configurable for different accuracy needs)
+  e2eTolerance: '1e-10',     // Default: 1e-10 (very tight with high clipSegments)
 };
 
 /**
@@ -77,6 +85,19 @@ export function flattenSVG(svgString, options = {}) {
     gradientsProcessed: 0,
     defsRemoved: 0,
     errors: [],
+    // Verification results - ALWAYS enabled (precision is non-negotiable)
+    verifications: {
+      transforms: [],
+      matrices: [],
+      polygons: [],
+      gradients: [],
+      e2e: [], // End-to-end verification: area conservation, union reconstruction
+      passed: 0,
+      failed: 0,
+      allPassed: true,
+    },
+    // Store outside fragments from clipping for potential reconstruction
+    clipOutsideFragments: [],
   };
 
   try {
@@ -120,21 +141,21 @@ export function flattenSVG(svgString, options = {}) {
 
     // Step 5: Apply clipPaths (boolean intersection)
     if (opts.resolveClipPaths) {
-      const result = applyAllClipPaths(root, defsMap, opts);
+      const result = applyAllClipPaths(root, defsMap, opts, stats);
       stats.clipPathsApplied = result.count;
       stats.errors.push(...result.errors);
     }
 
     // Step 6: Flatten transforms (bake into coordinates)
     if (opts.flattenTransforms) {
-      const result = flattenAllTransforms(root, opts);
+      const result = flattenAllTransforms(root, opts, stats);
       stats.transformsFlattened = result.count;
       stats.errors.push(...result.errors);
     }
 
     // Step 7: Bake gradient transforms
     if (opts.bakeGradients) {
-      const result = bakeAllGradientTransforms(root, opts);
+      const result = bakeAllGradientTransforms(root, opts, stats);
       stats.gradientsProcessed = result.count;
       stats.errors.push(...result.errors);
     }
@@ -430,12 +451,21 @@ function resolveAllMasks(root, defsMap, opts) {
 
 /**
  * Apply clipPath references by performing boolean intersection.
+ * Also computes the difference (outside parts) and verifies area conservation (E2E).
  * @private
  */
-function applyAllClipPaths(root, defsMap, opts) {
+function applyAllClipPaths(root, defsMap, opts, stats) {
   const errors = [];
   let count = 0;
 
+  // Initialize E2E verification tracking in stats
+  if (!stats.verifications.e2e) {
+    stats.verifications.e2e = [];
+  }
+  if (!stats.clipOutsideFragments) {
+    stats.clipOutsideFragments = []; // Store outside fragments for potential reconstruction
+  }
+
   const elementsWithClip = findElementsWithAttribute(root, 'clip-path');
 
   for (const el of elementsWithClip) {
@@ -466,13 +496,75 @@ function applyAllClipPaths(root, defsMap, opts) {
 
       if (!clipPathData) continue;
 
-      // Convert to polygons
-      const origPolygon = ClipPathResolver.pathToPolygon(origPathData, opts.curveSegments);
-      const clipPolygon = ClipPathResolver.pathToPolygon(clipPathData, opts.curveSegments);
+      // Convert to polygons using higher segment count for clip accuracy
+      // clipSegments (default 64) provides better curve approximation for E2E verification
+      const clipSegs = opts.clipSegments || 64;
+      const origPolygon = ClipPathResolver.pathToPolygon(origPathData, clipSegs);
+      const clipPolygon = ClipPathResolver.pathToPolygon(clipPathData, clipSegs);
 
-      // Perform intersection
+      // Perform intersection (clipped result - what's kept)
       const clippedPolygon = intersectPolygons(origPolygon, clipPolygon);
 
+      // Convert polygon arrays to proper format for verification
+      const origForVerify = origPolygon.map(p => ({
+        x: p.x instanceof Decimal ? p.x : D(p.x),
+        y: p.y instanceof Decimal ? p.y : D(p.y)
+      }));
+      const clipForVerify = clipPolygon.map(p => ({
+        x: p.x instanceof Decimal ? p.x : D(p.x),
+        y: p.y instanceof Decimal ? p.y : D(p.y)
+      }));
+
+      // VERIFICATION: Verify polygon intersection is valid (ALWAYS runs)
+      if (clippedPolygon && clippedPolygon.length > 2) {
+        const clippedForVerify = clippedPolygon.map(p => ({
+          x: p.x instanceof Decimal ? p.x : D(p.x),
+          y: p.y instanceof Decimal ? p.y : D(p.y)
+        }));
+
+        const polyResult = Verification.verifyPolygonIntersection(origForVerify, clipForVerify, clippedForVerify);
+        stats.verifications.polygons.push({
+          element: el.tagName,
+          clipPathId: refId,
+          ...polyResult
+        });
+        if (polyResult.valid) {
+          stats.verifications.passed++;
+        } else {
+          stats.verifications.failed++;
+          stats.verifications.allPassed = false;
+        }
+
+        // E2E VERIFICATION: Compute difference (outside parts) and verify area conservation
+        // This ensures: area(original) = area(clipped) + area(outside)
+        const outsideFragments = Verification.computePolygonDifference(origForVerify, clipForVerify);
+
+        // Store outside fragments (marked invisible) for potential reconstruction
+        stats.clipOutsideFragments.push({
+          elementId: el.getAttribute('id') || `clip-${count}`,
+          clipPathId: refId,
+          fragments: outsideFragments,
+          visible: false // These are the "thrown away" parts, stored invisibly
+        });
+
+        // E2E Verification: area(original) = area(clipped) + area(outside)
+        // Pass configurable tolerance (default 1e-10 with 64 clipSegments)
+        const e2eTolerance = opts.e2eTolerance || '1e-10';
+        const e2eResult = Verification.verifyClipPathE2E(origForVerify, clippedForVerify, outsideFragments, e2eTolerance);
+        stats.verifications.e2e.push({
+          element: el.tagName,
+          clipPathId: refId,
+          type: 'clip-area-conservation',
+          ...e2eResult
+        });
+        if (e2eResult.valid) {
+          stats.verifications.passed++;
+        } else {
+          stats.verifications.failed++;
+          stats.verifications.allPassed = false;
+        }
+      }
+
       if (clippedPolygon && clippedPolygon.length > 2) {
         const clippedPath = ClipPathResolver.polygonToPathData(clippedPolygon, opts.precision);
 
@@ -510,7 +602,7 @@ function applyAllClipPaths(root, defsMap, opts) {
  * Flatten all transform attributes by baking into coordinates.
  * @private
  */
-function flattenAllTransforms(root, opts) {
+function flattenAllTransforms(root, opts, stats) {
   const errors = [];
   let count = 0;
 
@@ -524,21 +616,63 @@ function flattenAllTransforms(root, opts) {
       // Parse transform to matrix
       const ctm = SVGFlatten.parseTransformAttribute(transform);
 
+      // VERIFICATION: Verify matrix is invertible and well-formed (ALWAYS runs)
+      const matrixResult = Verification.verifyMatrixInversion(ctm);
+      stats.verifications.matrices.push({
+        element: el.tagName,
+        transform,
+        ...matrixResult
+      });
+      if (matrixResult.valid) {
+        stats.verifications.passed++;
+      } else {
+        stats.verifications.failed++;
+        stats.verifications.allPassed = false;
+      }
+
       // Get element path data
       const pathData = getElementPathData(el, opts.precision);
       if (!pathData) {
         // For groups, propagate transform to children
         if (el.tagName === 'g') {
-          propagateTransformToChildren(el, ctm, opts);
+          propagateTransformToChildren(el, ctm, opts, stats);
           el.removeAttribute('transform');
           count++;
         }
         continue;
       }
 
+      // VERIFICATION: Sample test points from original path for round-trip verification (ALWAYS runs)
+      let testPoints = [];
+      // Extract a few key points from the path for verification
+      const polygon = ClipPathResolver.pathToPolygon(pathData, 4);
+      if (polygon && polygon.length > 0) {
+        testPoints = polygon.slice(0, 4).map(p => ({
+          x: p.x instanceof Decimal ? p.x : D(p.x),
+          y: p.y instanceof Decimal ? p.y : D(p.y)
+        }));
+      }
+
       // Transform the path data
       const transformedPath = SVGFlatten.transformPathData(pathData, ctm, { precision: opts.precision });
 
+      // VERIFICATION: Verify transform round-trip accuracy for each test point (ALWAYS runs)
+      for (let i = 0; i < testPoints.length; i++) {
+        const pt = testPoints[i];
+        const rtResult = Verification.verifyTransformRoundTrip(ctm, pt.x, pt.y);
+        stats.verifications.transforms.push({
+          element: el.tagName,
+          pointIndex: i,
+          ...rtResult
+        });
+        if (rtResult.valid) {
+          stats.verifications.passed++;
+        } else {
+          stats.verifications.failed++;
+          stats.verifications.allPassed = false;
+        }
+      }
+
       // Update or replace element
       if (el.tagName === 'path') {
         el.setAttribute('d', transformedPath);
@@ -573,7 +707,7 @@ function flattenAllTransforms(root, opts) {
  * Propagate transform to all children of a group.
  * @private
  */
-function propagateTransformToChildren(group, ctm, opts) {
+function propagateTransformToChildren(group, ctm, opts, stats) {
   for (const child of [...group.children]) {
     if (!(child instanceof SVGElement)) continue;
 
@@ -599,6 +733,20 @@ function propagateTransformToChildren(group, ctm, opts) {
           combinedCtm = ctm.mul(childCtm);
         }
 
+        // VERIFICATION: Verify combined transform matrix (ALWAYS runs)
+        const matrixResult = Verification.verifyMatrixInversion(combinedCtm);
+        stats.verifications.matrices.push({
+          element: child.tagName,
+          context: 'group-propagation',
+          ...matrixResult
+        });
+        if (matrixResult.valid) {
+          stats.verifications.passed++;
+        } else {
+          stats.verifications.failed++;
+          stats.verifications.allPassed = false;
+        }
+
         const transformedPath = SVGFlatten.transformPathData(pathData, combinedCtm, { precision: opts.precision });
 
         if (child.tagName === 'path') {
@@ -627,7 +775,7 @@ function propagateTransformToChildren(group, ctm, opts) {
  * Bake gradientTransform into gradient coordinates.
  * @private
  */
-function bakeAllGradientTransforms(root, opts) {
+function bakeAllGradientTransforms(root, opts, stats) {
   const errors = [];
   let count = 0;
 
@@ -649,6 +797,24 @@ function bakeAllGradientTransforms(root, opts) {
       const [tx1, ty1] = Transforms2D.applyTransform(ctm, x1, y1);
       const [tx2, ty2] = Transforms2D.applyTransform(ctm, x2, y2);
 
+      // VERIFICATION: Verify linear gradient transform (ALWAYS runs)
+      const gradResult = Verification.verifyLinearGradientTransform(
+        { x1, y1, x2, y2 },
+        { x1: tx1.toNumber(), y1: ty1.toNumber(), x2: tx2.toNumber(), y2: ty2.toNumber() },
+        ctm
+      );
+      stats.verifications.gradients.push({
+        gradientId: grad.getAttribute('id') || 'unknown',
+        type: 'linear',
+        ...gradResult
+      });
+      if (gradResult.valid) {
+        stats.verifications.passed++;
+      } else {
+        stats.verifications.failed++;
+        stats.verifications.allPassed = false;
+      }
+
       grad.setAttribute('x1', tx1.toFixed(opts.precision));
       grad.setAttribute('y1', ty1.toFixed(opts.precision));
       grad.setAttribute('x2', tx2.toFixed(opts.precision));

package/src/geometry-to-path.js

@@ -3,6 +3,11 @@ import { Matrix } from './matrix.js';
 
 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%
+ */
 export function getKappa() {
   const two = new Decimal(2);
   const three = new Decimal(3);
@@ -10,6 +15,137 @@ export function getKappa() {
   return four.mul(two.sqrt().minus(1)).div(three);
 }
 
+/**
+ * Compute the optimal Bezier control point distance for any arc angle.
+ * Formula: L = (4/3) * tan(theta/4) where theta is in radians
+ *
+ * This is the generalization of the kappa constant.
+ * For 90° (π/2): L = (4/3) * tan(π/8) ≈ 0.5522847498 (standard kappa)
+ *
+ * References:
+ * - Spencer Mortensen's optimal Bezier circle approximation:
+ *   https://spencermortensen.com/articles/bezier-circle/
+ *   Derives the optimal kappa for minimizing radial error in quarter-circle arcs.
+ *
+ * - Akhil's ellipse approximation with π/4 step angle:
+ *   https://www.blog.akhil.cc/ellipse
+ *   Shows that π/4 (45°) is the optimal step angle for Bezier arc approximation,
+ *   based on Maisonobe's derivation. This allows precomputing the alpha coefficient.
+ *
+ * - Math Stack Exchange derivation:
+ *   https://math.stackexchange.com/questions/873224
+ *   General formula for control point distance for any arc angle.
+ *
+ * @param {Decimal|number} thetaRadians - Arc angle in radians
+ * @returns {Decimal} Control point distance factor (multiply by radius)
+ */
+export function getKappaForArc(thetaRadians) {
+  const theta = D(thetaRadians);
+  const four = new Decimal(4);
+  const three = new Decimal(3);
+  // L = (4/3) * tan(theta/4)
+  return four.div(three).mul(Decimal.tan(theta.div(four)));
+}
+
+/**
+ * High-precision circle to path using N Bezier arcs.
+ * More arcs = better approximation of the true circle.
+ *
+ * IMPORTANT: Arc count should be a multiple of 4 (for symmetry) and ideally
+ * a multiple of 8 (for optimal π/4 step angle as per Maisonobe's derivation).
+ * Reference: https://www.blog.akhil.cc/ellipse
+ *
+ * Error analysis (measured):
+ * - 4 arcs (90° = π/2 each): ~0.027% max radial error (standard)
+ * - 8 arcs (45° = π/4 each): ~0.0004% max radial error (optimal base)
+ * - 16 arcs (22.5° = π/8 each): ~0.000007% max radial error
+ * - 32 arcs (11.25° = π/16 each): ~0.0000004% max radial error
+ * - 64 arcs (5.625° = π/32 each): ~0.00000001% max radial error
+ *
+ * @param {number|Decimal} cx - Center X
+ * @param {number|Decimal} cy - Center Y
+ * @param {number|Decimal} r - Radius
+ * @param {number} arcs - Number of Bezier arcs (must be multiple of 4; 8, 16, 32, 64 recommended)
+ * @param {number} precision - Decimal precision for output
+ * @returns {string} SVG path data
+ */
+export function circleToPathDataHP(cx, cy, r, arcs = 8, precision = 6) {
+  return ellipseToPathDataHP(cx, cy, r, r, arcs, precision);
+}
+
+/**
+ * High-precision ellipse to path using N Bezier arcs.
+ * More arcs = better approximation of the true ellipse.
+ *
+ * Arc count must be a multiple of 4 for proper symmetry.
+ * Multiples of 8 are optimal (π/4 step angle per Maisonobe).
+ *
+ * @param {number|Decimal} cx - Center X
+ * @param {number|Decimal} cy - Center Y
+ * @param {number|Decimal} rx - Radius X
+ * @param {number|Decimal} ry - Radius Y
+ * @param {number} arcs - Number of Bezier arcs (must be multiple of 4; 8, 16, 32, 64 recommended)
+ * @param {number} precision - Decimal precision for output
+ * @returns {string} SVG path data
+ */
+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;
+  }
+  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);
+
+  // Control point distance for this arc angle
+  const kappa = getKappaForArc(arcAngle);
+
+  // Generate path
+  const commands = [];
+
+  for (let i = 0; i < arcs; i++) {
+    const startAngle = arcAngle.mul(i);
+    const endAngle = arcAngle.mul(i + 1);
+
+    // Start and end points on ellipse
+    const cosStart = Decimal.cos(startAngle);
+    const sinStart = Decimal.sin(startAngle);
+    const cosEnd = Decimal.cos(endAngle);
+    const sinEnd = Decimal.sin(endAngle);
+
+    const x0 = cxD.plus(rxD.mul(cosStart));
+    const y0 = cyD.plus(ryD.mul(sinStart));
+    const x3 = cxD.plus(rxD.mul(cosEnd));
+    const y3 = cyD.plus(ryD.mul(sinEnd));
+
+    // Tangent vectors at start and end (perpendicular to radius, scaled by kappa)
+    // 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 x1 = x0.plus(kappa.mul(rxD).mul(tx0));
+    const y1 = y0.plus(kappa.mul(ryD).mul(ty0));
+    const x2 = x3.minus(kappa.mul(rxD).mul(tx3));
+    const y2 = y3.minus(kappa.mul(ryD).mul(ty3));
+
+    if (i === 0) {
+      commands.push(`M ${f(x0)} ${f(y0)}`);
+    }
+    commands.push(`C ${f(x1)} ${f(y1)} ${f(x2)} ${f(y2)} ${f(x3)} ${f(y3)}`);
+  }
+
+  commands.push('Z');
+  return commands.join(' ');
+}
+
 function formatNumber(value, precision = 6) {
   // Use toFixed to preserve trailing zeros for consistent output formatting
   return value.toFixed(precision);

package/src/index.js

@@ -46,6 +46,7 @@ import * as MeshGradient from './mesh-gradient.js';
 import * as TextToPath from './text-to-path.js';
 import * as SVGParser from './svg-parser.js';
 import * as FlattenPipeline from './flatten-pipeline.js';
+import * as Verification from './verification.js';
 import { Logger, LogLevel, setLogLevel, getLogLevel as getLoggerLevel, enableFileLogging, disableFileLogging } from './logger.js';
 
 // Set high-precision default (80 significant digits) on module load
@@ -91,7 +92,7 @@ export { SVGFlatten, BrowserVerify };
 export { ClipPathResolver, MaskResolver, PatternResolver };
 export { UseSymbolResolver, MarkerResolver };
 export { MeshGradient, TextToPath };
-export { SVGParser, FlattenPipeline };
+export { SVGParser, FlattenPipeline, Verification };
 
 // ============================================================================
 // LOGGING: Configurable logging control
@@ -426,6 +427,7 @@ export default {
   TextToPath,
   SVGParser,
   FlattenPipeline,
+  Verification,
 
   // Logging
   Logger,