@emasoft/svg-matrix 1.0.18 → 1.0.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emasoft/svg-matrix",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "description": "Arbitrary-precision matrix, vector and affine transformation library for JavaScript using decimal.js",
   "type": "module",
   "main": "src/index.js",
@@ -9,6 +9,8 @@
     "test:browser": "node test/browser-verify.mjs",
     "test:playwright": "node test/playwright-diagnose.js",
     "ci-test": "npm ci && npm test",
+    "lint": "node bin/svglinter.cjs",
+    "lint:fix": "node bin/svglinter.cjs --fix",
     "version:sync": "node scripts/version-sync.js",
     "version:check": "node scripts/version-sync.js --check",
     "preversion": "npm run version:sync",
@@ -52,7 +54,8 @@
     "url": "https://github.com/Emasoft/SVG-MATRIX/issues"
   },
   "bin": {
-    "svg-matrix": "./bin/svg-matrix.js"
+    "svg-matrix": "./bin/svg-matrix.js",
+    "svglinter": "./bin/svglinter.cjs"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -74,5 +77,8 @@
     "playwright": {
       "optional": true
     }
+  },
+  "devDependencies": {
+    "svgo": "^4.0.0"
   }
 }

package/scripts/postinstall.js

@@ -114,15 +114,12 @@ ${c.cyan}${B.v}${hr}${B.v}${c.reset}
 ${c.cyan}${B.v}${c.reset}${R('')}${c.cyan}${B.v}${c.reset}
 ${c.cyan}${B.v}${c.reset}${R(`  ${c.yellow}CLI Commands:${c.reset}`)}${c.cyan}${B.v}${c.reset}
 ${c.cyan}${B.v}${c.reset}${R('')}${c.cyan}${B.v}${c.reset}
-${c.cyan}${B.v}${c.reset}${R(`  ${c.green}svg-matrix flatten${c.reset} input.svg -o output.svg`)}${c.cyan}${B.v}${c.reset}
-${c.cyan}${B.v}${c.reset}${R(`    ${c.dim}Bake all transforms into path coordinates${c.reset}`)}${c.cyan}${B.v}${c.reset}
+${c.cyan}${B.v}${c.reset}${R(`  ${c.green}svg-matrix flatten${c.reset}   ${c.dim}Bake transforms into path coordinates${c.reset}`)}${c.cyan}${B.v}${c.reset}
+${c.cyan}${B.v}${c.reset}${R(`  ${c.green}svg-matrix convert${c.reset}   ${c.dim}Convert shapes to <path> elements${c.reset}`)}${c.cyan}${B.v}${c.reset}
+${c.cyan}${B.v}${c.reset}${R(`  ${c.green}svg-matrix normalize${c.reset} ${c.dim}Convert paths to cubic Beziers${c.reset}`)}${c.cyan}${B.v}${c.reset}
+${c.cyan}${B.v}${c.reset}${R(`  ${c.green}svg-matrix info${c.reset}      ${c.dim}Show SVG file information${c.reset}`)}${c.cyan}${B.v}${c.reset}
 ${c.cyan}${B.v}${c.reset}${R('')}${c.cyan}${B.v}${c.reset}
-${c.cyan}${B.v}${c.reset}${R(`  ${c.green}Options:${c.reset}`)}${c.cyan}${B.v}${c.reset}
-${c.cyan}${B.v}${c.reset}${R(`    ${c.dim}--precision N${c.reset}       Output decimal places (default: 6)`)}${c.cyan}${B.v}${c.reset}
-${c.cyan}${B.v}${c.reset}${R(`    ${c.dim}--clip-segments N${c.reset}   Polygon sampling for clips (default: 64)`)}${c.cyan}${B.v}${c.reset}
-${c.cyan}${B.v}${c.reset}${R(`    ${c.dim}--bezier-arcs N${c.reset}     Bezier arcs for curves (default: 8)`)}${c.cyan}${B.v}${c.reset}
-${c.cyan}${B.v}${c.reset}${R(`    ${c.dim}--e2e-tolerance N${c.reset}   Verification tolerance (default: 1e-10)`)}${c.cyan}${B.v}${c.reset}
-${c.cyan}${B.v}${c.reset}${R(`    ${c.dim}--verbose${c.reset}           Show processing details`)}${c.cyan}${B.v}${c.reset}
+${c.cyan}${B.v}${c.reset}${R(`  ${c.dim}Run${c.reset} svg-matrix --help ${c.dim}or${c.reset} svg-matrix <cmd> --help`)}${c.cyan}${B.v}${c.reset}
 ${c.cyan}${B.v}${c.reset}${R('')}${c.cyan}${B.v}${c.reset}
 ${c.cyan}${B.v}${hr}${B.v}${c.reset}
 ${c.cyan}${B.v}${c.reset}${R('')}${c.cyan}${B.v}${c.reset}
@@ -137,7 +134,7 @@ ${c.cyan}${B.v}${c.reset}${R(`  ${c.green}${B.dot} Transforms3D${c.reset}  3D af
 ${c.cyan}${B.v}${c.reset}${R('')}${c.cyan}${B.v}${c.reset}
 ${c.cyan}${B.v}${hr}${B.v}${c.reset}
 ${c.cyan}${B.v}${c.reset}${R('')}${c.cyan}${B.v}${c.reset}
-${c.cyan}${B.v}${c.reset}${R(`  ${c.yellow}New in v1.0.18:${c.reset}`)}${c.cyan}${B.v}${c.reset}
+${c.cyan}${B.v}${c.reset}${R(`  ${c.yellow}New in v1.0.19:${c.reset}`)}${c.cyan}${B.v}${c.reset}
 ${c.cyan}${B.v}${c.reset}${R(`  ${c.green}${B.dot}${c.reset} Enhanced CLI help: svg-matrix <command> --help`)}${c.cyan}${B.v}${c.reset}
 ${c.cyan}${B.v}${c.reset}${R(`  ${c.green}${B.dot}${c.reset} High-precision Bezier circle/ellipse approximation`)}${c.cyan}${B.v}${c.reset}
 ${c.cyan}${B.v}${c.reset}${R(`  ${c.green}${B.dot}${c.reset} E2E verification always enabled for precision`)}${c.cyan}${B.v}${c.reset}

package/src/animation-optimization.js

@@ -0,0 +1,394 @@
+/**
+ * Animation Timing Optimization for SVG
+ *
+ * Optimizes SMIL animation timing attributes without breaking animations:
+ *
+ * 1. keySplines optimization:
+ *    - Remove leading zeros (0.4 -> .4)
+ *    - Remove trailing zeros (0.500 -> .5)
+ *    - Precision reduction with configurable decimal places
+ *    - Detect linear splines (0 0 1 1) and simplify calcMode
+ *
+ * 2. keyTimes optimization:
+ *    - Remove redundant precision
+ *    - Normalize separator spacing
+ *
+ * 3. values optimization:
+ *    - Numeric precision reduction for numeric values
+ *    - Preserve ID references (#frame1;#frame2) exactly
+ *
+ * @module animation-optimization
+ */
+
+import Decimal from 'decimal.js';
+
+// Configure Decimal for high precision internally
+Decimal.set({ precision: 20, rounding: Decimal.ROUND_HALF_UP });
+
+/**
+ * Standard easing curves that can be recognized
+ * Format: [x1, y1, x2, y2] control points
+ */
+export const STANDARD_EASINGS = {
+  linear: [0, 0, 1, 1],
+  ease: [0.25, 0.1, 0.25, 1],
+  'ease-in': [0.42, 0, 1, 1],
+  'ease-out': [0, 0, 0.58, 1],
+  'ease-in-out': [0.42, 0, 0.58, 1],
+};
+
+/**
+ * Format a number with optimal precision (no trailing zeros, no leading zero for decimals < 1)
+ * @param {number|string} value - Number to format
+ * @param {number} precision - Maximum decimal places (default: 3)
+ * @returns {string} Optimized number string
+ */
+export function formatSplineValue(value, precision = 3) {
+  const num = new Decimal(value);
+
+  // Round to precision
+  const rounded = num.toDecimalPlaces(precision);
+
+  // Convert to string
+  let str = rounded.toString();
+
+  // Remove trailing zeros after decimal point
+  if (str.includes('.')) {
+    str = str.replace(/\.?0+$/, '');
+  }
+
+  // Remove leading zero for values between -1 and 1 (exclusive)
+  if (str.startsWith('0.')) {
+    str = str.substring(1); // "0.5" -> ".5"
+  } else if (str.startsWith('-0.')) {
+    str = '-' + str.substring(2); // "-0.5" -> "-.5"
+  }
+
+  // Handle edge case: ".0" should be "0"
+  if (str === '' || str === '.') str = '0';
+
+  return str;
+}
+
+/**
+ * Parse a keySplines attribute value into array of spline arrays
+ * Each spline has 4 values: [x1, y1, x2, y2]
+ * @param {string} keySplines - keySplines attribute value
+ * @returns {number[][]} Array of [x1, y1, x2, y2] arrays
+ */
+export function parseKeySplines(keySplines) {
+  if (!keySplines || typeof keySplines !== 'string') return [];
+
+  // Split by semicolon to get individual splines
+  const splines = keySplines.split(';').map(s => s.trim()).filter(s => s);
+
+  return splines.map(spline => {
+    // Split by whitespace or comma to get control points
+    const values = spline.split(/[\s,]+/).map(v => parseFloat(v));
+    return values;
+  });
+}
+
+/**
+ * Serialize splines array back to keySplines attribute format
+ * @param {number[][]} splines - Array of [x1, y1, x2, y2] arrays
+ * @param {number} precision - Maximum decimal places
+ * @returns {string} keySplines attribute value
+ */
+export function serializeKeySplines(splines, precision = 3) {
+  return splines.map(spline => {
+    return spline.map(v => formatSplineValue(v, precision)).join(' ');
+  }).join('; ');
+}
+
+/**
+ * Check if a spline is effectively linear (0 0 1 1)
+ * @param {number[]} spline - [x1, y1, x2, y2] control points
+ * @param {number} tolerance - Comparison tolerance (default: 0.001)
+ * @returns {boolean} True if spline is linear
+ */
+export function isLinearSpline(spline, tolerance = 0.001) {
+  if (!spline || spline.length !== 4) return false;
+
+  const [x1, y1, x2, y2] = spline;
+  return (
+    Math.abs(x1) < tolerance &&
+    Math.abs(y1) < tolerance &&
+    Math.abs(x2 - 1) < tolerance &&
+    Math.abs(y2 - 1) < tolerance
+  );
+}
+
+/**
+ * Check if all splines in a keySplines value are linear
+ * @param {string} keySplines - keySplines attribute value
+ * @returns {boolean} True if all splines are linear
+ */
+export function areAllSplinesLinear(keySplines) {
+  const splines = parseKeySplines(keySplines);
+  if (splines.length === 0) return false;
+  // Must wrap in arrow function to avoid .every() passing index as tolerance
+  return splines.every(s => isLinearSpline(s));
+}
+
+/**
+ * Identify if a spline matches a standard CSS easing
+ * @param {number[]} spline - [x1, y1, x2, y2] control points
+ * @param {number} tolerance - Comparison tolerance
+ * @returns {string|null} Easing name or null if not standard
+ */
+export function identifyStandardEasing(spline, tolerance = 0.01) {
+  if (!spline || spline.length !== 4) return null;
+
+  for (const [name, standard] of Object.entries(STANDARD_EASINGS)) {
+    const matches = spline.every((val, i) => Math.abs(val - standard[i]) < tolerance);
+    if (matches) return name;
+  }
+  return null;
+}
+
+/**
+ * Optimize a keySplines attribute value
+ * @param {string} keySplines - Original keySplines value
+ * @param {Object} options - Optimization options
+ * @param {number} options.precision - Max decimal places (default: 3)
+ * @param {boolean} options.removeLinear - If true and all splines are linear, return null (default: true)
+ * @returns {{value: string|null, allLinear: boolean, standardEasings: string[]}}
+ */
+export function optimizeKeySplines(keySplines, options = {}) {
+  const precision = options.precision ?? 3;
+  const removeLinear = options.removeLinear !== false;
+
+  const splines = parseKeySplines(keySplines);
+
+  if (splines.length === 0) {
+    return { value: null, allLinear: false, standardEasings: [] };
+  }
+
+  // Check for all linear splines (wrap to avoid .every() passing index as tolerance)
+  const allLinear = splines.every(s => isLinearSpline(s));
+
+  // Identify standard easings
+  const standardEasings = splines.map(s => identifyStandardEasing(s)).filter(Boolean);
+
+  // If all linear and removeLinear is true, suggest removing keySplines
+  if (allLinear && removeLinear) {
+    return { value: null, allLinear: true, standardEasings };
+  }
+
+  // Optimize each spline value with precision
+  const optimized = serializeKeySplines(splines, precision);
+
+  return { value: optimized, allLinear, standardEasings };
+}
+
+/**
+ * Parse keyTimes attribute value
+ * @param {string} keyTimes - keyTimes attribute value
+ * @returns {number[]} Array of time values
+ */
+export function parseKeyTimes(keyTimes) {
+  if (!keyTimes || typeof keyTimes !== 'string') return [];
+  return keyTimes.split(';').map(s => parseFloat(s.trim())).filter(v => !isNaN(v));
+}
+
+/**
+ * Serialize keyTimes array back to attribute format
+ * @param {number[]} times - Array of time values
+ * @param {number} precision - Maximum decimal places
+ * @returns {string} keyTimes attribute value
+ */
+export function serializeKeyTimes(times, precision = 3) {
+  return times.map(t => formatSplineValue(t, precision)).join('; ');
+}
+
+/**
+ * Optimize keyTimes attribute value
+ * @param {string} keyTimes - Original keyTimes value
+ * @param {number} precision - Max decimal places (default: 3)
+ * @returns {string} Optimized keyTimes value
+ */
+export function optimizeKeyTimes(keyTimes, precision = 3) {
+  const times = parseKeyTimes(keyTimes);
+  if (times.length === 0) return keyTimes;
+  return serializeKeyTimes(times, precision);
+}
+
+/**
+ * Optimize numeric values in animation values attribute
+ * Preserves ID references (#id) exactly
+ * @param {string} values - values attribute
+ * @param {number} precision - Max decimal places for numbers
+ * @returns {string} Optimized values
+ */
+export function optimizeAnimationValues(values, precision = 3) {
+  if (!values || typeof values !== 'string') return values;
+
+  // Split by semicolon
+  const parts = values.split(';');
+
+  const optimized = parts.map(part => {
+    const trimmed = part.trim();
+
+    // Preserve ID references exactly
+    if (trimmed.startsWith('#') || trimmed.includes('url(')) {
+      return trimmed;
+    }
+
+    // Try to parse as numbers (could be space-separated like "0 0" for translate)
+    const nums = trimmed.split(/[\s,]+/);
+    const optimizedNums = nums.map(n => {
+      const num = parseFloat(n);
+      if (isNaN(num)) return n; // Not a number, preserve as-is
+      return formatSplineValue(num, precision);
+    });
+
+    return optimizedNums.join(' ');
+  });
+
+  return optimized.join('; ');
+}
+
+/**
+ * Optimize all animation timing attributes on an element
+ * @param {Element} el - SVG element (animate, animateTransform, etc.)
+ * @param {Object} options - Optimization options
+ * @returns {{modified: boolean, changes: string[]}}
+ */
+export function optimizeElementTiming(el, options = {}) {
+  const precision = options.precision ?? 3;
+  const removeLinearSplines = options.removeLinearSplines !== false;
+  const optimizeValues = options.optimizeValues !== false;
+
+  const changes = [];
+  let modified = false;
+
+  // Optimize keySplines
+  const keySplines = el.getAttribute('keySplines');
+  if (keySplines) {
+    const result = optimizeKeySplines(keySplines, { precision, removeLinear: removeLinearSplines });
+
+    if (result.allLinear && removeLinearSplines) {
+      // All splines are linear - can simplify to calcMode="linear"
+      const calcMode = el.getAttribute('calcMode');
+      if (calcMode === 'spline') {
+        el.setAttribute('calcMode', 'linear');
+        el.removeAttribute('keySplines');
+        changes.push('Converted linear splines to calcMode="linear"');
+        modified = true;
+      }
+    } else if (result.value && result.value !== keySplines) {
+      el.setAttribute('keySplines', result.value);
+      changes.push(`keySplines: "${keySplines}" -> "${result.value}"`);
+      modified = true;
+    }
+  }
+
+  // Optimize keyTimes
+  const keyTimes = el.getAttribute('keyTimes');
+  if (keyTimes) {
+    const optimized = optimizeKeyTimes(keyTimes, precision);
+    if (optimized !== keyTimes) {
+      el.setAttribute('keyTimes', optimized);
+      changes.push(`keyTimes: "${keyTimes}" -> "${optimized}"`);
+      modified = true;
+    }
+  }
+
+  // Optimize values (only numeric, preserve ID refs)
+  if (optimizeValues) {
+    const values = el.getAttribute('values');
+    if (values && !values.includes('#')) {
+      // Only optimize if no ID references
+      const optimized = optimizeAnimationValues(values, precision);
+      if (optimized !== values) {
+        el.setAttribute('values', optimized);
+        changes.push(`values: "${values}" -> "${optimized}"`);
+        modified = true;
+      }
+    }
+  }
+
+  // Optimize from/to
+  for (const attr of ['from', 'to', 'by']) {
+    const val = el.getAttribute(attr);
+    if (val && !val.includes('#')) {
+      const optimized = optimizeAnimationValues(val, precision);
+      if (optimized !== val) {
+        el.setAttribute(attr, optimized);
+        changes.push(`${attr}: "${val}" -> "${optimized}"`);
+        modified = true;
+      }
+    }
+  }
+
+  return { modified, changes };
+}
+
+/**
+ * Animation elements that can have timing attributes
+ * Note: all lowercase to match svg-parser tagName normalization
+ */
+export const ANIMATION_ELEMENTS = ['animate', 'animatetransform', 'animatemotion', 'animatecolor', 'set'];
+
+/**
+ * Optimize all animation timing in an SVG document
+ * @param {Element} root - SVG root element
+ * @param {Object} options - Optimization options
+ * @returns {{elementsModified: number, totalChanges: number, details: Array}}
+ */
+export function optimizeDocumentAnimationTiming(root, options = {}) {
+  let elementsModified = 0;
+  let totalChanges = 0;
+  const details = [];
+
+  const processElement = (el) => {
+    const tagName = el.tagName?.toLowerCase();
+
+    if (ANIMATION_ELEMENTS.includes(tagName)) {
+      const result = optimizeElementTiming(el, options);
+      if (result.modified) {
+        elementsModified++;
+        totalChanges += result.changes.length;
+        details.push({
+          element: tagName,
+          id: el.getAttribute('id') || null,
+          changes: result.changes
+        });
+      }
+    }
+
+    for (const child of el.children || []) {
+      processElement(child);
+    }
+  };
+
+  processElement(root);
+
+  return { elementsModified, totalChanges, details };
+}
+
+export default {
+  // Core functions
+  formatSplineValue,
+  parseKeySplines,
+  serializeKeySplines,
+  parseKeyTimes,
+  serializeKeyTimes,
+
+  // Analysis
+  isLinearSpline,
+  areAllSplinesLinear,
+  identifyStandardEasing,
+  STANDARD_EASINGS,
+
+  // Optimization
+  optimizeKeySplines,
+  optimizeKeyTimes,
+  optimizeAnimationValues,
+  optimizeElementTiming,
+  optimizeDocumentAnimationTiming,
+
+  // Constants
+  ANIMATION_ELEMENTS,
+};