@emasoft/svg-matrix 1.0.5 → 1.0.7

package/README.md

@@ -1,529 +1,535 @@
 # @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
 
-### npm
+**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
 
-```bash
-npm install @emasoft/svg-matrix
-```
+**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
 
-```js
-import { Decimal, Matrix, Vector, Transforms2D, Transforms3D, SVGFlatten } from '@emasoft/svg-matrix';
-```
+**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
 
-### CDN (Browser)
+## Requirements
 
-Using esm.sh (recommended - auto-resolves dependencies):
+- **Node.js 24.0.0** or higher (ES modules, modern JavaScript features)
+- **Playwright** (optional) - for browser verification features
 
-```html
-<script type="module">
-  import { Decimal, Matrix, Vector, Transforms2D, Transforms3D, SVGFlatten } from 'https://esm.sh/@emasoft/svg-matrix';
+## Precision
 
-  Decimal.set({ precision: 80 });
+| 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 |
 
-  // Create and compose 2D transforms
-  const M = Transforms2D.translation(2, 3)
-    .mul(Transforms2D.rotate(Math.PI / 4))
-    .mul(Transforms2D.scale(1.5));
+**When precision matters:** GIS, CAD, scientific visualization, deep transform hierarchies, accumulated operations.
 
-  // Apply to a point
-  const [x, y] = Transforms2D.applyTransform(M, 1, 0);
-  console.log('Transformed:', x.toString(), y.toString());
-</script>
+**When floats suffice:** Simple transforms, small coordinates, visual applications where sub-pixel errors are imperceptible.
+
+```bash
+node test/benchmark-precision.js
 ```
 
-Using Skypack:
+## Installation
 
-```html
-<script type="module">
-  import { Matrix, Vector } from 'https://cdn.skypack.dev/@emasoft/svg-matrix';
-</script>
+```bash
+npm install @emasoft/svg-matrix
 ```
 
-Using import maps:
+```js
+import { Matrix, Vector, Transforms2D, Transforms3D, SVGFlatten } from '@emasoft/svg-matrix';
+```
+
+### CDN
 
 ```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';
+  import { Matrix, Vector, Transforms2D } from 'https://esm.sh/@emasoft/svg-matrix';
 </script>
 ```
 
-## Usage Examples
+## CLI
 
-### Vector Operations
+The library includes a command-line interface for batch processing SVG files.
 
-```js
-import { Vector, Decimal } from '@emasoft/svg-matrix';
+```bash
+# Process single file
+svg-matrix flatten input.svg -o output.svg
 
-Decimal.set({ precision: 80 });
+# Batch process folder
+svg-matrix flatten ./svgs/ -o ./output/
 
-const v = Vector.from([1, 2, 3]);
-const w = Vector.from([4, 5, 6]);
+# Process files from list
+svg-matrix flatten --list files.txt -o ./output/
+
+# Convert shapes to paths
+svg-matrix convert input.svg -o output.svg
+
+# Normalize paths to cubic Beziers
+svg-matrix normalize input.svg -o output.svg
 
-// 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]
+# Show SVG file info
+svg-matrix info input.svg
 
-// Geometry
-console.log('Norm:', v.norm().toString());           // 3.7416...
-console.log('Normalized:', v.normalize().toNumberArray());
-console.log('Angle:', v.angleBetween(w).toString()); // radians
+# Show help
+svg-matrix help
+```
+
+### CLI Options
+
+| Option | Description |
+|--------|-------------|
+| `-o, --output <path>` | Output file or directory |
+| `-l, --list <file>` | Read input files from text file |
+| `-r, --recursive` | Process directories recursively |
+| `-p, --precision <n>` | Decimal precision (default: 6) |
+| `-f, --force` | Overwrite existing files |
+| `-n, --dry-run` | Show what would be done |
+| `-q, --quiet` | Suppress all output except errors |
+| `-v, --verbose` | Enable verbose/debug output |
+| `--log-file <path>` | Write log to file |
 
-// Projection
-const proj = v.projectOnto(w);
-console.log('Projection:', proj.toNumberArray());
+### File List Format
+
+Create a text file with one path per line:
+
+```
+# This is a comment
+./folder1/file1.svg
+./folder2/file2.svg
+./entire-folder/
 ```
 
-### Matrix Operations
+## Quick Start
 
 ```js
-import { Matrix } from '@emasoft/svg-matrix';
+import { Decimal, Matrix, Vector, Transforms2D, SVGFlatten } from '@emasoft/svg-matrix';
 
-const A = Matrix.from([[1, 2], [3, 4]]);
-const B = Matrix.from([[5, 6], [7, 8]]);
+Decimal.set({ precision: 80 });
+
+// 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));
+
+// Apply to point
+const [x, y] = Transforms2D.applyTransform(M, 1, 0);
 
-// 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
+// Round-trip with inverse
+const [xBack, yBack] = Transforms2D.applyTransform(M.inverse(), x, y);
+```
+
+---
+
+## API Reference
 
-// Linear algebra
-const inv = A.inverse();
-console.log('Inverse:', inv.toNumberArray());
+### Linear Algebra
 
-// Solve Ax = b
-const x = A.solve([1, 1]);
-console.log('Solution:', x.toNumberArray());
+#### Vector
 
-// Decompositions
-const { L, U, P } = A.lu();
-const { Q, R } = A.qr();
+```js
+import { Vector } from '@emasoft/svg-matrix';
+
+const v = Vector.from([1, 2, 3]);
+const w = Vector.from([4, 5, 6]);
 
-// Matrix exponential
-const expA = A.exp();
+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]
 ```
 
-### 2D Transforms
+#### Matrix
 
 ```js
-import { Transforms2D } from '@emasoft/svg-matrix';
+import { Matrix } 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
+const A = Matrix.from([[1, 2], [3, 4]]);
+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
+```
 
-// Rotation around a point
-const Rp = Transforms2D.rotateAroundPoint(Math.PI / 2, 5, 5);
+### Transforms
 
-// Skew and stretch
-const Sk = Transforms2D.skew(0.5, 0);
-const St = Transforms2D.stretchAlongAxis(1, 0, 2); // stretch 2x along X
+#### 2D (3x3 matrices)
 
-// Reflections
-const Rx = Transforms2D.reflectX();      // flip Y
-const Ry = Transforms2D.reflectY();      // flip X
-const Ro = Transforms2D.reflectOrigin(); // flip both
+```js
+import { Transforms2D } from '@emasoft/svg-matrix';
 
-// Compose transforms (right-to-left: S first, then R, then T)
-const M = T.mul(R).mul(S);
+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()
 
 // Apply to point
-const [x, y] = Transforms2D.applyTransform(M, 1, 0);
-
-// Inverse transform
-const Minv = M.inverse();
-const [xBack, yBack] = Transforms2D.applyTransform(Minv, x, y);
+const [x, y] = Transforms2D.applyTransform(matrix, px, py);
 ```
 
-### 3D Transforms
+#### 3D (4x4 matrices)
 
 ```js
 import { Transforms3D } from '@emasoft/svg-matrix';
 
-// Basic transforms
-const T = Transforms3D.translation(1, 2, 3);
-const S = Transforms3D.scale(2, 2, 2);
+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);
+```
 
-// 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);
+### SVG Processing
 
-// Rotation around arbitrary axis
-const Raxis = Transforms3D.rotateAroundAxis(1, 1, 0, Math.PI / 3);
+#### SVGFlatten - Transform Parsing & CTM
 
-// Rotation around a point
-const Rpt = Transforms3D.rotateAroundPoint(0, 0, 1, Math.PI / 2, 5, 5, 0);
+```js
+import { SVGFlatten } from '@emasoft/svg-matrix';
 
-// 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
+// Parse transform attributes
+const m = SVGFlatten.parseTransformAttribute('translate(50,50) rotate(45) scale(2)');
 
-// Compose and apply
-const M = T.mul(Rx).mul(S);
-const [x, y, z] = Transforms3D.applyTransform(M, 1, 0, 0);
-```
+// 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)'
+]);
 
-## API Reference
+// Apply to point
+const { x, y } = SVGFlatten.applyToPoint(ctm, 10, 10);
 
-### Vector
+// Transform path data
+const transformed = SVGFlatten.transformPathData('M 100 100 L 200 200', ctm);
 
-| 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 |
-|----------|-------------|
-| **viewBox & Viewport** | |
-| `parseViewBox(str)` | Parse viewBox attribute "minX minY width height" |
-| `parsePreserveAspectRatio(str)` | Parse preserveAspectRatio (align, meet/slice) |
-| `computeViewBoxTransform(vb, vpW, vpH, par)` | Compute viewBox to viewport matrix |
-| `SVGViewport` class | Represents viewport with viewBox + preserveAspectRatio |
-| `buildFullCTM(hierarchy)` | Build CTM from SVG/group/element hierarchy |
-| **Units & Percentages** | |
-| `resolveLength(value, ref, dpi?)` | Resolve px, %, em, pt, in, cm, mm, pc units |
-| `resolvePercentages(x, y, vpW, vpH)` | Resolve x/y percentages to viewport |
-| `normalizedDiagonal(w, h)` | Compute sqrt(w^2+h^2)/sqrt(2) for percentages |
-| **Object Bounding Box** | |
-| `objectBoundingBoxTransform(x, y, w, h)` | Transform for objectBoundingBox units |
-| **Transform Parsing** | |
-| `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:
+// viewBox handling
+const viewBox = SVGFlatten.parseViewBox('0 0 100 100');
+const par = SVGFlatten.parsePreserveAspectRatio('xMidYMid meet');
+const vbTransform = SVGFlatten.computeViewBoxTransform(viewBox, 800, 600, par);
 
-```
-Original coordinates:     (10, 10)
-After round-trip (float): (9.9857, 9.9857)  // Error: 0.0143
-```
+// 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)' }
+]);
 
-With `@emasoft/svg-matrix` using 80-digit Decimal precision:
+// 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);
 ```
-Original coordinates:     (10, 10)
-After round-trip:         (10.00000000000000000000000000000000000000,
-                           9.999999999999999999999999999999999999999999999999999999999999999999999999999999998)
-Round-trip error:         X=0, Y=2e-79
-```
-
-**Improvement: 10^77 times better precision than JavaScript floats.**
 
-### Parsing SVG Transforms
+#### GeometryToPath - Shape Conversion
 
 ```js
-import { SVGFlatten } from '@emasoft/svg-matrix';
+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()
+```
 
-// 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)');
+#### BrowserVerify - Chrome Verification
 
-// Parse chained transforms
-const combined = SVGFlatten.parseTransformAttribute('translate(50,50) rotate(45) scale(2)');
+```js
+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 });
 ```
 
-### Building CTM from Nested Elements
+### Polygon Operations
 
-```js
-import { Decimal, SVGFlatten } from '@emasoft/svg-matrix';
+#### PolygonClip
 
-Decimal.set({ precision: 80 });
+```js
+import { PolygonClip } from '@emasoft/svg-matrix';
 
-// 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
+const square = [
+  PolygonClip.point(0, 0),
+  PolygonClip.point(2, 0),
+  PolygonClip.point(2, 2),
+  PolygonClip.point(0, 2)
 ];
 
-// Build combined CTM
-const ctm = SVGFlatten.buildCTM(transformStack);
+// Boolean operations
+PolygonClip.polygonIntersection(poly1, poly2)
+PolygonClip.polygonUnion(poly1, poly2)
+PolygonClip.polygonDifference(poly1, poly2)
 
-// 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);
+// Properties
+PolygonClip.polygonArea(polygon)
+PolygonClip.isCounterClockwise(polygon)
+PolygonClip.isConvex(polygon)
+PolygonClip.pointInPolygon(point, polygon)  // 1=inside, 0=boundary, -1=outside
 
-// Transform back to local coordinates
-const inverseCTM = ctm.inverse();
-const recovered = SVGFlatten.applyToPoint(inverseCTM, viewport.x, viewport.y);
+// Convex hull
+PolygonClip.convexHull(points)
 
-// 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
+// Bounding box
+PolygonClip.boundingBox(polygon)  // {minX, minY, maxX, maxY}
+PolygonClip.bboxIntersects(bbox1, bbox2)
 ```
 
-### Transforming Path Data
+#### ClipPathResolver
 
 ```js
-import { SVGFlatten } from '@emasoft/svg-matrix';
+import { ClipPathResolver } from '@emasoft/svg-matrix';
 
-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);
+// Parse and resolve clipPath
+const clipData = ClipPathResolver.parseClipPathElement(element);
+const clipPolygon = ClipPathResolver.resolveClipPath(clipData, targetBBox);
 
-console.log(transformed);
-// M 250.000000 250.000000 L 450.000000 250.000000 L 450.000000 450.000000 L 250.000000 450.000000 Z
+// Shape to polygon
+ClipPathResolver.shapeToPolygon({ type: 'circle', cx: 100, cy: 100, r: 50 }, { samples: 32 })
+ClipPathResolver.pathToPolygon(pathData, { samples: 20 })
+ClipPathResolver.polygonToPathData(polygon)
+
+// Apply clipPath to element
+ClipPathResolver.applyClipPath(elementData, clipPathData, targetBBox)
 ```
 
-### Flattening All Transforms
+### SVG Element Resolution
 
-To flatten an SVG (remove all transform attributes and apply them directly to coordinates):
+#### UseSymbolResolver
 
 ```js
-import { SVGFlatten } from '@emasoft/svg-matrix';
+import { UseSymbolResolver } from '@emasoft/svg-matrix';
 
-// 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)
+const useData = UseSymbolResolver.parseUseElement(useElement);
+const symbolData = UseSymbolResolver.parseSymbolElement(symbolElement);
+const resolved = UseSymbolResolver.resolveUse(useData, svgDocument);
+const flattened = UseSymbolResolver.flattenResolvedUse(resolved);
+UseSymbolResolver.resolveAllUses(svgDocument)
 ```
 
-### viewBox and preserveAspectRatio
+#### MarkerResolver
 
-Per the [SVG 2 specification](https://www.w3.org/TR/SVG2/coords.html), the viewBox establishes a new coordinate system that maps to the viewport:
+```js
+import { MarkerResolver } from '@emasoft/svg-matrix';
+
+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)
+```
+
+#### PatternResolver
 
 ```js
-import { Decimal, SVGFlatten } from '@emasoft/svg-matrix';
+import { PatternResolver } from '@emasoft/svg-matrix';
 
-Decimal.set({ precision: 80 });
+const patternData = PatternResolver.parsePatternElement(patternElement);
+const tiles = PatternResolver.resolvePattern(patternData, targetBBox);
+PatternResolver.applyPattern(elementData, patternData, targetBBox)
+PatternResolver.patternToClipPath(patternData, targetBBox)
+PatternResolver.patternToPathData(patternData, targetBBox)
+```
 
-// Parse viewBox and preserveAspectRatio
-const viewBox = SVGFlatten.parseViewBox('0 0 100 100');
-const par = SVGFlatten.parsePreserveAspectRatio('xMidYMid meet');
+#### MaskResolver
 
-// Compute the viewBox-to-viewport transform
-const vbTransform = SVGFlatten.computeViewBoxTransform(viewBox, 800, 600, par);
+```js
+import { MaskResolver } from '@emasoft/svg-matrix';
 
-// Point (50, 50) in viewBox coords maps to viewport
-const point = SVGFlatten.applyToPoint(vbTransform, 50, 50);
-console.log('Viewport coords:', point.x.toFixed(2), point.y.toFixed(2));
+const maskData = MaskResolver.parseMaskElement(maskElement);
+const maskPolygon = MaskResolver.resolveMask(maskData, targetBBox);
+MaskResolver.applyMask(elementPolygon, maskData, targetBBox)
+MaskResolver.colorToLuminance({ r, g, b })  // sRGB luminance
 ```
 
-### Full CTM with viewBox and Nested Elements
+### Advanced Features
 
-Use `buildFullCTM` for complete SVG hierarchies including viewBox transforms:
+#### MeshGradient (SVG 2.0)
 
 ```js
-import { Decimal, SVGFlatten } from '@emasoft/svg-matrix';
+import { MeshGradient } from '@emasoft/svg-matrix';
 
-Decimal.set({ precision: 80 });
+// Parse mesh gradient
+const meshDef = MeshGradient.parseMeshGradientElement(element);
+const meshData = MeshGradient.parseMeshGradient(meshDef);
 
-// Real SVG structure with viewBox and nested transforms
-const hierarchy = [
-  { type: 'svg', width: 800, height: 600, viewBox: '0 0 400 300', preserveAspectRatio: 'xMidYMid meet' },
-  { type: 'g', transform: 'translate(50, 50)' },
-  { type: 'g', transform: 'rotate(45)' },
-  { type: 'element', transform: 'scale(2)' }
-];
+// Coons patch evaluation
+const patch = new MeshGradient.CoonsPatch(topEdge, rightEdge, bottomEdge, leftEdge, cornerColors);
+const { point, color } = patch.evaluate(u, v);
 
-const ctm = SVGFlatten.buildFullCTM(hierarchy);
-const local = { x: new Decimal('10'), y: new Decimal('10') };
-const viewport = SVGFlatten.applyToPoint(ctm, local.x, local.y);
+// Rasterize to ImageData
+const imageData = MeshGradient.rasterizeMeshGradient(meshData, width, height);
 
-// Round-trip with perfect precision
-const inverse = ctm.inverse();
-const recovered = SVGFlatten.applyToPoint(inverse, viewport.x, viewport.y);
-// Error: X=2e-78, Y=2e-78
-```
+// Convert to polygons for vector export
+const polygons = MeshGradient.meshGradientToPolygons(meshData, { subdivisions: 16 });
 
-### Nested SVG Viewports
+// Clip and export
+const clipped = MeshGradient.clipMeshGradient(meshData, clipPolygon, { subdivisions: 32 });
+const svgPaths = MeshGradient.clippedMeshToSVG(clipped);
+```
 
-Handle deeply nested `<svg>` elements, each with its own viewBox:
+#### TextToPath
 
 ```js
-const nestedHierarchy = [
-  { type: 'svg', width: 1000, height: 800, viewBox: '0 0 500 400' },
-  { type: 'g', transform: 'translate(100, 100)' },
-  { type: 'svg', width: 200, height: 150, viewBox: '0 0 100 75' },
-  { type: 'element' }
-];
-
-const ctm = SVGFlatten.buildFullCTM(nestedHierarchy);
-// Point (10, 10) in innermost viewBox -> (240, 240) in outer viewport
+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);
 ```
 
-### Unit and Percentage Resolution
+### Convenience Functions
 
-Resolve SVG length values with units or percentages:
+Direct exports for common operations:
 
 ```js
-import { Decimal, SVGFlatten } from '@emasoft/svg-matrix';
+import {
+  // Transforms
+  translate2D, rotate2D, scale2D, transform2D,
+  translate3D, scale3D, transform3D,
 
-const viewportWidth = new Decimal(800);
+  // Shape conversion
+  circleToPath, ellipseToPath, rectToPath, lineToPath,
+  polygonToPath, polylineToPath,
 
-// Percentages resolve relative to reference size
-SVGFlatten.resolveLength('50%', viewportWidth);   // -> 400
-SVGFlatten.resolveLength('25%', viewportWidth);   // -> 200
+  // Path manipulation
+  parsePath, pathToString, pathToAbsolute, pathToCubics, transformPath,
+  elementToPath,
 
-// Absolute units (at 96 DPI)
-SVGFlatten.resolveLength('1in', viewportWidth);   // -> 96
-SVGFlatten.resolveLength('2.54cm', viewportWidth);// -> 96 (1 inch)
-SVGFlatten.resolveLength('72pt', viewportWidth);  // -> 96 (1 inch)
-SVGFlatten.resolveLength('6pc', viewportWidth);   // -> 96 (1 inch)
+  // Matrix/Vector creation
+  identity, zeros, vec, mat,
 
-// Font-relative units (assumes 16px base)
-SVGFlatten.resolveLength('2em', viewportWidth);   // -> 32
+  // Precision control
+  setPrecision, getPrecision,
 
-// Normalized diagonal for non-directional percentages
-const diag = SVGFlatten.normalizedDiagonal(800, 600); // -> 707.1
+  // Constants
+  getKappa
+} from '@emasoft/svg-matrix';
 ```
 
-### Object Bounding Box Transform
+### Logging
 
-For gradients/patterns with `objectBoundingBox` units:
+Control library logging output:
 
 ```js
-// Element bounding box: x=100, y=50, width=200, height=100
-const bboxTransform = SVGFlatten.objectBoundingBoxTransform(100, 50, 200, 100);
+import { Logger, LogLevel, setLogLevel, enableFileLogging } from '@emasoft/svg-matrix';
 
-// (0, 0) in bbox -> (100, 50) in user space
-// (1, 1) in bbox -> (300, 150) in user space
-// (0.5, 0.5) in bbox -> (200, 100) in user space (center)
-```
+// Suppress all logging
+setLogLevel(LogLevel.SILENT);
 
-### CDN Usage
+// Enable only errors
+setLogLevel(LogLevel.ERROR);
 
-```html
-<script type="module">
-  import { Decimal, SVGFlatten } from 'https://esm.sh/@emasoft/svg-matrix';
+// Enable warnings and errors (default)
+setLogLevel(LogLevel.WARN);
 
-  Decimal.set({ precision: 80 });
+// Enable all logging including debug
+setLogLevel(LogLevel.DEBUG);
 
-  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>
+// Write logs to file
+enableFileLogging('/path/to/log.txt');
+
+// Direct Logger access
+Logger.level = LogLevel.INFO;
+Logger.warn('Custom warning');
+Logger.debug('Debug info');
 ```
 
 ## License