@emasoft/svg-matrix 1.3.1 → 1.3.4

package/dist/version.json

@@ -1,38 +1,38 @@
 {
-  "version": "1.3.1",
-  "buildTime": "2026-01-09T17:20:51.504Z",
+  "version": "1.3.4",
+  "buildTime": "2026-01-25T12:44:06.936Z",
   "bundles": {
     "esm": [
       {
         "name": "svg-matrix.min.js",
-        "size": 56185,
-        "gzipSize": 19446,
+        "size": 56104,
+        "gzipSize": 19413,
         "description": "ESM bundle for bundlers/Node.js (includes decimal.js)"
       },
       {
         "name": "svg-toolbox.min.js",
-        "size": 577130,
-        "gzipSize": 152266,
+        "size": 577298,
+        "gzipSize": 152361,
         "description": "ESM bundle for bundlers/Node.js (includes decimal.js)"
       },
       {
         "name": "svgm.min.js",
-        "size": 602513,
-        "gzipSize": 159440,
+        "size": 602600,
+        "gzipSize": 159489,
         "description": "ESM bundle for bundlers/Node.js (includes decimal.js)"
       }
     ],
     "iife": [
       {
         "name": "svg-matrix.global.min.js",
-        "size": 56568,
-        "gzipSize": 19669,
+        "size": 56487,
+        "gzipSize": 19638,
         "description": "IIFE bundle for browsers via <script> (includes decimal.js)"
       },
       {
         "name": "svg-toolbox.global.min.js",
-        "size": 577259,
-        "gzipSize": 151635,
+        "size": 577427,
+        "gzipSize": 151728,
         "description": "IIFE bundle for browsers via <script> (includes decimal.js)"
       },
       {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emasoft/svg-matrix",
-  "version": "1.3.1",
+  "version": "1.3.4",
   "description": "Arbitrary-precision matrix, vector and affine transformation library for JavaScript using decimal.js",
   "type": "module",
   "main": "src/index.js",
@@ -24,7 +24,7 @@
     "version:sync": "node scripts/version-sync.js",
     "version:check": "node scripts/version-sync.js --check",
     "preversion": "npm run version:sync",
-    "version": "node scripts/version-sync.js && git add src/index.js package-lock.json",
+    "version": "node scripts/version-sync.js && git add src/index.js package-lock.json src/svg-matrix-lib.js src/svg-toolbox-lib.js src/svgm-lib.js",
     "prepublishOnly": "npm run build && npm run version:check && npm test",
     "postinstall": "node scripts/postinstall.js || true"
   },

package/scripts/version-sync.js

@@ -172,18 +172,24 @@ function updateLockfileVersion(version) {
   const filePath = join(ROOT, "package-lock.json");
   try {
     const lock = JSON.parse(readFileSync(filePath, "utf8"));
-    const original = JSON.stringify(lock);
+
+    // WHY: Compare version values directly instead of stringified JSON
+    // The old approach compared compact JSON vs pretty-printed JSON which always differed
+    const rootVersionMatch = lock.version === version;
+    const packageVersionMatch =
+      !lock.packages?.[""] || lock.packages[""].version === version;
+
+    if (rootVersionMatch && packageVersionMatch) {
+      return false; // No update needed
+    }
 
     lock.version = version;
     if (lock.packages && lock.packages[""]) {
       lock.packages[""].version = version;
     }
 
-    const updated = JSON.stringify(lock, null, 2) + "\n";
-    if (updated !== original) {
-      writeFileSync(filePath, updated, "utf8");
-      return true;
-    }
+    writeFileSync(filePath, JSON.stringify(lock, null, 2) + "\n", "utf8");
+    return true;
   } catch {
     // Lockfile might not exist
   }

package/src/animation-optimization.js

@@ -76,9 +76,10 @@ export function formatSplineValue(value, precision = 3) {
   // Convert to string
   let str = rounded.toString();
 
-  // Remove trailing zeros after decimal point
+  // Remove trailing zeros after decimal point (two-step to avoid "10.0" -> "1" bug)
   if (str.includes(".")) {
-    str = str.replace(/\.?0+$/, "");
+    str = str.replace(/0+$/, ""); // First remove trailing zeros
+    str = str.replace(/\.$/, ""); // Then remove orphan decimal point
   }
 
   // Remove leading zero for values between -1 and 1 (exclusive)

package/src/bezier-analysis.js

@@ -1589,7 +1589,8 @@ export function verifyCurvature(points, t, tolerance = "1e-10") {
 
   const t1 = Decimal.max(D(0), tD.minus(h));
   const t2 = Decimal.min(D(1), tD.plus(h));
-  const _actualH = t2.minus(t1);
+  // NOTE: Actual step size differs at boundaries, but curvature comparison
+  // uses arc length directly rather than parameter difference
 
   const tan1 = bezierTangent(points, t1);
   const tan2 = bezierTangent(points, t2);

package/src/bezier-intersections.js

@@ -40,6 +40,23 @@ const SINGULARITY_THRESHOLD = "1e-50"; // Below this, Jacobian considered singul
 const INTERSECTION_VERIFY_FACTOR = 100; // Multiplier for intersection verification
 const DEDUP_TOLERANCE_FACTOR = 1000; // Multiplier for duplicate detection
 
+/**
+ * Default tolerance for intersection detection.
+ * WHY: 1e-10 provides high precision while being practical for real-world use.
+ * This is much more lenient than the theoretical 1e-30 but still far more precise
+ * than float64 operations (~1e-15).
+ * @type {string}
+ */
+export const DEFAULT_INTERSECTION_TOLERANCE = "1e-10";
+
+/**
+ * Tolerance for svgpathtools-compatible behavior.
+ * WHY: svgpathtools uses float64 (15 digits) and typically finds intersections
+ * with ~4e-7 distance error. This tolerance ensures compatible results.
+ * @type {string}
+ */
+export const SVGPATHTOOLS_COMPATIBLE_TOLERANCE = "1e-6";
+
 /** Maximum Newton iterations for intersection refinement */
 const MAX_NEWTON_ITERATIONS = 30;
 
@@ -382,14 +399,18 @@ function refineBezierLineRoot(bezier, line, t0, t1, tol) {
  * @param {Array} bezier1 - First Bezier control points [[x,y], ...]
  * @param {Array} bezier2 - Second Bezier control points [[x,y], ...]
  * @param {Object} [options] - Options
- * @param {string} [options.tolerance='1e-30'] - Intersection tolerance
+ * @param {string} [options.tolerance=DEFAULT_INTERSECTION_TOLERANCE] - Intersection tolerance.
+ *   Use DEFAULT_INTERSECTION_TOLERANCE (1e-10) for high precision,
+ *   SVGPATHTOOLS_COMPATIBLE_TOLERANCE (1e-6) for svgpathtools-compatible results.
  * @param {number} [options.maxDepth=50] - Maximum recursion depth
  * @returns {Array} Intersections [{t1, t2, point, error}]
  */
 export function bezierBezierIntersection(bezier1, bezier2, options = {}) {
-  // WHY: Use named constant as default instead of hardcoded 50 for clarity
-  const { tolerance = "1e-30", maxDepth = MAX_INTERSECTION_RECURSION_DEPTH } =
-    options;
+  // WHY: Use named constants as defaults for clarity and easy configuration
+  const {
+    tolerance = DEFAULT_INTERSECTION_TOLERANCE,
+    maxDepth = MAX_INTERSECTION_RECURSION_DEPTH,
+  } = options;
 
   // Input validation
   if (!bezier1 || !Array.isArray(bezier1) || bezier1.length < 2) {
@@ -573,21 +594,24 @@ function refineIntersection(bez1, bez2, t1, t2, tol) {
       break;
     }
 
-    // Solve: J * [dt1, dt2]^T = -[fx, fy]^T
-    // dt1 = (-(-dy2)*(-fx) - (-dx2)*(-fy)) / det = (-dy2*fx + dx2*fy) / det
-    // dt2 = (dx1*(-fy) - dy1*(-fx)) / det = (-dx1*fy + dy1*fx) / det
+    // Solve: J * [dt1, dt2]^T = -[fx, fy]^T using Cramer's rule
+    // The Jacobian J = [[dx1, -dx2], [dy1, -dy2]], det(J) = dx2*dy1 - dx1*dy2
+    // For J^-1 * [-fx, -fy]^T:
+    // dt1 = (dy2*fx - dx2*fy) / det
+    // dt2 = (dy1*fx - dx1*fy) / det
+    // WHY: This is the correct Cramer's rule solution for the 2x2 linear system.
 
-    const dt1 = dy2.neg().times(fx).plus(dx2.times(fy)).div(det);
-    const dt2 = dx1.neg().times(fy).plus(dy1.times(fx)).div(det);
+    const dt1 = dy2.times(fx).minus(dx2.times(fy)).div(det);
+    const dt2 = dy1.times(fx).minus(dx1.times(fy)).div(det);
 
     currentT1 = currentT1.plus(dt1);
     currentT2 = currentT2.plus(dt2);
 
     // Check for convergence by step size
     if (dt1.abs().lt(tol) && dt2.abs().lt(tol)) {
-      // BUGFIX: Compute fresh error value instead of using stale one from previous iteration
-      // WHY: The `error` variable computed above (line 553) is from before the parameter update,
-      // so it may not reflect the final accuracy. We need to recompute error for the converged parameters.
+      // BUGFIX: Compute fresh error value and verify it's within tolerance
+      // WHY: Step size convergence doesn't guarantee point accuracy.
+      // We must verify the final error meets the tolerance requirement.
       const [finalX, finalY] = bezierPoint(bez1, currentT1);
       const [finalX2, finalY2] = bezierPoint(bez2, currentT2);
       const finalError = D(finalX)
@@ -595,12 +619,19 @@ function refineIntersection(bez1, bez2, t1, t2, tol) {
         .pow(2)
         .plus(D(finalY).minus(D(finalY2)).pow(2))
         .sqrt();
-      return {
-        t1: currentT1,
-        t2: currentT2,
-        point: [finalX, finalY],
-        error: finalError,
-      };
+
+      // WHY: Only return if final error is within tolerance.
+      // This prevents returning false positives where Newton converged
+      // in parameter space but not in point distance space.
+      if (finalError.lt(tol)) {
+        return {
+          t1: currentT1,
+          t2: currentT2,
+          point: [finalX, finalY],
+          error: finalError,
+        };
+      }
+      // Step size converged but error too large - continue iterating
     }
   }
 
@@ -1953,6 +1984,10 @@ export function verifyAllIntersectionFunctions(tolerance = "1e-30") {
 // ============================================================================
 
 export default {
+  // Tolerance constants for configurable precision
+  DEFAULT_INTERSECTION_TOLERANCE,
+  SVGPATHTOOLS_COMPATIBLE_TOLERANCE,
+
   // Line-line
   lineLineIntersection,
 

package/src/convert-path-data.js

@@ -12,9 +12,8 @@
  * @module convert-path-data
  */
 
-import Decimal from "decimal.js";
-
-Decimal.set({ precision: 80 });
+// NOTE: This module uses native JavaScript Number/Math for all calculations.
+// For arbitrary-precision needs, see the main svg-matrix library.
 
 // SVG path command parameters count
 const COMMAND_PARAMS = {

package/src/flatten-pipeline.js

@@ -1659,6 +1659,8 @@ function getElementBBox(el) {
 
     return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
   } catch {
+    // Error is intentionally swallowed - invalid path data or polygon conversion
+    // failures are expected for some edge cases and should return null
     return null;
   }
 }

package/src/font-manager.js

@@ -511,8 +511,8 @@ export async function convertToWoff2(fontPath, options = {}) {
   }
 
   try {
-    // Use fonttools ttx to convert
-    execFileSync("fonttools", ["ttLib.woff2", "compress", fontPath, "-o", outputPath], {
+    // Use fonttools woff2 compress - output is positional argument, not -o flag
+    execFileSync("fonttools", ["ttLib.woff2", "compress", fontPath, outputPath], {
       stdio: "pipe",
       timeout: 60000,
     });

package/src/index.js

@@ -5,7 +5,7 @@
  * SVG path conversion, and 2D/3D affine transformations using Decimal.js.
  *
  * @module @emasoft/svg-matrix
- * @version 1.3.1
+ * @version 1.3.4
  * @license MIT
  *
  * @example
@@ -135,7 +135,7 @@ Decimal.set({ precision: 80 });
  * Library version
  * @constant {string}
  */
-export const VERSION = "1.3.1";
+export const VERSION = "1.3.4";
 
 /**
  * Default precision for path output (decimal places)

package/src/inkscape-support.js

@@ -528,11 +528,12 @@ export function cloneElement(element) {
   }
 
   // Create proper SVGElement with serialize() method
+  // Note: SVGElement constructor requires textContent to be a string, not null
   const clone = new SVGElement(
     element.tagName,
     attrs,
     clonedChildren,
-    element.textContent || null,
+    element.textContent || "",
   );
 
   return clone;

package/src/marker-resolver.js

@@ -378,6 +378,12 @@ export function getMarkerTransform(
   }
 
   // Step 4: Apply viewBox transformation if present
+  // BUG FIX: When viewBox has non-zero origin, the refX/refY are in viewBox coordinates.
+  // We must convert them to viewport coordinates before applying the ref translation.
+  // Transform chain: T_position * R * T(-ref_viewport) * S * T(-viewBox.origin)
+  let hasViewBox = false;
+  let viewBoxScaleFactor = 1;
+
   if (viewBox) {
     // Calculate scale factors to fit viewBox into marker viewport
     const vbWidth = viewBox.width;
@@ -397,30 +403,47 @@ export function getMarkerTransform(
       // Validate scale factors are finite
       if (isFinite(scaleFactorX) && isFinite(scaleFactorY)) {
         // For now, use uniform scaling (can be enhanced with full preserveAspectRatio parsing)
-        const scaleFactor = Math.min(scaleFactorX, scaleFactorY);
-
-        scaleX *= scaleFactor;
-        scaleY *= scaleFactor;
+        viewBoxScaleFactor = Math.min(scaleFactorX, scaleFactorY);
+        hasViewBox = true;
 
-        // Translate to account for viewBox origin
-        const viewBoxTranslate = Transforms2D.translation(
-          -viewBox.x,
-          -viewBox.y,
-        );
-        transform = transform.mul(viewBoxTranslate);
+        scaleX *= viewBoxScaleFactor;
+        scaleY *= viewBoxScaleFactor;
       }
     }
   }
 
-  // Apply combined scaling
-  if (scaleX !== 1 || scaleY !== 1) {
-    const scale = Transforms2D.scale(scaleX, scaleY);
-    transform = transform.mul(scale);
-  }
+  if (hasViewBox) {
+    // When viewBox is present, refX/refY are in viewBox coordinates.
+    // Convert to viewport (marker) coordinates by:
+    // 1. Subtract viewBox origin to get position relative to viewBox
+    // 2. Scale by viewBox scale factor to get position in marker viewport
+    const refViewportX = (refX - viewBox.x) * viewBoxScaleFactor;
+    const refViewportY = (refY - viewBox.y) * viewBoxScaleFactor;
+
+    // Apply ref translation in viewport coordinates (BEFORE scaling in the chain)
+    const refTranslate = Transforms2D.translation(-refViewportX, -refViewportY);
+    transform = transform.mul(refTranslate);
+
+    // Apply combined scaling
+    if (scaleX !== 1 || scaleY !== 1) {
+      const scale = Transforms2D.scale(scaleX, scaleY);
+      transform = transform.mul(scale);
+    }
+
+    // Apply viewBox origin translation (AFTER scaling, so it scales correctly)
+    const viewBoxTranslate = Transforms2D.translation(-viewBox.x, -viewBox.y);
+    transform = transform.mul(viewBoxTranslate);
+  } else {
+    // No viewBox: apply scaling then ref translation in original coordinates
+    if (scaleX !== 1 || scaleY !== 1) {
+      const scale = Transforms2D.scale(scaleX, scaleY);
+      transform = transform.mul(scale);
+    }
 
-  // Step 5: Translate by -refX, -refY
-  const refTranslate = Transforms2D.translation(-refX, -refY);
-  transform = transform.mul(refTranslate);
+    // Step 5: Translate by -refX, -refY
+    const refTranslate = Transforms2D.translation(-refX, -refY);
+    transform = transform.mul(refTranslate);
+  }
 
   return transform;
 }

package/src/mesh-gradient.js

@@ -161,17 +161,26 @@ export function parseColor(colorStr, opacity = 1) {
     return color(r, g, b, alphaClamped * 255 * opacity);
   }
 
-  // Handle hex colors
+  // Handle hex colors: #RGB, #RGBA, #RRGGBB, #RRGGBBAA (CSS Color Level 4)
   const hexMatch = colorStr.match(/^#([0-9a-f]{3,8})$/i);
   if (hexMatch) {
     const hex = hexMatch[1];
     if (hex.length === 3) {
+      // #RGB format - expand each digit to two (e.g., #F00 -> #FF0000)
       return color(
         parseInt(hex[0] + hex[0], 16),
         parseInt(hex[1] + hex[1], 16),
         parseInt(hex[2] + hex[2], 16),
         255 * opacity,
       );
+    } else if (hex.length === 4) {
+      // #RGBA format (CSS4) - expand each digit to two (e.g., #F00A -> #FF0000AA)
+      return color(
+        parseInt(hex[0] + hex[0], 16),
+        parseInt(hex[1] + hex[1], 16),
+        parseInt(hex[2] + hex[2], 16),
+        parseInt(hex[3] + hex[3], 16) * opacity,
+      );
     } else if (hex.length === 6) {
       return color(
         parseInt(hex.slice(0, 2), 16),

package/src/off-canvas-detection.js

@@ -1564,8 +1564,10 @@ export function clipPathToViewBox(pathCommands, viewBox) {
             continue;
           }
 
-          const x = D(cmd.x);
-          const y = D(cmd.y);
+          // BUG FIX: Handle relative coordinates (lowercase 'm')
+          const isRelative = cmd.type === cmd.type.toLowerCase();
+          const x = isRelative ? currentX.plus(D(cmd.x)) : D(cmd.x);
+          const y = isRelative ? currentY.plus(D(cmd.y)) : D(cmd.y);
 
           // Only add move if point is inside bounds
           if (pointInBBox({ x, y }, bounds)) {
@@ -1587,8 +1589,10 @@ export function clipPathToViewBox(pathCommands, viewBox) {
             continue;
           }
 
-          const x = D(cmd.x);
-          const y = D(cmd.y);
+          // BUG FIX: Handle relative coordinates (lowercase 'l')
+          const isRelative = cmd.type === cmd.type.toLowerCase();
+          const x = isRelative ? currentX.plus(D(cmd.x)) : D(cmd.x);
+          const y = isRelative ? currentY.plus(D(cmd.y)) : D(cmd.y);
 
           // Clip line segment
           const clipped = clipLine(
@@ -1629,7 +1633,9 @@ export function clipPathToViewBox(pathCommands, viewBox) {
             continue;
           }
 
-          const x = D(cmd.x);
+          // BUG FIX: Handle relative coordinates (lowercase 'h')
+          const isRelative = cmd.type === cmd.type.toLowerCase();
+          const x = isRelative ? currentX.plus(D(cmd.x)) : D(cmd.x);
           const clipped = clipLine(
             { x: currentX, y: currentY },
             { x, y: currentY },
@@ -1665,7 +1671,9 @@ export function clipPathToViewBox(pathCommands, viewBox) {
             continue;
           }
 
-          const y = D(cmd.y);
+          // BUG FIX: Handle relative coordinates (lowercase 'v')
+          const isRelative = cmd.type === cmd.type.toLowerCase();
+          const y = isRelative ? currentY.plus(D(cmd.y)) : D(cmd.y);
           const clipped = clipLine(
             { x: currentX, y: currentY },
             { x: currentX, y },
@@ -1708,8 +1716,10 @@ export function clipPathToViewBox(pathCommands, viewBox) {
           // BUG FIX: Sample the curve to better approximate clipping
           // A full implementation would clip curves exactly, but sampling provides
           // a reasonable approximation (WHY: curves can extend outside bounds even if endpoints are inside)
-          const x = D(cmd.x);
-          const y = D(cmd.y);
+          // BUG FIX: Handle relative coordinates (lowercase 'c', 's', 'q', 't', 'a')
+          const isRelative = cmd.type === cmd.type.toLowerCase();
+          const x = isRelative ? currentX.plus(D(cmd.x)) : D(cmd.x);
+          const y = isRelative ? currentY.plus(D(cmd.y)) : D(cmd.y);
 
           // Sample 10 points along the curve path from current to end
           const samples = 10;

package/src/path-simplification.js

@@ -1361,11 +1361,11 @@ export function removeZeroLengthSegments(pathData, tolerance = EPSILON) {
     currentY = D(0);
   let startX = D(0),
     startY = D(0);
-  // Track previous control points for S and T commands (reserved for future S/T command handling)
+  // Track previous control points for S and T commands (smooth Bezier continuity)
   let prevCp2X = null,
-    prevCp2Y = null; // For S command (cubic)
+    prevCp2Y = null; // For S command (cubic) - tracks 2nd control point of previous C/S
   let prevCpX = null,
-    prevCpY = null; // For T command (quadratic)
+    prevCpY = null; // For T command (quadratic) - tracks control point of previous Q/T
 
   for (let idx = 0; idx < pathData.length; idx++) {
     const item = pathData[idx];

package/src/svg-matrix-lib.js

@@ -5,7 +5,7 @@
  * Works in both Node.js and browser environments.
  *
  * @module svg-matrix-lib
- * @version 1.3.1
+ * @version 1.3.4
  * @license MIT
  *
  * @example Browser usage:
@@ -32,7 +32,7 @@ Decimal.set({ precision: 80 });
 /**
  * Library version
  */
-export const VERSION = "1.3.1";
+export const VERSION = "1.3.4";
 
 // Export core classes
 export { Decimal, Matrix, Vector };

package/src/svg-toolbox-lib.js

@@ -5,7 +5,7 @@
  * Provides 69+ operations for cleaning, optimizing, and transforming SVG files.
  *
  * @module svg-toolbox-lib
- * @version 1.3.1
+ * @version 1.3.4
  * @license MIT
  *
  * @example Browser usage:
@@ -34,7 +34,7 @@ import * as SVGToolboxModule from "./svg-toolbox.js";
 /**
  * Library version
  */
-export const VERSION = "1.3.1";
+export const VERSION = "1.3.4";
 
 /**
  * Default export for browser global (window.SVGToolbox)

package/src/svgm-lib.js

@@ -5,7 +5,7 @@
  * comprehensive SVG manipulation (SVGToolbox). Works in Node.js and browser.
  *
  * @module svgm-lib
- * @version 1.3.1
+ * @version 1.3.4
  * @license MIT
  *
  * @example Browser usage:
@@ -49,7 +49,7 @@ Decimal.set({ precision: 80 });
 /**
  * Library version
  */
-export const VERSION = "1.3.1";
+export const VERSION = "1.3.4";
 
 // Export math classes
 export { Decimal, Matrix, Vector };

package/src/transform-decomposition.js

@@ -294,7 +294,15 @@ export function decomposeMatrix(matrix) {
   }
 
   // Calculate rotation angle from first column
-  const rotation = Decimal.atan2(b, a);
+  // BUG FIX: When scaleX is negative (reflection), we must compute rotation from negated
+  // column vector to separate the reflection component from the rotation component.
+  // Without this fix, X-flip matrix(-1,0,0,1,0,0) gives rotation=π instead of 0.
+  let rotation;
+  if (scaleX.lessThan(0)) {
+    rotation = Decimal.atan2(b.neg(), a.neg());
+  } else {
+    rotation = Decimal.atan2(b, a);
+  }
 
   // Calculate skew
   // After removing rotation and scale, we get the skew

package/src/transforms3d.js

@@ -63,17 +63,9 @@ function normalizeAngle(theta) {
 
   // For large angles, normalize to [-2π, 2π] to reduce precision loss
   // Using modulo with 2π (tau) to find equivalent angle in standard range
+  // Note: modulo already guarantees result in (-2π, 2π) exclusive
   const TWO_PI = 6.283185307179586;
-  let normalized = tNum % TWO_PI;
-
-  // Ensure result is in [-2π, 2π] range
-  if (normalized > TWO_PI) {
-    normalized -= TWO_PI;
-  } else if (normalized < -TWO_PI) {
-    normalized += TWO_PI;
-  }
-
-  return normalized;
+  return tNum % TWO_PI;
 }
 
 /**
@@ -229,11 +221,8 @@ export function scale(sx, sy = null, sz = null) {
   const syD = D(syValue);
   const szD = D(szValue);
 
-  // Warn about zero scale factors creating singular matrices
-  if (sxD.isZero() || syD.isZero() || szD.isZero()) {
-    // Zero scale is mathematically valid but creates non-invertible matrix
-    // We allow it but document the behavior in JSDoc above
-  }
+  // Note: Zero scale factors create singular (non-invertible) matrices
+  // This is mathematically valid but cannot be reversed - documented in JSDoc above
 
   return Matrix.from([
     [sxD, new Decimal(0), new Decimal(0), new Decimal(0)],