@emasoft/svg-matrix 1.0.4 → 1.0.6

package/README.md

@@ -1,413 +1,450 @@
 # @emasoft/svg-matrix
 
-Arbitrary-precision matrix, vector and affine transformation library for JavaScript using decimal.js.
+High-precision matrix, vector, and SVG transformation library for JavaScript. Built on decimal.js for 80-digit precision arithmetic.
 
 ## Features
 
-- **Decimal-backed** Matrix and Vector classes for high-precision geometry
-- **2D transforms** (3x3 homogeneous matrices): translation, rotation, scale, skew, reflection
-- **3D transforms** (4x4 homogeneous matrices): translation, rotation (X/Y/Z axis), scale, reflection
-- **SVG transform flattening**: parse transform attributes, build CTMs, flatten nested hierarchies
-- **Linear algebra**: LU/QR decomposition, determinant, inverse, solve, matrix exponential
-- **10^77 times better precision** than JavaScript floats for round-trip transforms
-- Works in **Node.js** and **browsers** (via CDN)
+**Linear Algebra**
+- Matrix and Vector classes with full linear algebra operations
+- LU/QR decomposition, determinant, inverse, solve, matrix exponential
 
-## Installation
+**Affine Transforms**
+- 2D (3x3 homogeneous): translation, rotation, scale, skew, reflection
+- 3D (4x4 homogeneous): translation, rotation (X/Y/Z/arbitrary axis), scale
+
+**SVG Processing**
+- Transform attribute parsing and CTM (Current Transform Matrix) building
+- viewBox, preserveAspectRatio, nested viewports, unit resolution
+- Shape-to-path conversion (circle, ellipse, rect, line, polygon, polyline)
+- Path parsing, normalization (absolute, cubics), transformation
+
+**SVG Element Resolution**
+- ClipPath flattening to polygons
+- Mask resolution (luminance and alpha)
+- Pattern tiling expansion
+- Use/symbol inlining with proper transforms
+- Marker positioning and orientation
+
+**Advanced**
+- Polygon boolean operations (intersection, union, difference, convex hull)
+- SVG 2.0 mesh gradient parsing and rasterization
+- Text-to-path conversion with font support
+- Browser verification against Chrome's native W3C SVG2 implementation
+
+## Precision
+
+| Scenario | Float Error | This Library | Improvement |
+|----------|-------------|--------------|-------------|
+| GIS/CAD coordinates (1e6+ scale) | 1.69e-7 | 0 | 10^93x |
+| 6-level SVG hierarchy | 1.14e-13 | 1e-77 | 10^64x |
+| 1000 round-trip transforms | 5.41e-14 | 0 | 10^86x |
 
-### npm
+**When precision matters:** GIS, CAD, scientific visualization, deep transform hierarchies, accumulated operations.
+
+**When floats suffice:** Simple transforms, small coordinates, visual applications where sub-pixel errors are imperceptible.
+
+```bash
+node test/benchmark-precision.js
+```
+
+## Installation
 
 ```bash
 npm install @emasoft/svg-matrix
 ```
 
 ```js
-import { Decimal, Matrix, Vector, Transforms2D, Transforms3D, SVGFlatten } from '@emasoft/svg-matrix';
+import { Matrix, Vector, Transforms2D, Transforms3D, SVGFlatten } from '@emasoft/svg-matrix';
 ```
 
-### CDN (Browser)
-
-Using esm.sh (recommended - auto-resolves dependencies):
+### CDN
 
 ```html
 <script type="module">
-  import { Decimal, Matrix, Vector, Transforms2D, Transforms3D, SVGFlatten } from 'https://esm.sh/@emasoft/svg-matrix';
+  import { Matrix, Vector, Transforms2D } from 'https://esm.sh/@emasoft/svg-matrix';
+</script>
+```
 
-  Decimal.set({ precision: 80 });
+## Quick Start
 
-  // Create and compose 2D transforms
-  const M = Transforms2D.translation(2, 3)
-    .mul(Transforms2D.rotate(Math.PI / 4))
-    .mul(Transforms2D.scale(1.5));
+```js
+import { Decimal, Matrix, Vector, Transforms2D, SVGFlatten } from '@emasoft/svg-matrix';
 
-  // Apply to a point
-  const [x, y] = Transforms2D.applyTransform(M, 1, 0);
-  console.log('Transformed:', x.toString(), y.toString());
-</script>
-```
+Decimal.set({ precision: 80 });
 
-Using Skypack:
+// Compose transforms (right-to-left: scale first, then rotate, then translate)
+const M = Transforms2D.translation(10, 20)
+  .mul(Transforms2D.rotate(Math.PI / 4))
+  .mul(Transforms2D.scale(2));
 
-```html
-<script type="module">
-  import { Matrix, Vector } from 'https://cdn.skypack.dev/@emasoft/svg-matrix';
-</script>
+// Apply to point
+const [x, y] = Transforms2D.applyTransform(M, 1, 0);
+
+// Round-trip with inverse
+const [xBack, yBack] = Transforms2D.applyTransform(M.inverse(), x, y);
 ```
 
-Using import maps:
+---
 
-```html
-<script type="importmap">
-{
-  "imports": {
-    "@emasoft/svg-matrix": "https://esm.sh/@emasoft/svg-matrix"
-  }
-}
-</script>
-<script type="module">
-  import { Matrix, Vector, Transforms2D } from '@emasoft/svg-matrix';
-</script>
-```
+## API Reference
 
-## Usage Examples
+### Linear Algebra
 
-### Vector Operations
+#### Vector
 
 ```js
-import { Vector, Decimal } from '@emasoft/svg-matrix';
-
-Decimal.set({ precision: 80 });
+import { Vector } from '@emasoft/svg-matrix';
 
 const v = Vector.from([1, 2, 3]);
 const w = Vector.from([4, 5, 6]);
 
-// Basic operations
-console.log('Add:', v.add(w).toNumberArray());       // [5, 7, 9]
-console.log('Scale:', v.scale(2).toNumberArray());   // [2, 4, 6]
-console.log('Dot:', v.dot(w).toString());            // 32
-console.log('Cross:', v.cross(w).toNumberArray());   // [-3, 6, -3]
-
-// Geometry
-console.log('Norm:', v.norm().toString());           // 3.7416...
-console.log('Normalized:', v.normalize().toNumberArray());
-console.log('Angle:', v.angleBetween(w).toString()); // radians
-
-// Projection
-const proj = v.projectOnto(w);
-console.log('Projection:', proj.toNumberArray());
+v.add(w)              // Element-wise addition
+v.sub(w)              // Element-wise subtraction
+v.scale(2)            // Scalar multiplication
+v.dot(w)              // Dot product → Decimal
+v.cross(w)            // Cross product (3D)
+v.norm()              // Euclidean length
+v.normalize()         // Unit vector
+v.angleBetween(w)     // Angle in radians
+v.projectOnto(w)      // Vector projection
+v.orthogonal()        // Perpendicular vector
+v.distance(w)         // Euclidean distance
+v.toNumberArray()     // [1, 2, 3]
 ```
 
-### Matrix Operations
+#### Matrix
 
 ```js
 import { Matrix } from '@emasoft/svg-matrix';
 
 const A = Matrix.from([[1, 2], [3, 4]]);
-const B = Matrix.from([[5, 6], [7, 8]]);
+const I = Matrix.identity(3);
+const Z = Matrix.zeros(2, 3);
+
+A.add(B)              // Element-wise addition
+A.sub(B)              // Element-wise subtraction
+A.mul(B)              // Matrix multiplication
+A.transpose()         // Transpose
+A.trace()             // Sum of diagonal
+A.determinant()       // Determinant
+A.inverse()           // Matrix inverse
+A.solve([1, 1])       // Solve Ax = b
+A.lu()                // { L, U, P } decomposition
+A.qr()                // { Q, R } decomposition
+A.exp()               // Matrix exponential
+A.applyToVector(v)    // Matrix-vector product
+```
 
-// Basic operations
-console.log('Multiply:', A.mul(B).toNumberArray());
-console.log('Transpose:', A.transpose().toNumberArray());
-console.log('Determinant:', A.determinant().toString());  // -2
-console.log('Trace:', A.trace().toString());              // 5
+### Transforms
 
-// Linear algebra
-const inv = A.inverse();
-console.log('Inverse:', inv.toNumberArray());
+#### 2D (3x3 matrices)
 
-// Solve Ax = b
-const x = A.solve([1, 1]);
-console.log('Solution:', x.toNumberArray());
+```js
+import { Transforms2D } from '@emasoft/svg-matrix';
 
-// Decompositions
-const { L, U, P } = A.lu();
-const { Q, R } = A.qr();
+Transforms2D.translation(tx, ty)
+Transforms2D.scale(sx, sy)              // sy defaults to sx
+Transforms2D.rotate(theta)              // radians
+Transforms2D.rotateAroundPoint(theta, px, py)
+Transforms2D.skew(ax, ay)
+Transforms2D.stretchAlongAxis(ux, uy, k)
+Transforms2D.reflectX()                 // flip across X axis
+Transforms2D.reflectY()                 // flip across Y axis
+Transforms2D.reflectOrigin()
 
-// Matrix exponential
-const expA = A.exp();
+// Apply to point
+const [x, y] = Transforms2D.applyTransform(matrix, px, py);
 ```
 
-### 2D Transforms
+#### 3D (4x4 matrices)
 
 ```js
-import { Transforms2D } from '@emasoft/svg-matrix';
+import { Transforms3D } from '@emasoft/svg-matrix';
 
-// Basic transforms
-const T = Transforms2D.translation(10, 20);
-const R = Transforms2D.rotate(Math.PI / 4);        // 45 degrees
-const S = Transforms2D.scale(2, 3);                // non-uniform
-const Su = Transforms2D.scale(2);                  // uniform
+Transforms3D.translation(tx, ty, tz)
+Transforms3D.scale(sx, sy, sz)
+Transforms3D.rotateX(theta)
+Transforms3D.rotateY(theta)
+Transforms3D.rotateZ(theta)
+Transforms3D.rotateAroundAxis(ux, uy, uz, theta)
+Transforms3D.rotateAroundPoint(ux, uy, uz, theta, px, py, pz)
+Transforms3D.reflectXY()                // flip Z
+Transforms3D.reflectXZ()                // flip Y
+Transforms3D.reflectYZ()                // flip X
+
+const [x, y, z] = Transforms3D.applyTransform(matrix, px, py, pz);
+```
 
-// Rotation around a point
-const Rp = Transforms2D.rotateAroundPoint(Math.PI / 2, 5, 5);
+### SVG Processing
 
-// Skew and stretch
-const Sk = Transforms2D.skew(0.5, 0);
-const St = Transforms2D.stretchAlongAxis(1, 0, 2); // stretch 2x along X
+#### SVGFlatten - Transform Parsing & CTM
 
-// Reflections
-const Rx = Transforms2D.reflectX();      // flip Y
-const Ry = Transforms2D.reflectY();      // flip X
-const Ro = Transforms2D.reflectOrigin(); // flip both
+```js
+import { SVGFlatten } from '@emasoft/svg-matrix';
+
+// Parse transform attributes
+const m = SVGFlatten.parseTransformAttribute('translate(50,50) rotate(45) scale(2)');
 
-// Compose transforms (right-to-left: S first, then R, then T)
-const M = T.mul(R).mul(S);
+// Build CTM from transform stack
+const ctm = SVGFlatten.buildCTM([
+  'scale(1.5)',
+  'translate(-13.6, -10.2)',
+  'rotate(15)',
+  'matrix(0.716, 0, 0, 1.397, 0, 0)'
+]);
 
 // Apply to point
-const [x, y] = Transforms2D.applyTransform(M, 1, 0);
+const { x, y } = SVGFlatten.applyToPoint(ctm, 10, 10);
+
+// Transform path data
+const transformed = SVGFlatten.transformPathData('M 100 100 L 200 200', ctm);
+
+// viewBox handling
+const viewBox = SVGFlatten.parseViewBox('0 0 100 100');
+const par = SVGFlatten.parsePreserveAspectRatio('xMidYMid meet');
+const vbTransform = SVGFlatten.computeViewBoxTransform(viewBox, 800, 600, par);
+
+// Full CTM with viewBox + nested transforms
+const fullCtm = SVGFlatten.buildFullCTM([
+  { type: 'svg', width: 800, height: 600, viewBox: '0 0 400 300' },
+  { type: 'g', transform: 'translate(50, 50)' },
+  { type: 'g', transform: 'rotate(45)' },
+  { type: 'element', transform: 'scale(2)' }
+]);
+
+// Unit resolution (px, %, em, pt, in, cm, mm, pc)
+SVGFlatten.resolveLength('50%', 800);   // → 400
+SVGFlatten.resolveLength('1in', 800);   // → 96
+
+// objectBoundingBox transform
+const bboxTransform = SVGFlatten.objectBoundingBoxTransform(100, 50, 200, 100);
+```
+
+#### GeometryToPath - Shape Conversion
 
-// Inverse transform
-const Minv = M.inverse();
-const [xBack, yBack] = Transforms2D.applyTransform(Minv, x, y);
+```js
+import { GeometryToPath } from '@emasoft/svg-matrix';
+
+// Shape to path
+GeometryToPath.circleToPathData(cx, cy, r, precision)
+GeometryToPath.ellipseToPathData(cx, cy, rx, ry, precision)
+GeometryToPath.rectToPathData(x, y, w, h, rx, ry, useArcs, precision)
+GeometryToPath.lineToPathData(x1, y1, x2, y2, precision)
+GeometryToPath.polylineToPathData(points, precision)
+GeometryToPath.polygonToPathData(points, precision)
+GeometryToPath.convertElementToPath(element, precision)
+
+// Path manipulation
+GeometryToPath.parsePathData(pathData)          // → [{command, args}]
+GeometryToPath.pathArrayToString(commands)      // → path string
+GeometryToPath.pathToAbsolute(pathData)         // relative → absolute
+GeometryToPath.pathToCubics(pathData)           // all → cubic Beziers
+GeometryToPath.transformPathData(pathData, matrix, precision)
+
+// Bezier kappa constant: 4*(sqrt(2)-1)/3
+GeometryToPath.getKappa()
 ```
 
-### 3D Transforms
+#### BrowserVerify - Chrome Verification
 
 ```js
-import { Transforms3D } from '@emasoft/svg-matrix';
+import { BrowserVerify } from '@emasoft/svg-matrix';
+
+// One-off verification
+await BrowserVerify.verifyViewBox(800, 600, '0 0 400 300', 'xMidYMid meet');
+await BrowserVerify.verifyTransform('rotate(45) translate(100, 50) scale(2)');
+
+// Session-based verification
+const verifier = new BrowserVerify.BrowserVerifier();
+await verifier.init({ headless: true });
+await verifier.verifyViewBoxTransform(800, 600, '0 0 100 100');
+await verifier.verifyMatrix(ctm, { width: 100, height: 100, transform: '...' });
+await verifier.verifyPointTransform(ctm, 10, 20, config);
+await verifier.close();
+
+// Standard test suite (28 tests including W3C issue #215 cases)
+await BrowserVerify.runStandardTests({ verbose: true });
+```
 
-// Basic transforms
-const T = Transforms3D.translation(1, 2, 3);
-const S = Transforms3D.scale(2, 2, 2);
+### Polygon Operations
 
-// Axis rotations (radians, right-hand rule)
-const Rx = Transforms3D.rotateX(Math.PI / 2);
-const Ry = Transforms3D.rotateY(Math.PI / 4);
-const Rz = Transforms3D.rotateZ(Math.PI / 6);
+#### PolygonClip
 
-// Rotation around arbitrary axis
-const Raxis = Transforms3D.rotateAroundAxis(1, 1, 0, Math.PI / 3);
+```js
+import { PolygonClip } from '@emasoft/svg-matrix';
 
-// Rotation around a point
-const Rpt = Transforms3D.rotateAroundPoint(0, 0, 1, Math.PI / 2, 5, 5, 0);
+const square = [
+  PolygonClip.point(0, 0),
+  PolygonClip.point(2, 0),
+  PolygonClip.point(2, 2),
+  PolygonClip.point(0, 2)
+];
 
-// Reflections
-const RfXY = Transforms3D.reflectXY();     // flip Z
-const RfXZ = Transforms3D.reflectXZ();     // flip Y
-const RfYZ = Transforms3D.reflectYZ();     // flip X
-const RfO = Transforms3D.reflectOrigin();  // flip all
+// Boolean operations
+PolygonClip.polygonIntersection(poly1, poly2)
+PolygonClip.polygonUnion(poly1, poly2)
+PolygonClip.polygonDifference(poly1, poly2)
 
-// Compose and apply
-const M = T.mul(Rx).mul(S);
-const [x, y, z] = Transforms3D.applyTransform(M, 1, 0, 0);
+// Properties
+PolygonClip.polygonArea(polygon)
+PolygonClip.isCounterClockwise(polygon)
+PolygonClip.isConvex(polygon)
+PolygonClip.pointInPolygon(point, polygon)  // 1=inside, 0=boundary, -1=outside
+
+// Convex hull
+PolygonClip.convexHull(points)
+
+// Bounding box
+PolygonClip.boundingBox(polygon)  // {minX, minY, maxX, maxY}
+PolygonClip.bboxIntersects(bbox1, bbox2)
 ```
 
-## API Reference
+#### ClipPathResolver
 
-### Vector
-
-| Method | Description |
-|--------|-------------|
-| `Vector.from(arr)` | Create vector from array |
-| `add(v)` | Element-wise addition |
-| `sub(v)` | Element-wise subtraction |
-| `scale(s)` | Scalar multiplication |
-| `negate()` | Negate all components |
-| `dot(v)` | Dot product |
-| `cross(v)` | Cross product (3D only) |
-| `outer(v)` | Outer product (returns 2D array) |
-| `norm()` | Euclidean length |
-| `normalize()` | Unit vector |
-| `angleBetween(v)` | Angle in radians |
-| `projectOnto(v)` | Vector projection |
-| `orthogonal()` | Perpendicular vector |
-| `distance(v)` | Euclidean distance |
-| `equals(v, tol?)` | Equality check with optional tolerance |
-| `toArray()` | Get Decimal array |
-| `toNumberArray()` | Get number array |
-| `toStringArray()` | Get string array |
-
-### Matrix
-
-| Method | Description |
-|--------|-------------|
-| `Matrix.from(arr)` | Create from 2D array |
-| `Matrix.zeros(r, c)` | Zero matrix |
-| `Matrix.identity(n)` | Identity matrix |
-| `add(M)` | Element-wise addition |
-| `sub(M)` | Element-wise subtraction |
-| `mul(M)` | Matrix multiplication |
-| `div(s)` | Scalar division |
-| `negate()` | Negate all elements |
-| `transpose()` | Transpose |
-| `trace()` | Sum of diagonal |
-| `determinant()` | Determinant |
-| `inverse()` | Matrix inverse |
-| `solve(b)` | Solve Ax = b |
-| `lu()` | LU decomposition |
-| `qr()` | QR decomposition |
-| `exp()` | Matrix exponential |
-| `applyToVector(v)` | Matrix-vector product |
-| `equals(M, tol?)` | Equality check |
-| `isSquare()` | Check if square |
-| `toNumberArray()` | Get number 2D array |
-| `toArrayOfStrings()` | Get string 2D array |
-
-### Transforms2D
-
-| Function | Description |
-|----------|-------------|
-| `translation(tx, ty)` | Translation matrix |
-| `scale(sx, sy?)` | Scale matrix (uniform if sy omitted) |
-| `rotate(theta)` | Rotation matrix (radians) |
-| `rotateAroundPoint(theta, px, py)` | Rotation around point |
-| `skew(ax, ay)` | Skew/shear matrix |
-| `stretchAlongAxis(ux, uy, k)` | Stretch along direction |
-| `reflectX()` | Reflect across X axis |
-| `reflectY()` | Reflect across Y axis |
-| `reflectOrigin()` | Reflect through origin |
-| `applyTransform(M, x, y)` | Apply matrix to point |
-
-### Transforms3D
-
-| Function | Description |
-|----------|-------------|
-| `translation(tx, ty, tz)` | Translation matrix |
-| `scale(sx, sy?, sz?)` | Scale matrix |
-| `rotateX(theta)` | Rotation around X axis |
-| `rotateY(theta)` | Rotation around Y axis |
-| `rotateZ(theta)` | Rotation around Z axis |
-| `rotateAroundAxis(ux, uy, uz, theta)` | Rotation around arbitrary axis |
-| `rotateAroundPoint(ux, uy, uz, theta, px, py, pz)` | Rotation around point |
-| `reflectXY()` | Reflect across XY plane |
-| `reflectXZ()` | Reflect across XZ plane |
-| `reflectYZ()` | Reflect across YZ plane |
-| `reflectOrigin()` | Reflect through origin |
-| `applyTransform(M, x, y, z)` | Apply matrix to point |
-
-### SVGFlatten
-
-| Function | Description |
-|----------|-------------|
-| `parseTransformFunction(func, args)` | Parse a single SVG transform function |
-| `parseTransformAttribute(str)` | Parse a full SVG transform attribute string |
-| `buildCTM(transformStack)` | Build CTM from array of transform strings |
-| `applyToPoint(ctm, x, y)` | Apply CTM to a 2D point |
-| `toSVGMatrix(ctm, precision?)` | Convert CTM back to SVG matrix() notation |
-| `isIdentity(m, tolerance?)` | Check if matrix is effectively identity |
-| `transformPathData(pathD, ctm)` | Transform path data coordinates |
-| `PRECISION_INFO` | Object with precision comparison data |
-
-## SVG Transform Flattening
-
-The `SVGFlatten` module provides tools for parsing SVG transform attributes, building CTMs (Current Transform Matrices), and flattening nested transforms with arbitrary precision.
-
-### Why Use SVGFlatten?
-
-SVG elements can have deeply nested transforms through parent groups. When coordinates are transformed from local space to viewport and back using JavaScript's native 64-bit floats, precision is lost:
+```js
+import { ClipPathResolver } from '@emasoft/svg-matrix';
 
-```
-Original coordinates:     (10, 10)
-After round-trip (float): (9.9857, 9.9857)  // Error: 0.0143
-```
+// Parse and resolve clipPath
+const clipData = ClipPathResolver.parseClipPathElement(element);
+const clipPolygon = ClipPathResolver.resolveClipPath(clipData, targetBBox);
 
-With `@emasoft/svg-matrix` using 80-digit Decimal precision:
+// Shape to polygon
+ClipPathResolver.shapeToPolygon({ type: 'circle', cx: 100, cy: 100, r: 50 }, { samples: 32 })
+ClipPathResolver.pathToPolygon(pathData, { samples: 20 })
+ClipPathResolver.polygonToPathData(polygon)
 
-```
-Original coordinates:     (10, 10)
-After round-trip:         (10.00000000000000000000000000000000000000,
-                           9.999999999999999999999999999999999999999999999999999999999999999999999999999999998)
-Round-trip error:         X=0, Y=2e-79
+// Apply clipPath to element
+ClipPathResolver.applyClipPath(elementData, clipPathData, targetBBox)
 ```
 
-**Improvement: 10^77 times better precision than JavaScript floats.**
+### SVG Element Resolution
 
-### Parsing SVG Transforms
+#### UseSymbolResolver
 
 ```js
-import { SVGFlatten } from '@emasoft/svg-matrix';
+import { UseSymbolResolver } from '@emasoft/svg-matrix';
 
-// Parse individual transforms
-const m1 = SVGFlatten.parseTransformAttribute('translate(10, 20)');
-const m2 = SVGFlatten.parseTransformAttribute('rotate(45)');
-const m3 = SVGFlatten.parseTransformAttribute('scale(2, 0.5)');
-const m4 = SVGFlatten.parseTransformAttribute('skewX(15)');
-const m5 = SVGFlatten.parseTransformAttribute('matrix(0.866, 0.5, -0.5, 0.866, 0, 0)');
-
-// Parse chained transforms
-const combined = SVGFlatten.parseTransformAttribute('translate(50,50) rotate(45) scale(2)');
+const useData = UseSymbolResolver.parseUseElement(useElement);
+const symbolData = UseSymbolResolver.parseSymbolElement(symbolElement);
+const resolved = UseSymbolResolver.resolveUse(useData, svgDocument);
+const flattened = UseSymbolResolver.flattenResolvedUse(resolved);
+UseSymbolResolver.resolveAllUses(svgDocument)
 ```
 
-### Building CTM from Nested Elements
+#### MarkerResolver
 
 ```js
-import { Decimal, SVGFlatten } from '@emasoft/svg-matrix';
+import { MarkerResolver } from '@emasoft/svg-matrix';
 
-Decimal.set({ precision: 80 });
+const markerData = MarkerResolver.parseMarkerElement(markerElement);
+const vertices = MarkerResolver.getPathVertices(pathData);
+const transform = MarkerResolver.getMarkerTransform(markerData, vertex, angle, strokeWidth);
+const instances = MarkerResolver.resolveMarkers(pathD, { 'marker-start': m1, 'marker-end': m2, strokeWidth: 2 });
+MarkerResolver.markersToPathData(instances)
+```
 
-// Simulate a 6-level SVG hierarchy:
-// <svg viewBox="...">                              <!-- viewBox scaling -->
-//   <g transform="translate(-13.6,-10.2)">         <!-- g1 -->
-//     <g transform="translate(-1144.8,517.6)">     <!-- g2 -->
-//       <g transform="rotate(15)">                 <!-- g3 -->
-//         <g transform="scale(1.2, 0.8)">          <!-- g4 -->
-//           <path transform="matrix(...)"/>       <!-- element -->
-
-const transformStack = [
-  'scale(1.5)',                                    // viewBox scaling
-  'translate(-13.613145,-10.209854)',              // g1
-  'translate(-1144.8563,517.64642)',               // g2
-  'rotate(15)',                                    // g3
-  'scale(1.2, 0.8)',                               // g4
-  'matrix(0.71577068,0,0,1.3970955,0,0)'          // element
-];
+#### PatternResolver
 
-// Build combined CTM
-const ctm = SVGFlatten.buildCTM(transformStack);
+```js
+import { PatternResolver } from '@emasoft/svg-matrix';
+
+const patternData = PatternResolver.parsePatternElement(patternElement);
+const tiles = PatternResolver.resolvePattern(patternData, targetBBox);
+PatternResolver.applyPattern(elementData, patternData, targetBBox)
+PatternResolver.patternToClipPath(patternData, targetBBox)
+PatternResolver.patternToPathData(patternData, targetBBox)
+```
 
-// Transform a point from local to viewport coordinates
-const local = { x: new Decimal('10'), y: new Decimal('10') };
-const viewport = SVGFlatten.applyToPoint(ctm, local.x, local.y);
+#### MaskResolver
 
-// Transform back to local coordinates
-const inverseCTM = ctm.inverse();
-const recovered = SVGFlatten.applyToPoint(inverseCTM, viewport.x, viewport.y);
+```js
+import { MaskResolver } from '@emasoft/svg-matrix';
 
-// Verify precision
-const errorX = recovered.x.minus(local.x).abs();
-const errorY = recovered.y.minus(local.y).abs();
-console.log('Round-trip error X:', errorX.toString()); // 0
-console.log('Round-trip error Y:', errorY.toString()); // ~2e-79
+const maskData = MaskResolver.parseMaskElement(maskElement);
+const maskPolygon = MaskResolver.resolveMask(maskData, targetBBox);
+MaskResolver.applyMask(elementPolygon, maskData, targetBBox)
+MaskResolver.colorToLuminance({ r, g, b })  // sRGB luminance
 ```
 
-### Transforming Path Data
+### Advanced Features
+
+#### MeshGradient (SVG 2.0)
 
 ```js
-import { SVGFlatten } from '@emasoft/svg-matrix';
+import { MeshGradient } from '@emasoft/svg-matrix';
+
+// Parse mesh gradient
+const meshDef = MeshGradient.parseMeshGradientElement(element);
+const meshData = MeshGradient.parseMeshGradient(meshDef);
+
+// Coons patch evaluation
+const patch = new MeshGradient.CoonsPatch(topEdge, rightEdge, bottomEdge, leftEdge, cornerColors);
+const { point, color } = patch.evaluate(u, v);
 
-const pathD = 'M 100 100 L 200 100 L 200 200 L 100 200 Z';
-const ctm = SVGFlatten.parseTransformAttribute('translate(50, 50) scale(2)');
-const transformed = SVGFlatten.transformPathData(pathD, ctm);
+// Rasterize to ImageData
+const imageData = MeshGradient.rasterizeMeshGradient(meshData, width, height);
 
-console.log(transformed);
-// M 250.000000 250.000000 L 450.000000 250.000000 L 450.000000 450.000000 L 250.000000 450.000000 Z
+// Convert to polygons for vector export
+const polygons = MeshGradient.meshGradientToPolygons(meshData, { subdivisions: 16 });
+
+// Clip and export
+const clipped = MeshGradient.clipMeshGradient(meshData, clipPolygon, { subdivisions: 32 });
+const svgPaths = MeshGradient.clippedMeshToSVG(clipped);
+```
+
+#### TextToPath
+
+```js
+import { TextToPath } from '@emasoft/svg-matrix';
+import opentype from 'opentype.js';
+
+const font = await opentype.load('font.ttf');
+
+// Convert text to path
+const pathData = TextToPath.textToPath("Hello", {
+  x: 100, y: 100,
+  fontSize: 24,
+  font: font,
+  textAnchor: TextToPath.TextAnchor.MIDDLE,
+  dominantBaseline: TextToPath.DominantBaseline.MIDDLE
+});
+
+// Parse text element
+const textData = TextToPath.parseTextElement(textElement);
+const result = TextToPath.textElementToPath(textData, { font });
+
+// Measure text
+const metrics = TextToPath.measureText("Hello", { fontSize: "20px" }, font);
+const bbox = TextToPath.getTextBBox(textData);
 ```
 
-### Flattening All Transforms
+### Convenience Functions
 
-To flatten an SVG (remove all transform attributes and apply them directly to coordinates):
+Direct exports for common operations:
 
 ```js
-import { SVGFlatten } from '@emasoft/svg-matrix';
+import {
+  // Transforms
+  translate2D, rotate2D, scale2D, transform2D,
+  translate3D, scale3D, transform3D,
 
-// 1. For each element, collect transforms from root to element
-// 2. Build CTM: const ctm = SVGFlatten.buildCTM(transformStack);
-// 3. Transform path data: const newD = SVGFlatten.transformPathData(d, ctm);
-// 4. Remove transform attribute, update path d attribute
-// 5. Convert CTM back to SVG: SVGFlatten.toSVGMatrix(ctm, 6)
-```
+  // Shape conversion
+  circleToPath, ellipseToPath, rectToPath, lineToPath,
+  polygonToPath, polylineToPath,
 
-### CDN Usage
+  // Path manipulation
+  parsePath, pathToString, pathToAbsolute, pathToCubics, transformPath,
+  elementToPath,
 
-```html
-<script type="module">
-  import { Decimal, SVGFlatten } from 'https://esm.sh/@emasoft/svg-matrix';
+  // Matrix/Vector creation
+  identity, zeros, vec, mat,
 
-  Decimal.set({ precision: 80 });
+  // Precision control
+  setPrecision, getPrecision,
 
-  const ctm = SVGFlatten.parseTransformAttribute('rotate(45, 100, 100)');
-  const point = SVGFlatten.applyToPoint(ctm, 50, 50);
-  console.log('Transformed:', point.x.toFixed(6), point.y.toFixed(6));
-</script>
+  // Constants
+  getKappa
+} from '@emasoft/svg-matrix';
 ```
 
 ## License