svger-cli 3.1.0 → 4.0.0

package/dist/optimizers/tree-stages.js

@@ -0,0 +1,141 @@
+/**
+ * Tree-Based Optimization Stages
+ * Wrapper for tree-based optimizations in the optimizer pipeline
+ * Handles parse → optimize → serialize cycle
+ */
+import { parseSVG } from './svg-tree-parser.js';
+import { serializeSVGMinified } from './tree-serializer.js';
+import { removeUnusedDefsStage } from './remove-unused-defs.js';
+import { collapseUselessGroupsStage } from './collapse-useless-groups.js';
+import { moveAttributesToParentStage } from './move-attrs-to-parent.js';
+import { removeHiddenAndEmptyElementsStage } from './remove-hidden-empty.js';
+/**
+ * Tree-based optimization stage: Remove unused defs
+ */
+export async function treeRemoveUnusedDefsStage(svg, config) {
+    // Skip if not enabled for this level
+    if (config.level === 'none' || config.level === 'basic') {
+        return svg;
+    }
+    try {
+        const tree = parseSVG(svg);
+        if (!tree)
+            return svg;
+        const result = removeUnusedDefsStage(tree);
+        if (result.modified) {
+            return serializeSVGMinified(tree);
+        }
+        return svg;
+    }
+    catch (error) {
+        console.warn('Tree optimization (remove-unused-defs) failed:', error);
+        return svg;
+    }
+}
+/**
+ * Tree-based optimization stage: Collapse useless groups
+ */
+export async function treeCollapseGroupsStage(svg, config) {
+    // Only enabled for aggressive and maximum
+    if (!config.collapseGroups) {
+        return svg;
+    }
+    try {
+        const tree = parseSVG(svg);
+        if (!tree)
+            return svg;
+        const result = collapseUselessGroupsStage(tree);
+        if (result.modified) {
+            return serializeSVGMinified(tree);
+        }
+        return svg;
+    }
+    catch (error) {
+        console.warn('Tree optimization (collapse-groups) failed:', error);
+        return svg;
+    }
+}
+/**
+ * Tree-based optimization stage: Move attributes to parent
+ */
+export async function treeMoveAttributesToParentStage(svg, config) {
+    // Only enabled for aggressive and maximum
+    if (config.level === 'none' || config.level === 'basic') {
+        return svg;
+    }
+    try {
+        const tree = parseSVG(svg);
+        if (!tree)
+            return svg;
+        const result = moveAttributesToParentStage(tree);
+        if (result.modified) {
+            return serializeSVGMinified(tree);
+        }
+        return svg;
+    }
+    catch (error) {
+        console.warn('Tree optimization (move-attrs-to-parent) failed:', error);
+        return svg;
+    }
+}
+/**
+ * Tree-based optimization stage: Remove hidden and empty elements
+ */
+export async function treeRemoveHiddenEmptyStage(svg, config) {
+    // Enabled for balanced and above
+    if (!config.removeHiddenElements) {
+        return svg;
+    }
+    try {
+        const tree = parseSVG(svg);
+        if (!tree)
+            return svg;
+        const result = removeHiddenAndEmptyElementsStage(tree);
+        if (result.modified) {
+            return serializeSVGMinified(tree);
+        }
+        return svg;
+    }
+    catch (error) {
+        console.warn('Tree optimization (remove-hidden-empty) failed:', error);
+        return svg;
+    }
+}
+/**
+ * Combined tree-based optimization stage
+ * Applies all tree optimizations in one pass for efficiency
+ */
+export async function treeOptimizationStage(svg, config) {
+    // Skip tree optimizations for none and basic levels
+    if (config.level === 'none' || config.level === 'basic') {
+        return svg;
+    }
+    try {
+        const tree = parseSVG(svg);
+        if (!tree)
+            return svg;
+        let modified = false;
+        // Apply all tree-based optimizations
+        const stages = [
+            removeUnusedDefsStage,
+            removeHiddenAndEmptyElementsStage,
+            moveAttributesToParentStage,
+            collapseUselessGroupsStage,
+        ];
+        for (const stage of stages) {
+            const result = stage(tree);
+            if (result.modified) {
+                modified = true;
+            }
+        }
+        // Serialize only if modified
+        if (modified) {
+            return serializeSVGMinified(tree);
+        }
+        return svg;
+    }
+    catch (error) {
+        console.warn('Tree optimization failed:', error);
+        return svg;
+    }
+}

package/dist/optimizers/types.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Type definitions for Advanced SVG Optimizer
+ */
+/**
+ * Optimization level enum
+ */
+export declare enum OptLevel {
+    NONE = "none",
+    BASIC = "basic",
+    BALANCED = "balanced",
+    AGGRESSIVE = "aggressive",
+    MAXIMUM = "maximum"
+}
+/**
+ * Optimization configuration interface
+ */
+export interface OptConfig {
+    /**
+     * Optimization level
+     * @default 'balanced'
+     */
+    level: OptLevel;
+    /**
+     * Float precision for decimal numbers (1-4)
+     * @default 3
+     */
+    floatPrecision: 1 | 2 | 3 | 4;
+    /**
+     * Path simplification tolerance (0-1)
+     * Higher values = more aggressive simplification
+     * @default 0.5
+     */
+    pathTolerance: number;
+    /**
+     * Remove viewBox attribute
+     * @default false
+     */
+    removeViewBox: boolean;
+    /**
+     * Remove unnecessary XML declarations and metadata
+     * @default true
+     */
+    removeMetadata: boolean;
+    /**
+     * Remove comments
+     * @default true
+     */
+    removeComments: boolean;
+    /**
+     * Normalize whitespace
+     * @default true
+     */
+    normalizeWhitespace: boolean;
+    /**
+     * Remove unnecessary attributes
+     * @default true
+     */
+    removeUnnecessaryAttrs: boolean;
+    /**
+     * Convert colors to shortest form (#ffffff → #fff)
+     * @default true
+     */
+    shortenColors: boolean;
+    /**
+     * Merge paths when possible
+     * @default false (basic/balanced), true (aggressive/maximum)
+     */
+    mergePaths: boolean;
+    /**
+     * Remove hidden elements (opacity:0, display:none)
+     * @default false (basic), true (balanced+)
+     */
+    removeHiddenElements: boolean;
+    /**
+     * Convert style attributes to presentation attributes
+     * @default false
+     */
+    inlineStyles: boolean;
+    /**
+     * Remove empty containers (g, defs without children)
+     * @default true
+     */
+    removeEmptyContainers: boolean;
+    /**
+     * Collapse useless groups
+     * @default false (basic/balanced), true (aggressive/maximum)
+     */
+    collapseGroups: boolean;
+    /**
+     * Convert attributes to camelCase for React compatibility
+     * @default true
+     */
+    reactCompatibility: boolean;
+    /**
+     * Sort attributes alphabetically
+     * @default false
+     */
+    sortAttrs: boolean;
+    /**
+     * Remove DOCTYPE declarations
+     * @default true
+     */
+    removeDoctype: boolean;
+    /**
+     * Remove XML processing instructions
+     * @default true
+     */
+    removeXMLProcInst: boolean;
+    /**
+     * Enable numeric optimization (coordinate precision, etc.)
+     * @default true
+     */
+    enableNumericOptimization: boolean;
+    /**
+     * Enable style optimization (color shortening, unit removal, etc.)
+     * @default true
+     */
+    enableStyleOptimization: boolean;
+    /**
+     * Enable transform optimization (matrix simplification, etc.)
+     * @default false (basic/balanced), true (aggressive/maximum)
+     */
+    enableTransformOptimization: boolean;
+    /**
+     * Enable transform collapsing (propagate, bake into coordinates, collapse groups)
+     * @default false (basic/balanced), true (aggressive/maximum)
+     */
+    enableTransformCollapsing: boolean;
+    /**
+     * Enable path optimization (command merging, H/V conversion, etc.)
+     * @default false (basic/balanced), true (aggressive/maximum)
+     */
+    enablePathOptimization: boolean;
+    /**
+     * Enable path simplification (Douglas-Peucker, Visvalingam-Whyatt)
+     * @default false (basic/balanced/aggressive), true (maximum)
+     */
+    enablePathSimplification: boolean;
+    /**
+     * Enable shape conversion (rect/polygon/polyline → path)
+     * @default false (basic/balanced), true (aggressive/maximum)
+     */
+    shapeConversion: boolean;
+    /**
+     * Minimum bytes to save for shape conversion
+     * @default 5 (aggressive), 0 (maximum)
+     */
+    shapeConversionThreshold: number;
+    /**
+     * Optimization level for stage-based processing
+     * @default 'BALANCED'
+     */
+    optimizationLevel: OptLevel;
+    /**
+     * Custom plugins (future extension point)
+     */
+    plugins?: OptimizationPlugin[];
+}
+/**
+ * Optimization plugin interface (for future extensibility)
+ */
+export interface OptimizationPlugin {
+    name: string;
+    stage: 'pre-parse' | 'tree' | 'post-serialize';
+    execute: (input: string | OptimizedTree, config: OptConfig) => string | OptimizedTree | Promise<string | OptimizedTree>;
+}
+/**
+ * Optimized tree node (lightweight virtual DOM)
+ */
+export interface OptimizedNode {
+    type: 'element' | 'text' | 'comment';
+    tagName?: string;
+    attributes?: Record<string, string>;
+    children?: OptimizedNode[];
+    textContent?: string;
+    commentText?: string;
+}
+/**
+ * Optimized tree structure
+ */
+export interface OptimizedTree {
+    root: OptimizedNode;
+    metadata: {
+        originalSize: number;
+        optimizedSize: number;
+        reductionPercent: number;
+        stages: string[];
+    };
+}
+/**
+ * Optimization stage function type
+ */
+export type OptimizationStage = (svgString: string, config: OptConfig) => Promise<string> | string;
+/**
+ * Optimization result
+ */
+export interface OptimizationResult {
+    optimizedSvg: string;
+    originalSize: number;
+    optimizedSize: number;
+    reductionPercent: number;
+    stagesApplied: string[];
+}
+/**
+ * Get default optimization config based on level
+ */
+export declare function getDefaultOptConfig(level: OptLevel): OptConfig;

package/dist/optimizers/types.js

@@ -0,0 +1,122 @@
+/**
+ * Type definitions for Advanced SVG Optimizer
+ */
+/**
+ * Optimization level enum
+ */
+export var OptLevel;
+(function (OptLevel) {
+    OptLevel["NONE"] = "none";
+    OptLevel["BASIC"] = "basic";
+    OptLevel["BALANCED"] = "balanced";
+    OptLevel["AGGRESSIVE"] = "aggressive";
+    OptLevel["MAXIMUM"] = "maximum";
+})(OptLevel || (OptLevel = {}));
+/**
+ * Get default optimization config based on level
+ */
+export function getDefaultOptConfig(level) {
+    const baseConfig = {
+        level,
+        floatPrecision: 3,
+        pathTolerance: 0.5,
+        removeViewBox: false,
+        removeMetadata: true,
+        removeComments: true,
+        normalizeWhitespace: true,
+        removeUnnecessaryAttrs: true,
+        shortenColors: true,
+        mergePaths: false,
+        removeHiddenElements: false,
+        inlineStyles: false,
+        removeEmptyContainers: true,
+        collapseGroups: false,
+        reactCompatibility: true,
+        sortAttrs: false,
+        removeDoctype: true,
+        removeXMLProcInst: true,
+        enableNumericOptimization: true,
+        enableStyleOptimization: true,
+        enableTransformOptimization: false,
+        enableTransformCollapsing: false,
+        enablePathOptimization: false,
+        enablePathSimplification: false,
+        shapeConversion: false,
+        shapeConversionThreshold: 5,
+        optimizationLevel: level,
+    };
+    switch (level) {
+        case OptLevel.NONE:
+            return {
+                ...baseConfig,
+                removeMetadata: false,
+                removeComments: false,
+                normalizeWhitespace: false,
+                removeUnnecessaryAttrs: false,
+                shortenColors: false,
+                removeEmptyContainers: false,
+                removeDoctype: false,
+                removeXMLProcInst: false,
+                enableNumericOptimization: false,
+                enableStyleOptimization: false,
+                enableTransformOptimization: false,
+                enableTransformCollapsing: false,
+                enablePathOptimization: false,
+                enablePathSimplification: false,
+            };
+        case OptLevel.BASIC:
+            return baseConfig;
+        case OptLevel.BALANCED:
+            return {
+                ...baseConfig,
+                removeHiddenElements: true,
+                floatPrecision: 3,
+                enableNumericOptimization: true,
+                enableStyleOptimization: true,
+                enableTransformOptimization: false,
+                enableTransformCollapsing: false,
+                enablePathOptimization: false,
+            };
+        case OptLevel.AGGRESSIVE:
+            return {
+                ...baseConfig,
+                removeHiddenElements: true,
+                mergePaths: true,
+                collapseGroups: true,
+                floatPrecision: 2,
+                pathTolerance: 0.7,
+                sortAttrs: true,
+                enableNumericOptimization: true,
+                enableStyleOptimization: true,
+                enableTransformOptimization: true,
+                enableTransformCollapsing: true,
+                enablePathOptimization: true,
+                // DISABLED: Shape conversion conflicts with floatPrecision=2
+                // Causes visual regressions (coordinates get rounded before conversion)
+                shapeConversion: false,
+                shapeConversionThreshold: 5,
+            };
+        case OptLevel.MAXIMUM:
+            return {
+                ...baseConfig,
+                removeHiddenElements: true,
+                mergePaths: true,
+                collapseGroups: true,
+                inlineStyles: true,
+                floatPrecision: 1,
+                pathTolerance: 0.9,
+                sortAttrs: true,
+                removeViewBox: false, // Keep viewBox even at maximum for compatibility
+                enableNumericOptimization: true,
+                enableStyleOptimization: true,
+                enableTransformOptimization: true,
+                enableTransformCollapsing: true,
+                enablePathOptimization: true,
+                enablePathSimplification: true,
+                shapeConversion: true,
+                shapeConversionThreshold: 0, // Convert even 1-byte savings
+            };
+        default:
+            return baseConfig;
+    }
+}

package/dist/plugins/color-replacer.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Example Plugin: Color Replacer with Visual Validation
+ * Demonstrates Phase 6.2 plugin system with pipeline hooks
+ */
+import type { EnhancedPlugin } from '../types/plugin-system.js';
+/**
+ * Color Replacer Plugin
+ * Replaces specified colors in SVG while ensuring visual quality
+ */
+export declare const colorReplacerPlugin: EnhancedPlugin;
+/**
+ * Example usage:
+ *
+ * import { enhancedPluginManager } from './core/enhanced-plugin-manager.js';
+ * import { colorReplacerPlugin } from './plugins/color-replacer.js';
+ *
+ * // Register plugin
+ * await enhancedPluginManager.registerPlugin(colorReplacerPlugin);
+ *
+ * // Enable with options
+ * enhancedPluginManager.enablePlugin('color-replacer', {
+ *   colors: {
+ *     '#ff0000': '#00ff00',  // Red → Green
+ *     '#0000ff': '#ffff00',  // Blue → Yellow
+ *   },
+ *   includeStyles: true,
+ * });
+ *
+ * // Process SVG through pipeline with visual validation
+ * const result = await enhancedPluginManager.processWithHooks(
+ *   svgContent,
+ *   config
+ * );
+ *
+ * // Check validation results
+ * if (result.validationResults.some(v => !v.validationPassed)) {
+ *   console.error('Visual validation failed!');
+ * }
+ */

package/dist/plugins/color-replacer.js

@@ -0,0 +1,126 @@
+/**
+ * Example Plugin: Color Replacer with Visual Validation
+ * Demonstrates Phase 6.2 plugin system with pipeline hooks
+ */
+/**
+ * Color Replacer Plugin
+ * Replaces specified colors in SVG while ensuring visual quality
+ */
+export const colorReplacerPlugin = {
+    name: 'color-replacer',
+    version: '1.0.0',
+    description: 'Replace colors in SVG with visual validation',
+    author: 'svger-cli',
+    hooks: {
+        'after-parse': async (context) => {
+            const options = context.metadata.get('pluginOptions');
+            if (!options || !options.colors) {
+                return { content: context.content };
+            }
+            let modifiedContent = context.content;
+            // Replace colors
+            for (const [oldColor, newColor] of Object.entries(options.colors)) {
+                // Replace in fill attributes
+                const fillRegex = new RegExp(`fill=["']${escapeRegex(oldColor)}["']`, options.caseSensitive ? 'g' : 'gi');
+                modifiedContent = modifiedContent.replace(fillRegex, `fill="${newColor}"`);
+                // Replace in stroke attributes
+                const strokeRegex = new RegExp(`stroke=["']${escapeRegex(oldColor)}["']`, options.caseSensitive ? 'g' : 'gi');
+                modifiedContent = modifiedContent.replace(strokeRegex, `stroke="${newColor}"`);
+                // Replace in style attributes if enabled
+                if (options.includeStyles) {
+                    const styleRegex = new RegExp(`(fill|stroke):\\s*${escapeRegex(oldColor)}`, options.caseSensitive ? 'g' : 'gi');
+                    modifiedContent = modifiedContent.replace(styleRegex, `$1:${newColor}`);
+                }
+            }
+            return {
+                content: modifiedContent,
+                metadata: {
+                    colorsReplaced: Object.keys(options.colors).length,
+                },
+            };
+        },
+    },
+    // Enable visual validation - colors should change but structure stays the same
+    validation: {
+        enabled: true,
+        maxDiffPercent: 100, // Allow 100% color change, but structure must be identical
+        options: {
+            diff: {
+                threshold: 0.1, // Strict threshold for structural changes
+                includeAA: false,
+            },
+        },
+    },
+    configSchema: {
+        colors: {
+            type: 'object',
+            required: true,
+            description: 'Color mapping (old color → new color)',
+        },
+        includeStyles: {
+            type: 'boolean',
+            required: false,
+            default: false,
+            description: 'Whether to replace colors in style attributes',
+        },
+        caseSensitive: {
+            type: 'boolean',
+            required: false,
+            default: false,
+            description: 'Case-sensitive color matching',
+        },
+    },
+    validate(options) {
+        if (!options) {
+            return { valid: false, errors: ['Options are required'] };
+        }
+        if (!options.colors || typeof options.colors !== 'object') {
+            return {
+                valid: false,
+                errors: ['colors property is required and must be an object'],
+            };
+        }
+        if (Object.keys(options.colors).length === 0) {
+            return {
+                valid: false,
+                errors: ['At least one color mapping is required'],
+            };
+        }
+        return { valid: true, errors: [] };
+    },
+};
+/**
+ * Escape special regex characters
+ */
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Example usage:
+ *
+ * import { enhancedPluginManager } from './core/enhanced-plugin-manager.js';
+ * import { colorReplacerPlugin } from './plugins/color-replacer.js';
+ *
+ * // Register plugin
+ * await enhancedPluginManager.registerPlugin(colorReplacerPlugin);
+ *
+ * // Enable with options
+ * enhancedPluginManager.enablePlugin('color-replacer', {
+ *   colors: {
+ *     '#ff0000': '#00ff00',  // Red → Green
+ *     '#0000ff': '#ffff00',  // Blue → Yellow
+ *   },
+ *   includeStyles: true,
+ * });
+ *
+ * // Process SVG through pipeline with visual validation
+ * const result = await enhancedPluginManager.processWithHooks(
+ *   svgContent,
+ *   config
+ * );
+ *
+ * // Check validation results
+ * if (result.validationResults.some(v => !v.validationPassed)) {
+ *   console.error('Visual validation failed!');
+ * }
+ */

package/dist/plugins/gradient-optimizer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Gradient Optimizer Plugin
+ * Removes redundant gradient stops and optimizes gradient definitions
+ *
+ * Features:
+ * - Remove duplicate gradient stops
+ * - Merge gradients with identical stops
+ * - Remove unused gradient definitions
+ * - Optimize stop colors (round precision)
+ *
+ * Visual tolerance: 2% (gradients should look nearly identical)
+ */
+import type { EnhancedPlugin } from '../types/plugin-system.js';
+/**
+ * Configuration for gradient optimizer
+ */
+export interface GradientOptimizerOptions {
+    /** Remove duplicate stops (default: true) */
+    removeDuplicates?: boolean;
+    /** Merge identical gradients (default: true) */
+    mergeIdentical?: boolean;
+    /** Remove unused gradients (default: true) */
+    removeUnused?: boolean;
+    /** Color precision (number of decimals, default: 2) */
+    colorPrecision?: number;
+    /** Offset precision (number of decimals, default: 2) */
+    offsetPrecision?: number;
+}
+/**
+ * Gradient Optimizer Plugin
+ */
+export declare const gradientOptimizerPlugin: EnhancedPlugin;
+export default gradientOptimizerPlugin;