@emasoft/svg-matrix 1.0.3 → 1.0.5

package/README.md

@@ -7,7 +7,9 @@ Arbitrary-precision matrix, vector and affine transformation library for JavaScr
 - **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)
 
 ## Installation
@@ -19,7 +21,7 @@ npm install @emasoft/svg-matrix
 ```
 
 ```js
-import { Decimal, Matrix, Vector, Transforms2D, Transforms3D } from '@emasoft/svg-matrix';
+import { Decimal, Matrix, Vector, Transforms2D, Transforms3D, SVGFlatten } from '@emasoft/svg-matrix';
 ```
 
 ### CDN (Browser)
@@ -28,7 +30,7 @@ Using esm.sh (recommended - auto-resolves dependencies):
 
 ```html
 <script type="module">
-  import { Decimal, Matrix, Vector, Transforms2D, Transforms3D } from 'https://esm.sh/@emasoft/svg-matrix';
+  import { Decimal, Matrix, Vector, Transforms2D, Transforms3D, SVGFlatten } from 'https://esm.sh/@emasoft/svg-matrix';
 
   Decimal.set({ precision: 80 });
 
@@ -272,6 +274,258 @@ const [x, y, z] = Transforms3D.applyTransform(M, 1, 0, 0);
 | `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:
+
+```
+Original coordinates:     (10, 10)
+After round-trip (float): (9.9857, 9.9857)  // Error: 0.0143
+```
+
+With `@emasoft/svg-matrix` using 80-digit Decimal precision:
+
+```
+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
+
+```js
+import { SVGFlatten } 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)');
+```
+
+### Building CTM from Nested Elements
+
+```js
+import { Decimal, SVGFlatten } from '@emasoft/svg-matrix';
+
+Decimal.set({ precision: 80 });
+
+// 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
+];
+
+// Build combined CTM
+const ctm = SVGFlatten.buildCTM(transformStack);
+
+// 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);
+
+// Transform back to local coordinates
+const inverseCTM = ctm.inverse();
+const recovered = SVGFlatten.applyToPoint(inverseCTM, viewport.x, viewport.y);
+
+// 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
+```
+
+### Transforming Path Data
+
+```js
+import { SVGFlatten } 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);
+
+console.log(transformed);
+// M 250.000000 250.000000 L 450.000000 250.000000 L 450.000000 450.000000 L 250.000000 450.000000 Z
+```
+
+### Flattening All Transforms
+
+To flatten an SVG (remove all transform attributes and apply them directly to coordinates):
+
+```js
+import { SVGFlatten } 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)
+```
+
+### viewBox and preserveAspectRatio
+
+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 { Decimal, SVGFlatten } from '@emasoft/svg-matrix';
+
+Decimal.set({ precision: 80 });
+
+// Parse viewBox and preserveAspectRatio
+const viewBox = SVGFlatten.parseViewBox('0 0 100 100');
+const par = SVGFlatten.parsePreserveAspectRatio('xMidYMid meet');
+
+// Compute the viewBox-to-viewport transform
+const vbTransform = SVGFlatten.computeViewBoxTransform(viewBox, 800, 600, par);
+
+// 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));
+```
+
+### Full CTM with viewBox and Nested Elements
+
+Use `buildFullCTM` for complete SVG hierarchies including viewBox transforms:
+
+```js
+import { Decimal, SVGFlatten } from '@emasoft/svg-matrix';
+
+Decimal.set({ precision: 80 });
+
+// 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)' }
+];
+
+const ctm = SVGFlatten.buildFullCTM(hierarchy);
+const local = { x: new Decimal('10'), y: new Decimal('10') };
+const viewport = SVGFlatten.applyToPoint(ctm, local.x, local.y);
+
+// 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
+```
+
+### Nested SVG Viewports
+
+Handle deeply nested `<svg>` elements, each with its own viewBox:
+
+```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
+```
+
+### Unit and Percentage Resolution
+
+Resolve SVG length values with units or percentages:
+
+```js
+import { Decimal, SVGFlatten } from '@emasoft/svg-matrix';
+
+const viewportWidth = new Decimal(800);
+
+// Percentages resolve relative to reference size
+SVGFlatten.resolveLength('50%', viewportWidth);   // -> 400
+SVGFlatten.resolveLength('25%', viewportWidth);   // -> 200
+
+// 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)
+
+// Font-relative units (assumes 16px base)
+SVGFlatten.resolveLength('2em', viewportWidth);   // -> 32
+
+// Normalized diagonal for non-directional percentages
+const diag = SVGFlatten.normalizedDiagonal(800, 600); // -> 707.1
+```
+
+### Object Bounding Box Transform
+
+For gradients/patterns with `objectBoundingBox` units:
+
+```js
+// Element bounding box: x=100, y=50, width=200, height=100
+const bboxTransform = SVGFlatten.objectBoundingBoxTransform(100, 50, 200, 100);
+
+// (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)
+```
+
+### CDN Usage
+
+```html
+<script type="module">
+  import { Decimal, SVGFlatten } from 'https://esm.sh/@emasoft/svg-matrix';
+
+  Decimal.set({ precision: 80 });
+
+  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>
+```
+
 ## License
 
 MIT

package/package.json

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

package/samples/preserveAspectRatio_SVG.svg

@@ -0,0 +1,63 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20000802//EN" 
+  "http://www.w3.org/TR/2000/CR-SVG-20000802/DTD/svg-20000802.dtd" [
+<!ENTITY Smile "
+  <rect x='.5' y='.5' width='29' height='39' style='fill:yellow; stroke:red'/>
+  <g transform='rotate(90)'>
+    <text x='10' y='10' style='font-family:Verdana; 
+          font-weight:bold; font-size:14'>:)</text>
+  </g>">
+<!ENTITY Viewport1 "<rect x='.5' y='.5' width='49' height='29'
+                          style='fill:none; stroke:blue'/>">
+<!ENTITY Viewport2 "<rect x='.5' y='.5' width='29' height='59' 
+                          style='fill:none; stroke:blue'/>">
+]>
+<svg width="480px" height="270px" style="font-family:Verdana; font-size:8">
+  <desc>Example PreserveAspectRatio - demonstrate available options</desc>
+  <text x="10" y="30">SVG to fit</text>
+  <g transform="translate(20,40)">&Smile;</g>
+  <text x="10" y="110">Viewport 1</text>
+  <g transform="translate(10,120)">&Viewport1;</g>
+  <text x="10" y="180">Viewport 2</text>
+  <g transform="translate(20,190)">&Viewport2;</g>
+  <text x="100" y="30">--------------- meet ---------------</text>
+  <g transform="translate(100,60)"><text y="-10">xMin*</text>&Viewport1;
+    <svg preserveAspectRatio="xMinYMin meet" viewBox="0 0 30 40" 
+         width="50" height="30">&Smile;</svg></g>
+  <g transform="translate(170,60)"><text y="-10">xMid*</text>&Viewport1;
+    <svg preserveAspectRatio="xMidYMid meet" viewBox="0 0 30 40" 
+         width="50" height="30">&Smile;</svg></g>
+  <g transform="translate(240,60)"><text y="-10">xMax*</text>&Viewport1;
+    <svg preserveAspectRatio="xMaxYMax meet" viewBox="0 0 30 40" 
+         width="50" height="30">&Smile;</svg></g>
+  <text x="330" y="30">---------- meet ----------</text>
+  <g transform="translate(330,60)"><text y="-10">*YMin</text>&Viewport2;
+    <svg preserveAspectRatio="xMinYMin meet" viewBox="0 0 30 40" 
+         width="30" height="60">&Smile;</svg></g>
+  <g transform="translate(380,60)"><text y="-10">*YMid</text>&Viewport2;
+    <svg preserveAspectRatio="xMidYMid meet" viewBox="0 0 30 40" 
+         width="30" height="60">&Smile;</svg></g>
+  <g transform="translate(430,60)"><text y="-10">*YMax</text>&Viewport2;
+    <svg preserveAspectRatio="xMaxYMax meet" viewBox="0 0 30 40" 
+         width="30" height="60">&Smile;</svg></g>
+  <text x="100" y="160">---------- slice ----------</text>
+  <g transform="translate(100,190)"><text y="-10">xMin*</text>&Viewport2;
+    <svg preserveAspectRatio="xMinYMin slice" viewBox="0 0 30 40" 
+         width="30" height="60">&Smile;</svg></g>
+  <g transform="translate(150,190)"><text y="-10">xMid*</text>&Viewport2;
+    <svg preserveAspectRatio="xMidYMid slice" viewBox="0 0 30 40" 
+         width="30" height="60">&Smile;</svg></g>
+  <g transform="translate(200,190)"><text y="-10">xMax*</text>&Viewport2;
+    <svg preserveAspectRatio="xMaxYMax slice" viewBox="0 0 30 40" 
+         width="30" height="60">&Smile;</svg></g>
+  <text x="270" y="160">--------------- slice ---------------</text>
+  <g transform="translate(270,190)"><text y="-10">*YMin</text>&Viewport1;
+    <svg preserveAspectRatio="xMinYMin slice" viewBox="0 0 30 40" 
+         width="50" height="30">&Smile;</svg></g>
+  <g transform="translate(340,190)"><text y="-10">*YMid</text>&Viewport1;
+    <svg preserveAspectRatio="xMidYMid slice" viewBox="0 0 30 40" 
+         width="50" height="30">&Smile;</svg></g>
+  <g transform="translate(410,190)"><text y="-10">*YMax</text>&Viewport1;
+    <svg preserveAspectRatio="xMaxYMax slice" viewBox="0 0 30 40" 
+         width="50" height="30">&Smile;</svg></g>
+</svg>

package/samples/test.svg

@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg id="pure_smill_no_javascript" version="1.1" x="0px" y="0px" width="1037.2269" height="1486.5736" viewBox="0 0 1037.227 2892.792" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://www.w3.org/2000/svg" xmlns:svg="http://www.w3.org/2000/svg">
+  <defs id="defs82" />
+  <defs id="defs83" />
+  <g id="g37" transform="translate(-13.613145,-10.209854)">
+    <rect style="fill:#ffffff;stroke-width:16.1377" id="rect46" width="2018.3876" height="2892.792" x="-476.96716" y="10.209854" />
+    <g id="g1" transform="translate(-1144.8563,517.64642)">
+      <path id="rect1851" style="fill:none;stroke:#fe0000;stroke-width:14.5557;stroke-dasharray:87.3339, 14.5557;stroke-dashoffset:0;stroke-opacity:1" d="m 1318.7684,284.08405 c 307.4737,-77.43295 477.4693,-79.6744 779.5799,0 132.9776,50.26731 130.7718,132.64482 0,168.79753 -297.0165,89.1289 -485.8097,78.65553 -779.5799,0 -143.454,-38.49011 -151.4589,-124.05689 0,-168.79753 z" />
+    </g>
+    <g id="g6" transform="translate(13.613181,10.209854)">
+      <text xml:space="preserve" style="font-style:normal;font-variant:normal;font-weight:500;font-stretch:normal;font-size:94.4263px;font-family:Futura;-inkscape-font-specification:'Futura, Medium';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;writing-mode:lr-tb;direction:ltr;text-anchor:middle;fill:#808000;stroke-width:16.0447" x="535.36902" y="880.21216" id="text2"><tspan id="tspan2" style="font-style:normal;font-variant:normal;font-weight:500;font-stretch:normal;font-size:94.4263px;font-family:Futura;-inkscape-font-specification:'Futura, Medium';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#808000;stroke-width:16.0447" x="535.36902" y="880.21216">100% PURE SMIL</tspan></text>
+    </g>
+    <g id="g7" transform="translate(13.613181,10.209854)">
+      <text xml:space="preserve" style="font-style:normal;font-variant:normal;font-weight:500;font-stretch:normal;font-size:51.2678px;font-family:Futura;-inkscape-font-specification:'Futura, Medium';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;writing-mode:lr-tb;direction:ltr;text-anchor:middle;fill:#808000;stroke-width:8.7113" x="550.46289" y="939.87573" id="text3"><tspan id="tspan3" style="font-style:italic;font-variant:normal;font-weight:500;font-stretch:normal;font-size:51.2678px;font-family:Futura;-inkscape-font-specification:'Futura, Medium Italic';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#808000;stroke-width:8.7113" x="550.46289" y="939.87573">No javascript or css needed!</tspan></text>
+    </g>
+    <text xml:space="preserve" style="font-style:italic;font-weight:600;font-size:85.6631px;font-family:'EB Garamond', serif;-inkscape-font-specification:'EB Garamond, serif, Semi-Bold Italic';writing-mode:lr-tb;direction:ltr;text-anchor:middle;fill:#000080;stroke-width:26.6984" x="388.92661" y="1477.7195" id="text37" text-anchor="middle"><tspan id="tspan1" style="font-style:normal;font-variant:normal;font-weight:500;font-stretch:normal;font-size:85.6631px;font-family:Futura;-inkscape-font-specification:'Futura, Medium';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000080;stroke-width:26.6984" x="388.92661" y="1477.7195">100% PURE SMIL</tspan></text>
+    <text xml:space="preserve" style="font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:63.7367px;font-family:'.New York';-inkscape-font-specification:'.New York, Italic';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;writing-mode:lr-tb;direction:ltr;text-anchor:middle;fill:#000080;stroke-width:19.8645" x="363.31311" y="1603.9994" id="text39" text-anchor="middle"><tspan id="tspan38" style="font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:63.7367px;font-family:'.New York';-inkscape-font-specification:'.New York, Italic';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000080;stroke-width:19.8645" x="363.31311" y="1603.9994">No javascript or css needed!</tspan></text>
+    <text xml:space="preserve" style="font-style:italic;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:69.4323px;font-family:'Hurmit Nerd Font';-inkscape-font-specification:'Hurmit Nerd Font, Bold Italic';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;writing-mode:lr-tb;direction:ltr;text-anchor:middle;fill:#000080;stroke-width:21.6396" x="678.02161" y="1757.4683" id="text40" transform="scale(0.71577068,1.3970955)" text-anchor="middle"><tspan id="tspan39" style="font-style:italic;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:69.4323px;font-family:'Hurmit Nerd Font';-inkscape-font-specification:'Hurmit Nerd Font, Bold Italic';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000080;stroke-width:21.6396" x="678.02161" y="1757.4683">No javascript or css needed!</tspan></text>
+    <text xml:space="preserve" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:85.6631px;font-family:Luminari;-inkscape-font-specification:'Luminari, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;writing-mode:lr-tb;direction:ltr;text-anchor:middle;fill:#000080;stroke-width:26.6984" x="404.79761" y="2284.7117" id="text41" text-anchor="middle"><tspan id="tspan40" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:85.6631px;font-family:Luminari;-inkscape-font-specification:'Luminari, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000080;stroke-width:26.6984" x="404.79761" y="2284.7117">100% PURE SMIL</tspan></text>
+    <text xml:space="preserve" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:condensed;font-size:85.6631px;font-family:'American Typewriter';-inkscape-font-specification:'American Typewriter, Condensed';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;writing-mode:lr-tb;direction:ltr;text-anchor:middle;fill:#000080;stroke-width:26.6984" x="341.14975" y="1755.0848" id="text42" text-anchor="middle"><tspan id="tspan41" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:condensed;font-size:85.6631px;font-family:'American Typewriter';-inkscape-font-specification:'American Typewriter, Condensed';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000080;stroke-width:26.6984" x="341.14975" y="1755.0848">100% PURE SMIL</tspan></text>
+    <text xml:space="preserve" style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:85.6631px;font-family:'Comic Sans MS';-inkscape-font-specification:'Comic Sans MS, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;writing-mode:lr-tb;direction:ltr;text-anchor:middle;fill:#000080;stroke-width:26.6984" x="419.90002" y="1326.3029" id="text43" text-anchor="middle"><tspan id="tspan42" style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:85.6631px;font-family:'Comic Sans MS';-inkscape-font-specification:'Comic Sans MS, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000080;stroke-width:26.6984" x="419.90002" y="1326.3029">100% PURE SMIL</tspan></text>
+    <text xml:space="preserve" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:85.6631px;font-family:'.SF Arabic Rounded';-inkscape-font-specification:'.SF Arabic Rounded, @opsz=80,wght=510';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;font-variation-settings:'opsz' 80, 'wght' 510;writing-mode:lr-tb;direction:ltr;text-anchor:middle;white-space:pre;inline-size:1228.52;display:inline;fill:#000080;stroke-width:26.6984" x="1381.6643" y="1890.0889" id="text44" text-anchor="middle" transform="matrix(1.3203255,0,0,1.3203255,-1375.0262,-560.41607)"><tspan x="1381.6643" y="1890.0889" id="tspan27"><tspan style="text-align:end;text-anchor:end" id="tspan24">منتررف؛</tspan><tspan dx="212.47826" style="text-align:end;text-anchor:end" id="tspan25">٦٥</tspan><tspan dx="714.30957 -42.915234" style="text-align:end;text-anchor:end" id="tspan26">غفبممهت ورعبب</tspan><tspan y="1890.0889" id="tspan29">  </tspan></tspan><tspan x="1381.6643" y="1997.1678" id="tspan45"><tspan style="text-align:end;text-anchor:end" id="tspan30">٣٤٥٨</tspan><tspan dx="538.61511 0 0 0 0 25.01298 0 14.890675 -39.903576" style="text-align:end;text-anchor:end" id="tspan32">حخهـعنٌففڤك</tspan><tspan dx="296.26553" style="text-align:end;text-anchor:end" id="tspan33">٦</tspan><tspan dx="132.55197" style="text-align:end;text-anchor:end" id="tspan34">#</tspan><tspan dx="-47.641735" style="text-align:end;text-anchor:end" id="tspan35">٤</tspan><tspan dx="514.77338" style="text-align:end;text-anchor:end" id="tspan43">وحكهههـا؛جن</tspan></tspan></text>
+    <text xml:space="preserve" style="font-style:normal;font-variant:normal;font-weight:500;font-stretch:normal;font-size:67.9909px;font-family:'GohuFont 14 Nerd Font';-inkscape-font-specification:'GohuFont 14 Nerd Font, Medium';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;writing-mode:lr-tb;direction:ltr;text-anchor:middle;fill:#000080;stroke-width:21.1905" x="604.13745" y="1147.0764" id="text45" text-anchor="middle"><tspan id="tspan44" style="font-style:normal;font-variant:normal;font-weight:500;font-stretch:normal;font-size:67.9909px;font-family:'GohuFont 14 Nerd Font';-inkscape-font-specification:'GohuFont 14 Nerd Font, Medium';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000080;stroke-width:21.1905" x="604.13745" y="1147.0764">100% PURE SMIL تاكهعغفبقڤذطسببى٦٥!§|</tspan></text>
+    <text xml:space="preserve" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:69.4323px;font-family:Phosphate;-inkscape-font-specification:'Phosphate, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;writing-mode:lr-tb;direction:ltr;text-anchor:middle;fill:#000080;stroke-width:21.6396" x="536.83356" y="1861.4491" id="text47" transform="scale(0.71577068,1.3970955)" text-anchor="middle"><tspan id="tspan47" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:69.4323px;font-family:Phosphate;-inkscape-font-specification:'Phosphate, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000080;stroke-width:21.6396" x="536.83356" y="1861.4491">No javascript or css needed!</tspan></text>
+    <text xml:space="preserve" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:69.4323px;font-family:'ProFont IIx Nerd Font';-inkscape-font-specification:'ProFont IIx Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;writing-mode:lr-tb;direction:ltr;text-anchor:middle;fill:#000080;stroke-width:21.6396" x="747.38995" y="525.20264" id="text48" transform="matrix(0.71322166,-0.06035344,0.11780243,1.3921201,0,0)" text-anchor="middle"><tspan id="tspan48" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:69.4323px;font-family:'ProFont IIx Nerd Font';-inkscape-font-specification:'ProFont IIx Nerd Font, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000080;stroke-width:21.6396" x="747.39001" y="525.20264">No javascript or css needed!</tspan></text>
+    <text xml:space="preserve" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:63.7367px;font-family:'Bodoni Ornaments';-inkscape-font-specification:'Bodoni Ornaments, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;writing-mode:lr-tb;direction:ltr;text-anchor:middle;fill:#000080;stroke-width:19.8645" x="472.37082" y="2838.6682" id="text49" text-anchor="middle"><tspan id="tspan49" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:63.7367px;font-family:'Bodoni Ornaments';-inkscape-font-specification:'Bodoni Ornaments, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000080;stroke-width:19.8645" x="472.37082" y="2838.6682">No javascript or css needed!</tspan></text>
+    <text xml:space="preserve" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:63.7367px;font-family:'Academy Engraved LET';-inkscape-font-specification:'Academy Engraved LET, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;writing-mode:lr-tb;direction:ltr;text-anchor:middle;fill:#000080;stroke-width:19.8645" x="533.84888" y="530.25562" id="text50" text-anchor="middle"><tspan id="tspan50" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:63.7367px;font-family:'Academy Engraved LET';-inkscape-font-specification:'Academy Engraved LET, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000080;stroke-width:19.8645" x="533.84888" y="530.25562">No javascript or css needed!</tspan></text>
+    <text xml:space="preserve" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:63.7367px;font-family:Zapfino;-inkscape-font-specification:'Zapfino, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;writing-mode:lr-tb;direction:ltr;text-anchor:middle;fill:#000080;stroke-width:19.8645" x="584.37799" y="397.6167" id="text51" text-anchor="middle"><tspan id="tspan51" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:63.7367px;font-family:Zapfino;-inkscape-font-specification:'Zapfino, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000080;stroke-width:19.8645" x="584.37799" y="397.6167">No javascript or css needed!</tspan></text>
+    <text xml:space="preserve" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:63.7367px;font-family:Webdings;-inkscape-font-specification:'Webdings, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;writing-mode:lr-tb;direction:ltr;text-anchor:middle;fill:#000080;stroke-width:19.8645" x="449.30762" y="120.5267" id="text52" text-anchor="middle"><tspan id="tspan52" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:63.7367px;font-family:Webdings;-inkscape-font-specification:'Webdings, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000080;stroke-width:19.8645" x="449.30762" y="120.5267">No javascript or css needed!</tspan></text>
+    <text xml:space="preserve" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:63.7367px;font-family:Copperplate;-inkscape-font-specification:'Copperplate, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;writing-mode:lr-tb;direction:ltr;text-anchor:middle;fill:#000080;stroke-width:19.8645" x="609.64258" y="246.02931" id="text53" text-anchor="middle"><tspan id="tspan53" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:63.7367px;font-family:Copperplate;-inkscape-font-specification:'Copperplate, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000080;stroke-width:19.8645" x="609.64258" y="246.02931">No javascript or css needed!</tspan></text>
+    <text xml:space="preserve" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:85.6631px;font-family:Luminari;-inkscape-font-specification:'Luminari, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;writing-mode:lr-tb;direction:ltr;text-anchor:middle;fill:#000080;stroke-width:26.6984" x="450.42053" y="2729.5894" id="text54" text-anchor="middle"><tspan id="tspan54" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:85.6631px;font-family:Sans;-inkscape-font-specification:'Sans, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000080;stroke-width:26.6984" x="450.42053" y="2729.5894">100%  غعخيقفٌع٩ْخنتلو،حجةضصشيذزظطققثًار،منتزقُڤخهـرزلڤ</tspan></text>
+    <text xml:space="preserve" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:302.923px;font-family:'.SF Arabic Rounded';-inkscape-font-specification:'.SF Arabic Rounded, @opsz=80,wght=510';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;font-variation-settings:'opsz' 80, 'wght' 510;text-align:end;writing-mode:lr-tb;direction:ltr;text-anchor:end;fill:#808000;stroke-width:51.4717" x="-101.66634" y="477.18921" id="text4"><tspan id="tspan4" style="stroke-width:51.4717" x="-101.66634" y="477.18921">兛</tspan><tspan style="stroke-width:51.4717" x="-101.66634" y="864.82745" id="tspan5">瓩</tspan><tspan style="stroke-width:51.4717" x="-101.66634" y="1252.4657" id="tspan6">☞</tspan></text>
+    <path style="font-variation-settings:'opsz' 80, 'wght' 510;fill:none;stroke:#e40000;stroke-width:17.0854;stroke-dasharray:none;stroke-opacity:0.648148" d="m 1417.5151,346.27451 c -172.195,68.09973 -181.5149,120.68753 -227.2008,324.94298 -10.7474,48.04981 -1.555,122.34751 21.0816,166.07303 l 3.347,6.46516 c 40.3542,77.94932 296.6243,309.72422 275.2567,92.27938" id="path7" />
+    <text xml:space="preserve" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:63.7367px;font-family:'Academy Engraved LET';-inkscape-font-specification:'Academy Engraved LET, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;writing-mode:lr-tb;direction:ltr;text-anchor:middle;white-space:pre;fill:#000080;stroke-width:19.8645" id="text7" text-anchor="middle" transform="matrix(0.89589712,0,0,0.89589712,151.55716,65.666192)"><textPath xlink:href="#path7" startOffset="50%" id="textPath7"><tspan id="tspan7" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:63.7367px;font-family:'Academy Engraved LET';-inkscape-font-specification:'Academy Engraved LET, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000080;stroke-width:19.8645">No javascript or css needed!</tspan></textPath></text>
+    <text xml:space="preserve" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:268.424px;font-family:'Times New Roman';-inkscape-font-specification:'Times New Roman, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:end;writing-mode:lr-tb;direction:ltr;text-anchor:end;fill:#6d2eb8;fill-opacity:0.574074;stroke:none;stroke-width:2.43157;stroke-dasharray:none;stroke-opacity:0.648148" x="-50.072258" y="1466.8563" id="text8" transform="scale(0.86535508,1.155595)"><tspan id="tspan8" style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:268.424px;font-family:'Times New Roman';-inkscape-font-specification:'Times New Roman, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#6d2eb8;fill-opacity:0.574074;stroke:none;stroke-width:2.43157;stroke-dasharray:none" x="-50.072266" y="1466.8563">Λοπ</tspan></text>
+    <text xml:space="preserve" style="font-style:italic;font-variant:normal;font-weight:300;font-stretch:normal;font-size:92.6956px;font-family:Superclarendon;-inkscape-font-specification:'Superclarendon, Light Italic';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:end;writing-mode:lr-tb;direction:ltr;text-anchor:end;fill:#6d2eb8;fill-opacity:0.574074;stroke:none;stroke-width:0.839701;stroke-dasharray:none;stroke-opacity:0.648148" x="-41.03904" y="1797.0054" id="text9"><tspan id="tspan9" style="font-style:italic;font-variant:normal;font-weight:300;font-stretch:normal;font-size:92.6956px;font-family:Superclarendon;-inkscape-font-specification:'Superclarendon, Light Italic';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#6d2eb8;fill-opacity:0.574074;stroke:none;stroke-width:0.839701;stroke-dasharray:none" x="-41.039047" y="1797.0054">lkœtrëå</tspan></text>
+    <text xml:space="preserve" style="font-style:italic;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:69.4323px;font-family:'Hurmit Nerd Font';-inkscape-font-specification:'Hurmit Nerd Font, Bold Italic';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-decoration:underline;text-decoration-line:underline;writing-mode:lr-tb;direction:ltr;text-anchor:middle;fill:#000080;stroke-width:21.6396" x="1786.3558" y="997.44519" id="text22" transform="scale(0.71577068,1.3970955)" text-anchor="middle" text-decoration="underline"><tspan id="tspan23" x="1785.8699" y="997.44519" style="text-align:end;text-anchor:end"><tspan id="tspan22" style="font-style:italic;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:69.4323px;font-family:'Hurmit Nerd Font';-inkscape-font-specification:'Hurmit Nerd Font, Bold Italic';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:end;text-anchor:end;fill:#000080;stroke-width:21.6396" x="1785.8699" y="997.44519">No javascript</tspan></tspan><tspan x="1785.8699" y="997.44519" id="tspan28"><tspan id="tspan36" style="text-align:end;text-anchor:end"><tspan style="font-style:italic;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:69.4323px;font-family:'Hurmit Nerd Font';-inkscape-font-specification:'Hurmit Nerd Font, Bold Italic';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:end;text-anchor:end;fill:#000080;stroke-width:21.6396" x="1785.8699" y="997.44519" id="tspan31">   </tspan></tspan></tspan><tspan x="1785.8699" y="1084.2356" id="tspan37">no css needed!</tspan></text>
+  </g>
+</svg>

package/src/index.js

@@ -27,5 +27,6 @@ import { Matrix } from './matrix.js';
 import { Vector } from './vector.js';
 import * as Transforms2D from './transforms2d.js';
 import * as Transforms3D from './transforms3d.js';
+import * as SVGFlatten from './svg-flatten.js';
 
-export { Decimal, Matrix, Vector, Transforms2D, Transforms3D };
+export { Decimal, Matrix, Vector, Transforms2D, Transforms3D, SVGFlatten };

package/src/svg-flatten.js

@@ -0,0 +1,715 @@
+/**
+ * SVG Transform Flattening Utility
+ *
+ * Parses SVG transform attributes, builds CTM (Current Transform Matrix) for each element,
+ * and can flatten all transforms by applying them directly to coordinates.
+ *
+ * @module svg-flatten
+ */
+
+import Decimal from 'decimal.js';
+import { Matrix } from './matrix.js';
+import * as Transforms2D from './transforms2d.js';
+
+// Set high precision for all calculations
+Decimal.set({ precision: 80 });
+
+// ============================================================================
+// viewBox and preserveAspectRatio Parsing
+// ============================================================================
+
+/**
+ * Parse an SVG viewBox attribute.
+ *
+ * @param {string} viewBoxStr - viewBox attribute value "minX minY width height"
+ * @returns {{minX: Decimal, minY: Decimal, width: Decimal, height: Decimal}|null}
+ */
+export function parseViewBox(viewBoxStr) {
+  if (!viewBoxStr || viewBoxStr.trim() === '') {
+    return null;
+  }
+
+  const parts = viewBoxStr.trim().split(/[\s,]+/).map(s => new Decimal(s));
+  if (parts.length !== 4) {
+    console.warn(`Invalid viewBox: ${viewBoxStr}`);
+    return null;
+  }
+
+  return {
+    minX: parts[0],
+    minY: parts[1],
+    width: parts[2],
+    height: parts[3]
+  };
+}
+
+/**
+ * Parse an SVG preserveAspectRatio attribute.
+ * Format: "[defer] <align> [<meetOrSlice>]"
+ *
+ * @param {string} parStr - preserveAspectRatio attribute value
+ * @returns {{defer: boolean, align: string, meetOrSlice: string}}
+ */
+export function parsePreserveAspectRatio(parStr) {
+  const result = {
+    defer: false,
+    align: 'xMidYMid',  // default
+    meetOrSlice: 'meet' // default
+  };
+
+  if (!parStr || parStr.trim() === '') {
+    return result;
+  }
+
+  const parts = parStr.trim().split(/\s+/);
+  let idx = 0;
+
+  // Check for 'defer' (only applies to <image>)
+  if (parts[idx] === 'defer') {
+    result.defer = true;
+    idx++;
+  }
+
+  // Alignment value
+  if (parts[idx]) {
+    result.align = parts[idx];
+    idx++;
+  }
+
+  // meetOrSlice
+  if (parts[idx]) {
+    result.meetOrSlice = parts[idx].toLowerCase();
+  }
+
+  return result;
+}
+
+/**
+ * Compute the transformation matrix from viewBox coordinates to viewport.
+ * Implements the SVG 2 algorithm for viewBox + preserveAspectRatio.
+ *
+ * @param {Object} viewBox - Parsed viewBox {minX, minY, width, height}
+ * @param {number|Decimal} viewportWidth - Viewport width in pixels
+ * @param {number|Decimal} viewportHeight - Viewport height in pixels
+ * @param {Object} par - Parsed preserveAspectRatio {align, meetOrSlice}
+ * @returns {Matrix} 3x3 transformation matrix
+ */
+export function computeViewBoxTransform(viewBox, viewportWidth, viewportHeight, par = null) {
+  const D = x => new Decimal(x);
+
+  if (!viewBox) {
+    return Matrix.identity(3);
+  }
+
+  const vbX = viewBox.minX;
+  const vbY = viewBox.minY;
+  const vbW = viewBox.width;
+  const vbH = viewBox.height;
+  const vpW = D(viewportWidth);
+  const vpH = D(viewportHeight);
+
+  // Default preserveAspectRatio
+  if (!par) {
+    par = { align: 'xMidYMid', meetOrSlice: 'meet' };
+  }
+
+  // Handle 'none' - stretch to fill
+  if (par.align === 'none') {
+    const scaleX = vpW.div(vbW);
+    const scaleY = vpH.div(vbH);
+    // translate(-minX, -minY) then scale
+    const translateM = Transforms2D.translation(vbX.neg(), vbY.neg());
+    const scaleM = Transforms2D.scale(scaleX, scaleY);
+    return scaleM.mul(translateM);
+  }
+
+  // Compute uniform scale factor
+  let scaleX = vpW.div(vbW);
+  let scaleY = vpH.div(vbH);
+  let scale;
+
+  if (par.meetOrSlice === 'slice') {
+    // Use larger scale (content may overflow)
+    scale = Decimal.max(scaleX, scaleY);
+  } else {
+    // 'meet' - use smaller scale (content fits entirely)
+    scale = Decimal.min(scaleX, scaleY);
+  }
+
+  // Compute translation for alignment
+  const scaledW = vbW.mul(scale);
+  const scaledH = vbH.mul(scale);
+
+  let translateX = D(0);
+  let translateY = D(0);
+
+  // Parse alignment string (e.g., 'xMidYMid', 'xMinYMax')
+  const align = par.align;
+
+  // X alignment
+  if (align.includes('xMid')) {
+    translateX = vpW.minus(scaledW).div(2);
+  } else if (align.includes('xMax')) {
+    translateX = vpW.minus(scaledW);
+  }
+  // xMin is default (translateX = 0)
+
+  // Y alignment
+  if (align.includes('YMid')) {
+    translateY = vpH.minus(scaledH).div(2);
+  } else if (align.includes('YMax')) {
+    translateY = vpH.minus(scaledH);
+  }
+  // YMin is default (translateY = 0)
+
+  // Build the transform: translate(translateX, translateY) scale(scale) translate(-minX, -minY)
+  // Applied right-to-left: first translate by -minX,-minY, then scale, then translate for alignment
+  const translateMinM = Transforms2D.translation(vbX.neg(), vbY.neg());
+  const scaleM = Transforms2D.scale(scale, scale);
+  const translateAlignM = Transforms2D.translation(translateX, translateY);
+
+  return translateAlignM.mul(scaleM).mul(translateMinM);
+}
+
+/**
+ * Represents an SVG viewport with its coordinate system parameters.
+ * Used for building the full CTM through nested viewports.
+ */
+export class SVGViewport {
+  /**
+   * @param {number|Decimal} width - Viewport width
+   * @param {number|Decimal} height - Viewport height
+   * @param {string|null} viewBox - viewBox attribute value
+   * @param {string|null} preserveAspectRatio - preserveAspectRatio attribute value
+   * @param {string|null} transform - transform attribute value
+   */
+  constructor(width, height, viewBox = null, preserveAspectRatio = null, transform = null) {
+    this.width = new Decimal(width);
+    this.height = new Decimal(height);
+    this.viewBox = viewBox ? parseViewBox(viewBox) : null;
+    this.preserveAspectRatio = parsePreserveAspectRatio(preserveAspectRatio);
+    this.transform = transform;
+  }
+
+  /**
+   * Compute the transformation matrix for this viewport.
+   * @returns {Matrix} 3x3 transformation matrix
+   */
+  getTransformMatrix() {
+    let result = Matrix.identity(3);
+
+    // Apply viewBox transform first (if present)
+    if (this.viewBox) {
+      const vbTransform = computeViewBoxTransform(
+        this.viewBox,
+        this.width,
+        this.height,
+        this.preserveAspectRatio
+      );
+      result = result.mul(vbTransform);
+    }
+
+    // Then apply the transform attribute (if present)
+    if (this.transform) {
+      const transformMatrix = parseTransformAttribute(this.transform);
+      result = result.mul(transformMatrix);
+    }
+
+    return result;
+  }
+}
+
+/**
+ * Build the complete CTM including viewports, viewBox transforms, and element transforms.
+ *
+ * @param {Array} hierarchy - Array of objects describing the hierarchy from root to element.
+ *   Each object can be:
+ *   - {type: 'svg', width, height, viewBox?, preserveAspectRatio?, transform?}
+ *   - {type: 'g', transform?}
+ *   - {type: 'element', transform?}
+ *   Or simply a transform string for backwards compatibility
+ * @returns {Matrix} Combined CTM as 3x3 matrix
+ */
+export function buildFullCTM(hierarchy) {
+  let ctm = Matrix.identity(3);
+
+  for (const item of hierarchy) {
+    if (typeof item === 'string') {
+      // Backwards compatibility: treat string as transform attribute
+      if (item) {
+        const matrix = parseTransformAttribute(item);
+        ctm = ctm.mul(matrix);
+      }
+    } else if (item.type === 'svg') {
+      // SVG viewport with potential viewBox
+      const viewport = new SVGViewport(
+        item.width,
+        item.height,
+        item.viewBox || null,
+        item.preserveAspectRatio || null,
+        item.transform || null
+      );
+      ctm = ctm.mul(viewport.getTransformMatrix());
+    } else if (item.type === 'g' || item.type === 'element') {
+      // Group or element with optional transform
+      if (item.transform) {
+        const matrix = parseTransformAttribute(item.transform);
+        ctm = ctm.mul(matrix);
+      }
+    }
+  }
+
+  return ctm;
+}
+
+// ============================================================================
+// Unit and Percentage Resolution
+// ============================================================================
+
+/**
+ * Resolve a length value that may include units or percentages.
+ *
+ * @param {string|number} value - Length value (e.g., "50%", "10px", "5em", 100)
+ * @param {Decimal} referenceSize - Reference size for percentage resolution
+ * @param {number} [dpi=96] - DPI for absolute unit conversion
+ * @returns {Decimal} Resolved length in user units (px)
+ */
+export function resolveLength(value, referenceSize, dpi = 96) {
+  const D = x => new Decimal(x);
+
+  if (typeof value === 'number') {
+    return D(value);
+  }
+
+  const str = String(value).trim();
+
+  // Percentage
+  if (str.endsWith('%')) {
+    const pct = D(str.slice(0, -1));
+    return pct.div(100).mul(referenceSize);
+  }
+
+  // Extract numeric value and unit
+  const match = str.match(/^([+-]?[\d.]+(?:e[+-]?\d+)?)(.*)?$/i);
+  if (!match) {
+    return D(0);
+  }
+
+  const num = D(match[1]);
+  const unit = (match[2] || '').toLowerCase().trim();
+
+  // Convert to user units (px)
+  switch (unit) {
+    case '':
+    case 'px':
+      return num;
+    case 'em':
+      return num.mul(16); // Assume 16px font-size
+    case 'rem':
+      return num.mul(16);
+    case 'pt':
+      return num.mul(dpi).div(72);
+    case 'pc':
+      return num.mul(dpi).div(6);
+    case 'in':
+      return num.mul(dpi);
+    case 'cm':
+      return num.mul(dpi).div(2.54);
+    case 'mm':
+      return num.mul(dpi).div(25.4);
+    default:
+      return num; // Unknown unit, treat as px
+  }
+}
+
+/**
+ * Resolve percentage values for x/width (relative to viewport width)
+ * and y/height (relative to viewport height).
+ *
+ * @param {string|number} xOrWidth - X coordinate or width value
+ * @param {string|number} yOrHeight - Y coordinate or height value
+ * @param {Decimal} viewportWidth - Viewport width for reference
+ * @param {Decimal} viewportHeight - Viewport height for reference
+ * @returns {{x: Decimal, y: Decimal}} Resolved coordinates
+ */
+export function resolvePercentages(xOrWidth, yOrHeight, viewportWidth, viewportHeight) {
+  return {
+    x: resolveLength(xOrWidth, viewportWidth),
+    y: resolveLength(yOrHeight, viewportHeight)
+  };
+}
+
+/**
+ * Compute the normalized diagonal for resolving percentages that
+ * aren't clearly x or y oriented (per SVG spec).
+ * Formula: sqrt(width^2 + height^2) / sqrt(2)
+ *
+ * @param {Decimal} width - Viewport width
+ * @param {Decimal} height - Viewport height
+ * @returns {Decimal} Normalized diagonal
+ */
+export function normalizedDiagonal(width, height) {
+  const w = new Decimal(width);
+  const h = new Decimal(height);
+  const sqrt2 = Decimal.sqrt(2);
+  return Decimal.sqrt(w.mul(w).plus(h.mul(h))).div(sqrt2);
+}
+
+// ============================================================================
+// Object Bounding Box Transform
+// ============================================================================
+
+/**
+ * Create a transformation matrix for objectBoundingBox coordinates.
+ * Maps (0,0) to (bboxX, bboxY) and (1,1) to (bboxX+bboxW, bboxY+bboxH).
+ *
+ * @param {number|Decimal} bboxX - Bounding box X
+ * @param {number|Decimal} bboxY - Bounding box Y
+ * @param {number|Decimal} bboxWidth - Bounding box width
+ * @param {number|Decimal} bboxHeight - Bounding box height
+ * @returns {Matrix} 3x3 transformation matrix
+ */
+export function objectBoundingBoxTransform(bboxX, bboxY, bboxWidth, bboxHeight) {
+  const D = x => new Decimal(x);
+  // Transform: scale(bboxWidth, bboxHeight) then translate(bboxX, bboxY)
+  const scaleM = Transforms2D.scale(bboxWidth, bboxHeight);
+  const translateM = Transforms2D.translation(bboxX, bboxY);
+  return translateM.mul(scaleM);
+}
+
+// ============================================================================
+// Transform Parsing (existing code)
+// ============================================================================
+
+/**
+ * Parse a single SVG transform function and return a 3x3 matrix.
+ * Supports: translate, scale, rotate, skewX, skewY, matrix
+ *
+ * @param {string} func - Transform function name
+ * @param {number[]} args - Numeric arguments
+ * @returns {Matrix} 3x3 transformation matrix
+ */
+export function parseTransformFunction(func, args) {
+  const D = x => new Decimal(x);
+
+  switch (func.toLowerCase()) {
+    case 'translate': {
+      const tx = args[0] || 0;
+      const ty = args[1] || 0;
+      return Transforms2D.translation(tx, ty);
+    }
+
+    case 'scale': {
+      const sx = args[0] || 1;
+      const sy = args[1] !== undefined ? args[1] : sx;
+      return Transforms2D.scale(sx, sy);
+    }
+
+    case 'rotate': {
+      // SVG rotate is in degrees, can have optional cx, cy
+      const angleDeg = args[0] || 0;
+      const angleRad = D(angleDeg).mul(D(Math.PI)).div(180);
+
+      if (args.length >= 3) {
+        // rotate(angle, cx, cy) - rotation around point
+        const cx = args[1];
+        const cy = args[2];
+        return Transforms2D.rotateAroundPoint(angleRad, cx, cy);
+      }
+      return Transforms2D.rotate(angleRad);
+    }
+
+    case 'skewx': {
+      const angleDeg = args[0] || 0;
+      const angleRad = D(angleDeg).mul(D(Math.PI)).div(180);
+      const tanVal = Decimal.tan(angleRad);
+      return Transforms2D.skew(tanVal, 0);
+    }
+
+    case 'skewy': {
+      const angleDeg = args[0] || 0;
+      const angleRad = D(angleDeg).mul(D(Math.PI)).div(180);
+      const tanVal = Decimal.tan(angleRad);
+      return Transforms2D.skew(0, tanVal);
+    }
+
+    case 'matrix': {
+      // matrix(a, b, c, d, e, f) -> | a c e |
+      //                             | b d f |
+      //                             | 0 0 1 |
+      const [a, b, c, d, e, f] = args.map(x => D(x || 0));
+      return Matrix.from([
+        [a, c, e],
+        [b, d, f],
+        [D(0), D(0), D(1)]
+      ]);
+    }
+
+    default:
+      console.warn(`Unknown transform function: ${func}`);
+      return Matrix.identity(3);
+  }
+}
+
+/**
+ * Parse an SVG transform attribute string into a combined matrix.
+ * Handles multiple transforms: "translate(10,20) rotate(45) scale(2)"
+ *
+ * @param {string} transformStr - SVG transform attribute value
+ * @returns {Matrix} Combined 3x3 transformation matrix
+ */
+export function parseTransformAttribute(transformStr) {
+  if (!transformStr || transformStr.trim() === '') {
+    return Matrix.identity(3);
+  }
+
+  // Regex to match transform functions: name(args)
+  const transformRegex = /(\w+)\s*\(([^)]*)\)/g;
+  let match;
+  let result = Matrix.identity(3);
+
+  while ((match = transformRegex.exec(transformStr)) !== null) {
+    const func = match[1];
+    const argsStr = match[2];
+
+    // Parse arguments (comma or space separated)
+    const args = argsStr
+      .split(/[\s,]+/)
+      .filter(s => s.length > 0)
+      .map(s => parseFloat(s));
+
+    const matrix = parseTransformFunction(func, args);
+    // Transforms are applied left-to-right in SVG, so we multiply in order
+    result = result.mul(matrix);
+  }
+
+  return result;
+}
+
+/**
+ * Build the CTM (Current Transform Matrix) for an element by walking up its ancestry.
+ *
+ * @param {Object[]} transformStack - Array of transform strings from root to element
+ * @returns {Matrix} Combined CTM as 3x3 matrix
+ */
+export function buildCTM(transformStack) {
+  let ctm = Matrix.identity(3);
+
+  for (const transformStr of transformStack) {
+    if (transformStr) {
+      const matrix = parseTransformAttribute(transformStr);
+      ctm = ctm.mul(matrix);
+    }
+  }
+
+  return ctm;
+}
+
+/**
+ * Apply a CTM to a 2D point.
+ *
+ * @param {Matrix} ctm - 3x3 transformation matrix
+ * @param {number|string|Decimal} x - X coordinate
+ * @param {number|string|Decimal} y - Y coordinate
+ * @returns {{x: Decimal, y: Decimal}} Transformed coordinates
+ */
+export function applyToPoint(ctm, x, y) {
+  const [tx, ty] = Transforms2D.applyTransform(ctm, x, y);
+  return { x: tx, y: ty };
+}
+
+/**
+ * Convert a CTM back to SVG matrix() notation.
+ *
+ * @param {Matrix} ctm - 3x3 transformation matrix
+ * @param {number} [precision=6] - Decimal places for output
+ * @returns {string} SVG matrix transform string
+ */
+export function toSVGMatrix(ctm, precision = 6) {
+  const a = ctm.data[0][0].toFixed(precision);
+  const b = ctm.data[1][0].toFixed(precision);
+  const c = ctm.data[0][1].toFixed(precision);
+  const d = ctm.data[1][1].toFixed(precision);
+  const e = ctm.data[0][2].toFixed(precision);
+  const f = ctm.data[1][2].toFixed(precision);
+
+  return `matrix(${a}, ${b}, ${c}, ${d}, ${e}, ${f})`;
+}
+
+/**
+ * Check if a matrix is effectively the identity matrix.
+ *
+ * @param {Matrix} m - 3x3 matrix to check
+ * @param {string} [tolerance='1e-10'] - Tolerance for comparison
+ * @returns {boolean} True if matrix is identity within tolerance
+ */
+export function isIdentity(m, tolerance = '1e-10') {
+  const identity = Matrix.identity(3);
+  return m.equals(identity, tolerance);
+}
+
+/**
+ * Transform path data coordinates using a CTM.
+ * Handles M, L, C, Q, S, T, A, Z commands (absolute only for now).
+ *
+ * @param {string} pathData - SVG path d attribute
+ * @param {Matrix} ctm - 3x3 transformation matrix
+ * @returns {string} Transformed path data
+ */
+export function transformPathData(pathData, ctm) {
+  // Simple regex-based path parser for common commands
+  const result = [];
+  const commandRegex = /([MLHVCSQTAZ])([^MLHVCSQTAZ]*)/gi;
+  let match;
+
+  while ((match = commandRegex.exec(pathData)) !== null) {
+    const cmd = match[1];
+    const argsStr = match[2].trim();
+    const args = argsStr
+      .split(/[\s,]+/)
+      .filter(s => s.length > 0)
+      .map(s => parseFloat(s));
+
+    const cmdUpper = cmd.toUpperCase();
+
+    switch (cmdUpper) {
+      case 'M':
+      case 'L':
+      case 'T': {
+        // Pairs of coordinates
+        const transformed = [];
+        for (let i = 0; i < args.length; i += 2) {
+          const { x, y } = applyToPoint(ctm, args[i], args[i + 1]);
+          transformed.push(x.toFixed(6), y.toFixed(6));
+        }
+        result.push(cmd + ' ' + transformed.join(' '));
+        break;
+      }
+
+      case 'H': {
+        // Horizontal line - becomes L after transform
+        const { x, y } = applyToPoint(ctm, args[0], 0);
+        result.push('L ' + x.toFixed(6) + ' ' + y.toFixed(6));
+        break;
+      }
+
+      case 'V': {
+        // Vertical line - becomes L after transform
+        const { x, y } = applyToPoint(ctm, 0, args[0]);
+        result.push('L ' + x.toFixed(6) + ' ' + y.toFixed(6));
+        break;
+      }
+
+      case 'C': {
+        // Cubic bezier: 3 pairs of coordinates
+        const transformed = [];
+        for (let i = 0; i < args.length; i += 2) {
+          const { x, y } = applyToPoint(ctm, args[i], args[i + 1]);
+          transformed.push(x.toFixed(6), y.toFixed(6));
+        }
+        result.push('C ' + transformed.join(' '));
+        break;
+      }
+
+      case 'S': {
+        // Smooth cubic: 2 pairs of coordinates
+        const transformed = [];
+        for (let i = 0; i < args.length; i += 2) {
+          const { x, y } = applyToPoint(ctm, args[i], args[i + 1]);
+          transformed.push(x.toFixed(6), y.toFixed(6));
+        }
+        result.push('S ' + transformed.join(' '));
+        break;
+      }
+
+      case 'Q': {
+        // Quadratic bezier: 2 pairs of coordinates
+        const transformed = [];
+        for (let i = 0; i < args.length; i += 2) {
+          const { x, y } = applyToPoint(ctm, args[i], args[i + 1]);
+          transformed.push(x.toFixed(6), y.toFixed(6));
+        }
+        result.push('Q ' + transformed.join(' '));
+        break;
+      }
+
+      case 'A': {
+        // Arc: rx ry x-axis-rotation large-arc-flag sweep-flag x y
+        // Transform end point, scale radii (approximate for non-uniform scale)
+        const transformed = [];
+        for (let i = 0; i < args.length; i += 7) {
+          const rx = args[i];
+          const ry = args[i + 1];
+          const rotation = args[i + 2];
+          const largeArc = args[i + 3];
+          const sweep = args[i + 4];
+          const x = args[i + 5];
+          const y = args[i + 6];
+
+          const { x: tx, y: ty } = applyToPoint(ctm, x, y);
+
+          // Scale radii approximately (doesn't handle rotation correctly for skew)
+          const scaleX = ctm.data[0][0].abs().plus(ctm.data[0][1].abs()).div(2);
+          const scaleY = ctm.data[1][0].abs().plus(ctm.data[1][1].abs()).div(2);
+
+          transformed.push(
+            (rx * scaleX.toNumber()).toFixed(6),
+            (ry * scaleY.toNumber()).toFixed(6),
+            rotation,
+            largeArc,
+            sweep,
+            tx.toFixed(6),
+            ty.toFixed(6)
+          );
+        }
+        result.push('A ' + transformed.join(' '));
+        break;
+      }
+
+      case 'Z': {
+        result.push('Z');
+        break;
+      }
+
+      default:
+        // Keep unknown commands as-is
+        result.push(cmd + ' ' + argsStr);
+    }
+  }
+
+  return result.join(' ');
+}
+
+/**
+ * Information about precision comparison between float and Decimal.
+ */
+export const PRECISION_INFO = {
+  floatError: 0.0143,  // Typical error: 10 -> 9.9857
+  decimalPrecision: 80,
+  typicalRoundTripError: '2e-79',
+  improvementFactor: '1.43e+77'
+};
+
+export default {
+  // viewBox and preserveAspectRatio
+  parseViewBox,
+  parsePreserveAspectRatio,
+  computeViewBoxTransform,
+  SVGViewport,
+  buildFullCTM,
+  // Unit resolution
+  resolveLength,
+  resolvePercentages,
+  normalizedDiagonal,
+  // Object bounding box
+  objectBoundingBoxTransform,
+  // Transform parsing
+  parseTransformFunction,
+  parseTransformAttribute,
+  buildCTM,
+  applyToPoint,
+  toSVGMatrix,
+  isIdentity,
+  transformPathData,
+  PRECISION_INFO
+};