Upload folder using huggingface_hub

modules/title_styler/__init__.py

@@ -0,0 +1,58 @@
+"""
+信息图表标题生成器
+
+一个用于生成专业信息图表标题的Python模块。
+"""
+
+from modules.title_styler.infographic_title_generator import (
+    InfographicTitleGenerator,
+    generate_title
+)
+
+from modules.title_styler.templates import (
+    TitleTemplate,
+    get_all_templates,
+    get_templates_by_alignment
+)
+
+from modules.title_styler.svg_renderer import SVGRenderer
+
+from modules.title_styler.llm_analyzer import LLMAnalyzer
+
+from modules.title_styler.config import (
+    TITLE_FONTS,
+    NEUTRAL_COLORS,
+    ALIGNMENT_LEFT,
+    ALIGNMENT_CENTER,
+    ALIGNMENT_RIGHT
+)
+
+__version__ = '1.0.0'
+__author__ = 'Your Name'
+
+__all__ = [
+    # 主要类
+    'InfographicTitleGenerator',
+    'TitleTemplate',
+    'SVGRenderer',
+    'LLMAnalyzer',
+    
+    # 便捷函数
+    'generate_title',
+    'generate_and_save',
+    'render_title',
+    'analyze_title_structure',
+    
+    # 模板相关
+    'get_all_templates',
+    'get_templates_by_line_count',
+    'get_templates_by_alignment',
+    
+    # 常量
+    'TITLE_FONTS',
+    'NEUTRAL_COLORS',
+    'ALIGNMENT_LEFT',
+    'ALIGNMENT_CENTER',
+    'ALIGNMENT_RIGHT',
+]
+

modules/title_styler/color_utils.py

@@ -0,0 +1,61 @@
+"""
+Color utility functions for contrast calculation
+"""
+
+def hex_to_rgb(hex_color: str) -> tuple:
+    """Convert hex color to RGB tuple"""
+    hex_color = hex_color.lstrip('#')
+    return tuple(int(hex_color[i:i+2], 16) for i in (0, 2, 4))
+
+
+def rgb_to_luminance(r: int, g: int, b: int) -> float:
+    """Calculate relative luminance (0-1) from RGB"""
+    # Convert to 0-1 range
+    r, g, b = r / 255.0, g / 255.0, b / 255.0
+    
+    # Apply gamma correction
+    r = r / 12.92 if r <= 0.03928 else ((r + 0.055) / 1.055) ** 2.4
+    g = g / 12.92 if g <= 0.03928 else ((g + 0.055) / 1.055) ** 2.4
+    b = b / 12.92 if b <= 0.03928 else ((b + 0.055) / 1.055) ** 2.4
+    
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b
+
+
+def contrast_ratio(color1: str, color2: str) -> float:
+    """
+    Calculate contrast ratio between two colors (1:1 to 21:1)
+    
+    Args:
+        color1: Hex color (e.g., '#FFFFFF')
+        color2: Hex color (e.g., '#000000')
+    
+    Returns:
+        Contrast ratio (1.0 to 21.0)
+    """
+    rgb1 = hex_to_rgb(color1)
+    rgb2 = hex_to_rgb(color2)
+    
+    lum1 = rgb_to_luminance(*rgb1)
+    lum2 = rgb_to_luminance(*rgb2)
+    
+    lighter = max(lum1, lum2)
+    darker = min(lum1, lum2)
+    
+    return (lighter + 0.05) / (darker + 0.05)
+
+
+def is_sufficient_contrast(foreground: str, background: str, min_ratio: float = 3.0) -> bool:
+    """
+    Check if there's sufficient contrast between foreground and background
+    
+    Args:
+        foreground: Foreground color (hex)
+        background: Background color (hex)
+        min_ratio: Minimum acceptable contrast ratio (default 3.0)
+    
+    Returns:
+        True if contrast is sufficient
+    """
+    ratio = contrast_ratio(foreground, background)
+    return ratio >= min_ratio
+

modules/title_styler/font_metrics.py

@@ -0,0 +1,533 @@
+"""
+Font Metrics Tool - Using Pillow for Accurate Text Width Calculation
+"""
+
+import os
+import subprocess
+from typing import Tuple, Optional
+
+from PIL import Image, ImageDraw, ImageFont
+
+
+# Cache the file path returned by `fc-match <family>` so we don't fork a
+# subprocess on every text measurement. Keyed by (font_family, font_weight,
+# font_style) — same key shape used by `_load_font`.
+_FC_MATCH_CACHE: dict = {}
+
+# Map our public font_family names to a CSS generic family ("serif",
+# "sans-serif", "monospace", "cursive"). When `fc-match` is unavailable we
+# fall back to a Linux font of the same *category* so a request for Georgia
+# never silently degrades to LiberationSans (a sans-serif). Anything we
+# don't recognize is treated as sans-serif.
+_FAMILY_GENERIC = {
+    'Georgia': 'serif',
+    'Times': 'serif',
+    'Times New Roman': 'serif',
+    'Cambria': 'serif',
+    'Garamond': 'serif',
+    'Book Antiqua': 'serif',
+    'Palatino': 'serif',
+    'Palatino Linotype': 'serif',
+    'Noto Serif': 'serif',
+    'DejaVu Serif': 'serif',
+
+    'Arial': 'sans-serif',
+    'Helvetica': 'sans-serif',
+    'Verdana': 'sans-serif',
+    'Tahoma': 'sans-serif',
+    'Trebuchet MS': 'sans-serif',
+    'Segoe UI': 'sans-serif',
+    'Calibri': 'sans-serif',
+    'Roboto': 'sans-serif',
+    'Open Sans': 'sans-serif',
+    'Montserrat': 'sans-serif',
+    'Oswald': 'sans-serif',
+    'Lato': 'sans-serif',
+    'Source Sans Pro': 'sans-serif',
+    'Noto Sans': 'sans-serif',
+    'DejaVu Sans': 'sans-serif',
+    'Liberation Sans': 'sans-serif',
+
+    'Courier': 'monospace',
+    'Courier New': 'monospace',
+    'Consolas': 'monospace',
+    'Monaco': 'monospace',
+    'Menlo': 'monospace',
+    'DejaVu Sans Mono': 'monospace',
+    'Liberation Mono': 'monospace',
+
+    # display/script: have wildly different metrics. We push these through
+    # fc-match (which has explicit rules) instead of category-based fallback
+    # so they don't all collapse onto a sans-serif body font.
+    'Impact': 'sans-serif',
+    'Bebas Neue': 'sans-serif',
+    'Comic Sans MS': 'cursive',
+    'Comic Neue': 'cursive',
+    'Brush Script': 'cursive',
+    'Pacifico': 'cursive',
+}
+
+
+class FontMetrics:
+    """Font metrics calculator"""
+    
+    def __init__(self):
+        self.font_cache = {}
+    
+    def get_font(self, font_family: str, font_size: int, font_weight: str = 'normal', 
+                 font_style: str = 'normal') -> Optional[ImageFont.FreeTypeFont]:
+        """
+        Get font object (with caching)
+        
+        Args:
+            font_family: Font name
+            font_size: Font size
+            font_weight: Font weight
+            font_style: Font style (normal, italic, oblique)
+        
+        Returns:
+            Font object or None (if font is unavailable)
+        """
+        cache_key = f"{font_family}_{font_size}_{font_weight}_{font_style}"
+        
+        if cache_key in self.font_cache:
+            return self.font_cache[cache_key]
+        
+        # Try to load font
+        font = self._load_font(font_family, font_size, font_weight, font_style)
+        self.font_cache[cache_key] = font
+        return font
+    
+    def _load_font(self, font_family: str, font_size: int, font_weight: str,
+                   font_style: str) -> Optional[ImageFont.FreeTypeFont]:
+        """Resolve a font for measurement.
+
+        Resolution order:
+          1. Hard-coded path table (`_get_font_paths`) — exists for
+             developer machines that have the real Microsoft/Apple fonts
+             (Georgia, Arial, ...) installed in well-known locations.
+          2. fontconfig (`fc-match <family>:weight=...:slant=...`) — this is
+             *exactly* the path Chromium/Chrome uses on Linux to resolve a
+             `font-family: Georgia` SVG style, so going through fc-match
+             keeps PIL's measurement aligned with how the chart actually
+             renders. This is the fix for Bug B: before this call, the code
+             always fell through to `_get_generic_fallback_paths()` which
+             returned Liberation Sans regardless of whether the request was
+             serif, sans-serif, or display, so PIL routinely under-measured
+             a 32px Georgia headline by ~40-50% and the resulting title
+             SVG width was too small, leading to the rendered text
+             overflowing the canvas at compose time.
+          3. Generic-family fallback table (`_get_generic_fallback_paths`)
+             — used only when fontconfig is unavailable (no `fc-match`
+             binary). Picks a Linux-installed font that matches the
+             *category* (serif / sans-serif / monospace / cursive) of the
+             requested family.
+          4. Pillow's bitmap default (last-resort).
+        """
+        font_paths = self._get_font_paths(font_family, font_weight, font_style)
+        for path in font_paths:
+            if os.path.exists(path):
+                try:
+                    return ImageFont.truetype(path, font_size)
+                except Exception:
+                    continue
+
+        fc_path = self._fc_match(font_family, font_weight, font_style)
+        if fc_path:
+            try:
+                return ImageFont.truetype(fc_path, font_size)
+            except Exception:
+                pass
+
+        for path in self._get_generic_fallback_paths(font_family, font_weight, font_style):
+            if os.path.exists(path):
+                try:
+                    return ImageFont.truetype(path, font_size)
+                except Exception:
+                    continue
+
+        try:
+            return ImageFont.load_default()
+        except Exception:
+            return None
+
+    def _fc_match(self, font_family: str, font_weight: str, font_style: str) -> Optional[str]:
+        """Ask fontconfig which file would be used for this family / weight /
+        slant combination. Cached because subprocess.run is ~3ms and we may
+        ask thousands of times during a batch run.
+        """
+        key = (font_family, font_weight, font_style)
+        if key in _FC_MATCH_CACHE:
+            return _FC_MATCH_CACHE[key]
+
+        is_bold = font_weight in ['bold', 'bolder', '700', '800', '900']
+        is_italic = font_style in ['italic', 'oblique']
+        query = font_family
+        if is_bold:
+            query += ':weight=bold'
+        if is_italic:
+            query += ':slant=italic'
+
+        result = subprocess.run(
+            ['fc-match', '-f', '%{file}', query],
+            capture_output=True, text=True, timeout=2,
+            check=False,
+        )
+        path = result.stdout.strip() if result.returncode == 0 else ''
+        resolved = path if path and os.path.exists(path) else None
+        _FC_MATCH_CACHE[key] = resolved
+        return resolved
+
+    def _get_generic_fallback_paths(self, font_family: str, font_weight: str,
+                                     font_style: str) -> list:
+        """Linux font paths picked by *category* (serif / sans / mono / cursive).
+
+        Only used when fc-match is unavailable. The category is derived from
+        ``_FAMILY_GENERIC``; anything unknown is treated as sans-serif.
+        """
+        is_bold = font_weight in ['bold', 'bolder', '700', '800', '900']
+        is_italic = font_style in ['italic', 'oblique']
+        category = _FAMILY_GENERIC.get(font_family, 'sans-serif')
+
+        def pick(serif, sans, mono, cursive):
+            return {'serif': serif, 'sans-serif': sans, 'monospace': mono,
+                    'cursive': cursive}[category]
+
+        if is_bold and is_italic:
+            filename = pick(
+                'DejaVuSerif-BoldItalic.ttf',
+                'LiberationSans-BoldItalic.ttf',
+                'DejaVuSansMono-BoldOblique.ttf',
+                'LiberationSans-BoldItalic.ttf',
+            )
+        elif is_bold:
+            filename = pick(
+                'DejaVuSerif-Bold.ttf',
+                'LiberationSans-Bold.ttf',
+                'DejaVuSansMono-Bold.ttf',
+                'LiberationSans-Bold.ttf',
+            )
+        elif is_italic:
+            filename = pick(
+                'DejaVuSerif-Italic.ttf',
+                'LiberationSans-Italic.ttf',
+                'DejaVuSansMono-Oblique.ttf',
+                'LiberationSans-Italic.ttf',
+            )
+        else:
+            filename = pick(
+                'DejaVuSerif.ttf',
+                'LiberationSans-Regular.ttf',
+                'DejaVuSansMono.ttf',
+                'LiberationSans-Regular.ttf',
+            )
+
+        return [
+            f'/usr/share/fonts/truetype/dejavu/{filename}',
+            f'/usr/share/fonts/truetype/liberation2/{filename}',
+            f'/usr/share/fonts/truetype/liberation/{filename}',
+            f'/usr/share/fonts/truetype/noto/{filename}',
+        ]
+    
+    def _get_font_paths(self, font_family: str, font_weight: str, font_style: str) -> list:
+        """Get possible font file paths"""
+        paths = []
+        
+        # macOS font paths
+        mac_system_fonts = "/System/Library/Fonts"
+        mac_supplemental_fonts = "/System/Library/Fonts/Supplemental"
+        mac_user_fonts = os.path.expanduser("~/Library/Fonts")
+        
+        # Linux font paths
+        linux_fonts = "/usr/share/fonts"
+        linux_truetype = "/usr/share/fonts/truetype"
+        
+        # Windows font paths
+        windows_fonts = "C:/Windows/Fonts"
+        
+        # Determine style key: 'normal', 'italic', 'bold', 'bold-italic'
+        is_bold = font_weight in ['bold', 'bolder', '700', '800', '900']
+        is_italic = font_style in ['italic', 'oblique']
+        
+        if is_bold and is_italic:
+            style_key = 'bold-italic'
+        elif is_bold:
+            style_key = 'bold'
+        elif is_italic:
+            style_key = 'italic'
+        else:
+            style_key = 'normal'
+        
+        # Font filename mappings
+        font_files = {
+            'Arial': {
+                'normal': ['Arial.ttf', 'arial.ttf', 'Arial Unicode.ttf'],
+                'bold': ['Arial Bold.ttf', 'arialbd.ttf', 'Arial-Bold.ttf', 'Arial-BoldMT.ttf', 'Arial_Bold.ttf'],
+                'italic': ['Arial Italic.ttf', 'ariali.ttf', 'Arial-Italic.ttf', 'Arial-ItalicMT.ttf', 'Arial_Italic.ttf'],
+                'bold-italic': ['Arial Bold Italic.ttf', 'arialbi.ttf', 'Arial-BoldItalic.ttf', 'Arial-BoldItalicMT.ttf', 'Arial_Bold_Italic.ttf'],
+            },
+            'Comic Sans MS': {
+                'normal': ['Comic Sans MS.ttf', 'comic.ttf', 'ComicSansMS.ttf'],
+                'bold': ['Comic Sans MS Bold.ttf', 'comicbd.ttf', 'ComicSansMS-Bold.ttf'],
+                'italic': ['Comic Sans MS Italic.ttf', 'comici.ttf', 'ComicSansMS-Italic.ttf'],
+                'bold-italic': ['Comic Sans MS Bold Italic.ttf', 'comicbi.ttf', 'ComicSansMS-BoldItalic.ttf'],
+            },
+            'Georgia': {
+                'normal': ['Georgia.ttf', 'georgia.ttf'],
+                'bold': ['Georgia Bold.ttf', 'Georgia-Bold.ttf', 'GeorgiaBold.ttf', 'georgiab.ttf'],
+                'italic': ['Georgia Italic.ttf', 'Georgia-Italic.ttf', 'GeorgiaItalic.ttf', 'georgiai.ttf'],
+                'bold-italic': ['Georgia Bold Italic.ttf', 'Georgia-BoldItalic.ttf', 'GeorgiaBoldItalic.ttf', 'georgiaz.ttf'],
+            },
+            'Times New Roman': {
+                'normal': ['Times New Roman.ttf', 'times.ttf', 'Times_New_Roman.ttf'],
+                'bold': ['Times New Roman Bold.ttf', 'timesbd.ttf', 'Times-Bold.ttf'],
+                'italic': ['Times New Roman Italic.ttf', 'timesi.ttf', 'Times-Italic.ttf'],
+                'bold-italic': ['Times New Roman Bold Italic.ttf', 'timesbi.ttf', 'Times-BoldItalic.ttf'],
+            },
+            'Helvetica': {
+                'normal': ['Helvetica.ttc', 'Helvetica.ttf'],
+                'bold': ['Helvetica-Bold.ttc', 'Helvetica-Bold.ttf'],
+                'italic': ['Helvetica-Oblique.ttc', 'Helvetica-Oblique.ttf'],
+                'bold-italic': ['Helvetica-BoldOblique.ttc', 'Helvetica-BoldOblique.ttf'],
+            },
+            'Montserrat': {
+                'normal': ['Montserrat-Regular.ttf'],
+                'bold': ['Montserrat-Bold.ttf'],
+                'italic': ['Montserrat-Italic.ttf'],
+                'bold-italic': ['Montserrat-BoldItalic.ttf'],
+            },
+            'Open Sans': {
+                'normal': ['OpenSans-Regular.ttf'],
+                'bold': ['OpenSans-Bold.ttf'],
+                'italic': ['OpenSans-Italic.ttf'],
+                'bold-italic': ['OpenSans-BoldItalic.ttf'],
+            },
+            'Roboto': {
+                'normal': ['Roboto-Regular.ttf'],
+                'bold': ['Roboto-Bold.ttf'],
+                'italic': ['Roboto-Italic.ttf'],
+                'bold-italic': ['Roboto-BoldItalic.ttf'],
+            },
+            'Impact': {
+                'normal': ['Impact.ttf', 'impact.ttf'],
+                'bold': ['Impact.ttf', 'impact.ttf'],
+                'italic': ['Impact.ttf', 'impact.ttf'],
+                'bold-italic': ['Impact.ttf', 'impact.ttf'],
+            },
+            'Oswald': {
+                'normal': ['Oswald-Regular.ttf'],
+                'bold': ['Oswald-Bold.ttf'],
+                'italic': ['Oswald-Italic.ttf'],
+                'bold-italic': ['Oswald-BoldItalic.ttf'],
+            },
+        }
+        
+        filenames = font_files.get(font_family, {}).get(style_key, [f"{font_family}.ttf"])
+        
+        # Build complete paths
+        base_dirs = [
+            mac_supplemental_fonts,  # Search Supplemental first
+            mac_system_fonts, 
+            mac_user_fonts, 
+            linux_truetype,
+            linux_fonts, 
+            windows_fonts
+        ]
+        
+        # First try direct paths
+        for base_dir in base_dirs:
+            for filename in filenames:
+                paths.append(os.path.join(base_dir, filename))
+        
+        # For Linux, also search in common subdirectories (Ubuntu stores fonts in subdirs)
+        linux_subdirs = [
+            '/usr/share/fonts/truetype/msttcorefonts',  # Microsoft core fonts
+            '/usr/share/fonts/truetype/liberation',      # Liberation fonts
+            '/usr/share/fonts/truetype/dejavu',          # DejaVu fonts
+            '/usr/share/fonts/truetype/noto',            # Noto fonts
+            '/usr/share/fonts/truetype/liberation2',     # Liberation2 fonts
+        ]
+        
+        for subdir in linux_subdirs:
+            for filename in filenames:
+                paths.append(os.path.join(subdir, filename))
+        
+        return paths
+    
+    def measure_text(self, text: str, font_family: str, font_size: int, 
+                     font_weight: str = 'normal', font_style: str = 'normal', 
+                     letter_spacing: float = 0) -> Tuple[float, float]:
+        """
+        Measure text dimensions
+        
+        Args:
+            text: Text content
+            font_family: Font name
+            font_size: Font size
+            font_weight: Font weight
+            font_style: Font style (normal, italic, oblique)
+            letter_spacing: Letter spacing (em unit) - will be applied by SVG renderer
+        
+        Returns:
+            (width, height) Text width and height
+        
+        Note:
+            We measure the base width without letter-spacing here.
+            The SVG renderer will apply letter-spacing attribute, which the browser handles.
+            This avoids double-counting letter-spacing in both measurement and rendering.
+        """
+        font = self.get_font(font_family, font_size, font_weight, font_style)
+        
+        if font is None:
+            # Fallback to simple estimation
+            base_width, height = self._estimate_text_size(text, font_size, font_weight)
+            # Add letter spacing for fallback estimation
+            if letter_spacing > 0 and len(text) > 1:
+                extra_space = font_size * letter_spacing * (len(text) - 1)
+                base_width += extra_space
+            return base_width, height
+        
+        # Create temporary image for measurement
+        img = Image.new('RGB', (1, 1))
+        draw = ImageDraw.Draw(img)
+        
+        # Use textbbox to get accurate bounding box
+        try:
+            bbox = draw.textbbox((0, 0), text, font=font)
+            width = bbox[2] - bbox[0]
+            height = bbox[3] - bbox[1]
+            
+            # Add letter spacing
+            # SVG letter-spacing is applied on top of the base glyph spacing
+            # We need to estimate the total width including letter-spacing
+            if letter_spacing > 0 and len(text) > 1:
+                extra_space = font_size * letter_spacing * (len(text) - 1)
+                width += extra_space
+            
+            return width, height
+        except AttributeError:
+            # Older PIL versions use textsize
+            width, height = draw.textsize(text, font=font)
+            
+            if letter_spacing > 0 and len(text) > 1:
+                extra_space = font_size * letter_spacing * (len(text) - 1)
+                width += extra_space
+            
+            return width, height
+    
+    def _estimate_text_size(self, text: str, font_size: int, font_weight: str) -> Tuple[float, float]:
+        """Simple text size estimation (fallback)"""
+        char_width_ratio = 0.65 if font_weight in ['bold', 'bolder'] else 0.6
+        width = len(text) * font_size * char_width_ratio
+        height = font_size
+        return width, height
+
+
+# Global instance
+_metrics_instance = None
+
+
+def get_font_metrics() -> FontMetrics:
+    """Get global font metrics instance"""
+    global _metrics_instance
+    if _metrics_instance is None:
+        _metrics_instance = FontMetrics()
+    return _metrics_instance
+
+
+def measure_text_width(text: str, font_family: str, font_size: int, 
+                       font_weight: str = 'normal', font_style: str = 'normal', 
+                       letter_spacing: float = 0) -> float:
+    """
+    Convenience function: Measure text width
+    
+    Args:
+        text: Text content
+        font_family: Font name
+        font_size: Font size
+        font_weight: Font weight
+        font_style: Font style (normal, italic, oblique)
+        letter_spacing: Letter spacing
+    
+    Returns:
+        Text width
+    """
+    metrics = get_font_metrics()
+    width, _ = metrics.measure_text(text, font_family, font_size, font_weight, font_style, letter_spacing)
+    return width
+
+
+def measure_text_bbox(text: str, font_family: str, font_size: int, 
+                      font_weight: str = 'normal', font_style: str = 'normal', 
+                      letter_spacing: float = 0) -> Tuple[float, float, float, float]:
+    """
+    Measure text bounding box relative to baseline
+    
+    Args:
+        text: Text content
+        font_family: Font name
+        font_size: Font size
+        font_weight: Font weight
+        font_style: Font style (normal, italic, oblique)
+        letter_spacing: Letter spacing
+    
+    Returns:
+        (ascent, descent, width, total_height)
+        - ascent: Distance from baseline to top of text
+        - descent: Distance from baseline to bottom of text (positive value)
+        - width: Text width
+        - total_height: Total height (ascent + descent)
+    """
+    metrics = get_font_metrics()
+    font = metrics.get_font(font_family, font_size, font_weight, font_style)
+    
+    if font is None:
+        # Fallback estimation
+        width, height = metrics._estimate_text_size(text, font_size, font_weight)
+        if letter_spacing > 0 and len(text) > 1:
+            extra_space = font_size * letter_spacing * (len(text) - 1)
+            width += extra_space
+        # Estimate: ~75% above baseline, ~25% below
+        ascent = height * 0.75
+        descent = height * 0.25
+        return ascent, descent, width, height
+    
+    # Create temporary image for measurement
+    img = Image.new('RGB', (1, 1))
+    draw = ImageDraw.Draw(img)
+    
+    # Use textbbox to get accurate bounding box
+    try:
+        # textbbox with anchor parameter gives us baseline-relative coordinates
+        bbox = draw.textbbox((0, 0), text, font=font, anchor='ls')  # 'ls' = left-baseline
+        
+        # bbox = (left, top, right, bottom) relative to baseline at y=0
+        # top will be negative (above baseline)
+        # bottom will be positive (below baseline) for characters with descenders
+        ascent = abs(bbox[1])  # Distance from baseline to top
+        descent = max(0, bbox[3])  # Distance from baseline to bottom
+        width = bbox[2] - bbox[0]
+        
+        # Add letter spacing
+        if letter_spacing > 0 and len(text) > 1:
+            extra_space = font_size * letter_spacing * (len(text) - 1)
+            width += extra_space
+        
+        total_height = ascent + descent
+        return ascent, descent, width, total_height
+        
+    except (AttributeError, TypeError):
+        # Fallback if anchor parameter not supported
+        bbox = draw.textbbox((0, 0), text, font=font)
+        width = bbox[2] - bbox[0]
+        height = bbox[3] - bbox[1]
+        
+        if letter_spacing > 0 and len(text) > 1:
+            extra_space = font_size * letter_spacing * (len(text) - 1)
+            width += extra_space
+        
+        # Estimate ascent/descent
+        ascent = height * 0.75
+        descent = height * 0.25
+        return ascent, descent, width, height
+

modules/title_styler/infographic_title_generator.py

@@ -0,0 +1,954 @@
+"""
+Infographic Title Generator - Main Module
+Integrates all functionality and provides a unified generation interface
+"""
+
+from typing import Optional, List, Dict
+from modules.title_styler.templates import get_all_templates, get_templates_with_description, get_templates_main_only, get_templates_by_style, TitleTemplate
+from modules.title_styler.svg_renderer import SVGRenderer
+from modules.title_styler.llm_analyzer import LLMAnalyzer
+from modules.title_styler.color_utils import contrast_ratio
+import os
+from datetime import datetime
+from modules.title_styler.config import COLOR_TYPE_PRIMARY, COLOR_TYPE_SECONDARY, COLOR_TYPE_FIXED
+
+
+class InfographicTitleGenerator:
+    """Main class for infographic title generator"""
+    
+    def __init__(self, use_llm=True):
+        """
+        Initialize generator
+        
+        Args:
+            use_llm: Whether to use LLM for title analysis (default True)
+        """
+        self.renderer = SVGRenderer()
+        self.templates = get_all_templates()
+        self.use_llm = use_llm
+        if use_llm:
+            self.analyzer = LLMAnalyzer()
+        # Hard cap on total visible rows in the rendered title region
+        # (main segments + optional description). Keeps the layout from
+        # blowing up to 4+ rows when a multi-segment template is paired
+        # with a sub_title — the resulting infographic looks busy and
+        # dominates the chart. Set <= 0 to disable.
+        self.max_total_rows = 3
+
+    def _filter_templates_by_row_budget(self, templates, has_description: bool):
+        """Drop templates whose ``main_segments + (1 if has_description else 0)``
+        would exceed ``self.max_total_rows``. Used as a global guard rail
+        regardless of whether the LLM or the heuristic picker is in charge.
+        """
+        if not self.max_total_rows or self.max_total_rows <= 0:
+            return list(templates)
+        budget = self.max_total_rows - (1 if has_description else 0)
+        kept = []
+        for t in templates:
+            main_count = sum(1 for l in t.lines if l.role == 'main')
+            if main_count <= budget:
+                kept.append(t)
+        return kept
+    
+    def generate(self, 
+                 title: str,
+                 description: Optional[str] = None,
+                 primary_color: str = '#2E7D32',
+                 secondary_color: Optional[str] = None,
+                 background_color: str = '#FFFFFF',
+                 max_width: Optional[int] = None,
+                 alignment: Optional[str] = None,
+                 template_name: Optional[str] = None,
+                 top_k: Optional[int] = None,
+                 style: Optional[str] = None) -> List[Dict]:
+        """
+        Generate infographic title
+        
+        Args:
+            title: Main title text
+            description: Subtitle/description text (optional)
+            primary_color: Primary color
+            secondary_color: Secondary color (optional)
+            background_color: Background color for contrast checking
+            max_width: Maximum width limit
+            alignment: Alignment ('left', 'center', 'right'), None means no limit
+            template_name: Specify template name (optional)
+            top_k: Number of templates to try (only works when template_name is None and use_llm=True)
+            style: Template style filter ('normal', 'comic', 'simple', 'professional', 'all' or None)
+                  None means no style filtering, 'all' means use all styles
+        
+        Returns:
+            List of results, each containing:
+            - template_name: Template name used
+            - svg: SVG string
+            - width: SVG width
+            - height: SVG height
+        """
+        # Store background_color for later use in rendering
+        self.background_color = background_color
+        
+        # Step 1: Determine template and title splitting
+        if self.use_llm:
+            # Use LLM to analyze title splitting
+            if template_name:
+                print(f"🤖 Analyzing title with LLM for template: {template_name}")
+                
+                # Get the specified template
+                candidate_templates = self._select_templates(
+                    has_description=(description is not None),
+                    alignment=alignment,
+                    template_name=template_name,
+                    style=style
+                )
+                if not candidate_templates:
+                    print(f"⚠️  Specified template '{template_name}' not found")
+                    return []
+                
+                # Build templates info for LLM (just the one template)
+                t = candidate_templates[0]
+                segment_count = 0
+                if t.lines:
+                    segment_count = len([l for l in t.lines if l.role == 'main'])
+                
+                templates_info = [{
+                    'name': t.name,
+                    'description': t.description,
+                    'segment_count': segment_count
+                }]
+                
+                # Single template with LLM splitting
+                recommendation = self.analyzer.recommend_template(
+                    title, 
+                    has_description=(description is not None),
+                    templates_info=templates_info
+                )
+                
+                if not recommendation:
+                    print("❌ LLM analysis failed")
+                    return []
+
+                title_lines = recommendation['title_split']
+                rec_split_method = recommendation.get('split_method') or 'llm'
+
+                print(f"  ✅ LLM Analysis:")
+                print(f"     Title Splitting: {title_lines}")
+                print(f"     Reasoning: {recommendation.get('reasoning', '')}")
+                
+            elif top_k and top_k > 1:
+                # Top-k template recommendation
+                print(f"🤖 Analyzing title with LLM to recommend top-{top_k} templates...")
+                
+                # Step 1: Pre-filter all templates by contrast, style, and alignment
+                print(f"  📋 Step 1: Filtering templates by contrast with background {background_color}")
+                
+                # Apply style filter first if specified
+                templates_to_check = self.templates
+                if style and style != 'all':
+                    templates_to_check = [t for t in templates_to_check if t.style == style]
+                    print(f"  🎨 Style filter: {style} ({len(templates_to_check)} templates match)")
+                
+                all_contrast_valid = self._filter_templates_by_contrast(
+                    templates_to_check, background_color, primary_color
+                )
+                
+                if not all_contrast_valid:
+                    print("  ❌ All templates filtered out by contrast check")
+                    return []
+                
+                print(f"  ✅ {len(all_contrast_valid)}/{len(templates_to_check)} templates passed contrast check")
+
+                # Hard cap on total visible rows (main segments + optional desc).
+                # Without this, a 3-main-segment template + sub_title would
+                # produce 4 stacked rows in the title region.
+                row_budget_kept = self._filter_templates_by_row_budget(
+                    all_contrast_valid, has_description=(description is not None)
+                )
+                if row_budget_kept:
+                    if len(row_budget_kept) != len(all_contrast_valid):
+                        print(f"  ✂️  Row-budget filter (<= {self.max_total_rows} rows total): "
+                              f"{len(row_budget_kept)}/{len(all_contrast_valid)} kept")
+                    all_contrast_valid = row_budget_kept
+                else:
+                    print("  ⚠️  Row-budget filter would drop everything; keeping contrast-valid pool as-is")
+
+                # Apply alignment filter if specified
+                if alignment:
+                    templates_with_alignment = [t for t in all_contrast_valid if t.alignment == alignment]
+                    if not templates_with_alignment:
+                        print(f"  ⚠️  No templates found with alignment='{alignment}', falling back to all alignments")
+                        print(f"  💡 Available templates: {len(all_contrast_valid)} (various alignments)")
+                    else:
+                        all_contrast_valid = templates_with_alignment
+                        print(f"  ✅ Alignment filter: {alignment} ({len(all_contrast_valid)} templates match)")
+                
+                # Step 2: Group filtered templates by segment count for diversity
+                print(f"  📊 Step 2: Sampling diverse templates from filtered set")
+                import random
+                templates_by_segments = {}
+                
+                for t in all_contrast_valid:
+                    # Count main segments
+                    segments = []
+                    if t.lines:
+                        segments = [l for l in t.lines if l.role == 'main']
+                    
+                    seg_count = len(segments)
+                    if seg_count not in templates_by_segments:
+                        templates_by_segments[seg_count] = []
+                    
+                    templates_by_segments[seg_count].append({
+                        'template': t,
+                        'segment_count': seg_count
+                    })
+                
+                # Sample 3 templates from each segment count group
+                sampled_templates = []
+                for seg_count in sorted(templates_by_segments.keys()):
+                    group = templates_by_segments[seg_count]
+                    sample_size = min(3, len(group))
+                    sampled = random.sample(group, sample_size)
+                    sampled_templates.extend(sampled)
+                
+                print(f"  📌 Sampled {len(sampled_templates)} diverse templates:")
+                for seg_count in sorted(templates_by_segments.keys()):
+                    group_names = [s['template'].name for s in sampled_templates if s['segment_count'] == seg_count]
+                    if group_names:
+                        print(f"     {seg_count}-segment: {', '.join(group_names)}")
+                
+                # Step 3: Prepare template info for LLM (only contrast-valid, sampled templates)
+                print(f"  🤖 Step 3: Sending {len(sampled_templates)} templates to LLM")
+                templates_info = []
+                for item in sampled_templates:
+                    t = item['template']
+                    info = {
+                        'name': t.name,
+                        'description': t.description,
+                        'segment_roles': getattr(t, 'segment_roles', ''),
+                        'segment_count': item['segment_count']
+                    }
+                    templates_info.append(info)
+                
+                top_k_result = self.analyzer.recommend_top_k_templates(title, templates_info, top_k)
+                
+                if not top_k_result:
+                    print("  ❌ LLM analysis failed")
+                    return []
+                
+                recommendations_list = top_k_result.get('recommendations', [])
+                
+                print(f"  ✅ LLM Analysis - Top {len(recommendations_list)} Recommendations:")
+                for i, rec in enumerate(recommendations_list, 1):
+                    print(f"     {i}. {rec['template_name']} (confidence: {rec.get('confidence', 0):.2f})")
+                    if rec.get('paraphrased_title'):
+                        print(f"        Paraphrased: \"{rec['paraphrased_title']}\"")
+                    print(f"        Split: {rec['title_split']}")
+                    print(f"        Reason: {rec.get('reasoning', '')}")
+                
+                # Step 4: Generate SVG for each recommended template
+                print(f"  🎨 Step 4: Generating SVG for recommended templates")
+                all_results = []
+                for rec in recommendations_list:
+                    rec_template_name = rec['template_name']
+                    rec_title_split = rec['title_split']
+                    rec_split_method = rec.get('split_method') or 'llm'
+
+                    # Find template (should already be contrast-valid from Step 1)
+                    rec_templates = self._select_templates(
+                        has_description=(description is not None),
+                        alignment=alignment,
+                        template_name=rec_template_name,
+                        style=style
+                    )
+                    
+                    if not rec_templates:
+                        print(f"  ⚠️  Template '{rec_template_name}' not found, skipping")
+                        continue
+                    
+                    # Generate with this template
+                    result = self._generate_with_template(
+                        rec_templates[0], rec_title_split, description,
+                        primary_color, secondary_color, background_color, max_width
+                    )
+
+                    if result:
+                        result['split_method'] = rec_split_method
+                        all_results.append(result)
+                        print(f"  ✓ Template '{rec_template_name}' generated successfully")
+
+                return all_results
+            
+            else:
+                # Single template recommendation
+                print("🤖 Analyzing title with LLM to recommend template...")
+                
+                # Get available templates (with style filter if specified)
+                available_templates = self.templates
+                if style and style != 'all':
+                    available_templates = [t for t in available_templates if t.style == style]
+                    print(f"  🎨 Style filter: {style} ({len(available_templates)} templates available)")
+                
+                # Build templates info for LLM
+                templates_info = []
+                for t in available_templates:
+                    # Count segments
+                    segment_count = 0
+                    if t.lines:
+                        segment_count = len([l for l in t.lines if l.role == 'main'])
+                    
+                    templates_info.append({
+                        'name': t.name,
+                        'description': t.description,
+                        'segment_count': segment_count
+                    })
+                
+                recommendation = self.analyzer.recommend_template(
+                    title, 
+                    has_description=(description is not None),
+                    templates_info=templates_info
+                )
+                
+                if not recommendation:
+                    print("❌ LLM analysis failed")
+                    return []
+                
+                recommended_template_name = recommendation['recommended_template']
+                title_lines = recommendation['title_split']
+                reasoning = recommendation.get('reasoning', '')
+                
+                print(f"  ✅ LLM Analysis:")
+                print(f"     Recommended Template: {recommended_template_name}")
+                print(f"     Title Splitting: {title_lines}")
+                print(f"     Reasoning: {reasoning}")
+                
+                candidate_templates = []
+                for t in self.templates:
+                    if t.name == recommended_template_name:
+                        candidate_templates = [t]
+                        break
+                
+                if not candidate_templates:
+                    print(f"  ❌ Recommended template '{recommended_template_name}' not found")
+                    return []
+            
+        elif template_name:
+            # Use specified template without LLM
+            print(f"📋 Using specified template: {template_name}")
+            candidate_templates = self._select_templates(
+                has_description=(description is not None),
+                alignment=alignment,
+                template_name=template_name,
+                style=style
+            )
+            if not candidate_templates:
+                print(f"⚠️  Specified template '{template_name}' not found")
+                return []
+            # Split by newline if title contains \n
+            if '\n' in title:
+                title_lines = title.split('\n')
+            else:
+                title_lines = [title]
+            
+        else:
+            # Use simple standard template (useLLM=False)
+            print("📋 Using standard single-line template (LLM disabled)")
+            candidate_templates = []
+            for t in self.templates:
+                if t.name == 'infographic_standard':
+                    candidate_templates = [t]
+                    break
+            
+            if not candidate_templates:
+                print("❌ Standard template not found")
+                return []
+            
+            # Split by newline if title contains \n
+            if '\n' in title:
+                title_lines = title.split('\n')
+            else:
+                title_lines = [title]
+        
+        # Step 2: Filter templates by color contrast
+        filtered_templates = self._filter_templates_by_contrast(
+            candidate_templates, background_color, primary_color
+        )
+        
+        if not filtered_templates:
+            print("⚠️  All templates filtered out due to insufficient contrast with background")
+            return []
+        
+        # Step 3: Generate SVG
+        # Single-template / standard / specified branches don't have a real
+        # rec; mark the split source as 'literal' (kept the raw title or just
+        # split on newlines).
+        rec_split_method = locals().get('rec_split_method', 'literal')
+        results = []
+
+        for template in filtered_templates:
+            try:
+                result = self._generate_with_template(
+                    template, title_lines, description,
+                    primary_color, secondary_color, background_color, max_width
+                )
+
+                if result:
+                    result['title_lines'] = title_lines
+                    result['split_method'] = rec_split_method
+                    results.append(result)
+                    print(f"  ✓ Template '{template.name}' generated successfully")
+            except Exception as e:
+                print(f"  ✗ Template '{template.name}' generation failed: {e}")
+                continue
+        
+        print(f"\n{'='*60}")
+        print(f"🎉 Total generated {len(results)} result(s)")
+        print(f"{'='*60}")
+        
+        return results
+    
+    def _select_templates(self,
+                         has_description: bool,
+                         alignment: Optional[str],
+                         template_name: Optional[str],
+                         style: Optional[str] = None) -> List[TitleTemplate]:
+        """Select suitable templates"""
+        candidates = []
+        
+        # If template name is specified, use only that template
+        if template_name:
+            for template in self.templates:
+                if template.name == template_name:
+                    candidates.append(template)
+            return candidates
+        
+        # Filter by description availability
+        if has_description:
+            candidates = get_templates_with_description()
+        else:
+            candidates = get_templates_main_only()
+        
+        # Filter by alignment
+        if alignment:
+            candidates = [t for t in candidates if t.alignment == alignment]
+        
+        # Filter by style
+        if style and style != 'all':
+            candidates = [t for t in candidates if t.style == style]
+        
+        return candidates
+    
+    def _filter_templates_by_contrast(self, templates: List[TitleTemplate], 
+                                      background_color: str, 
+                                      primary_color: str,
+                                      min_contrast: float = 2.5) -> List[TitleTemplate]:
+        """
+        Filter templates by color contrast with page background
+        Skip templates where text or background rectangles are too similar to page background
+        
+        Args:
+            templates: Template list to filter
+            background_color: Page background color
+            primary_color: Primary color (user-provided, skip checking)
+            min_contrast: Minimum acceptable contrast ratio (default 2.5)
+        
+        Returns:
+            Filtered template list
+        """
+        filtered = []
+        
+        for template in templates:
+            # Get all lines
+            all_lines = template.lines if template.lines else []
+            
+            is_acceptable = True
+            
+            for line in all_lines:
+                colors_to_check = []
+                
+                # Rule 1: If line has background rectangle, check rectangle vs page background
+                if line.background and isinstance(line.background, dict):
+                    bg_rect_color = line.background.get('color')
+                    # Only check fixed colors, skip primary_color/secondary_color
+                    if bg_rect_color and bg_rect_color not in ['primary_color', 'secondary_color']:
+                        colors_to_check.append(('background rect', bg_rect_color))
+                # Rule 2: If no background rectangle, check text color vs page background
+                else:
+                    # Skip primary_color/secondary_color (user-provided)
+                    if line.color_type == COLOR_TYPE_FIXED and line.color_value:
+                        colors_to_check.append(('text', line.color_value))
+                
+                # Calculate contrast
+                for color_type, check_color in colors_to_check:
+                    try:
+                        contrast = contrast_ratio(check_color, background_color)
+                        if contrast < min_contrast:
+                            # print(f"  ⚠️  Template '{template.name}' skipped: {color_type} {check_color} vs page bg {background_color} = {contrast:.2f} (< {min_contrast})")
+                            is_acceptable = False
+                            break
+                    except Exception:
+                        # If contrast calculation fails, accept the template
+                        pass
+                
+                if not is_acceptable:
+                    break
+            
+            if is_acceptable:
+                filtered.append(template)
+        
+        return filtered
+    
+    def _generate_with_template(self,
+                                template: TitleTemplate,
+                                title_lines: List[str],
+                                description: Optional[str],
+                                primary_color: str,
+                                secondary_color: Optional[str],
+                                background_color: str,
+                                max_width: Optional[int]) -> Optional[Dict]:
+        """Generate SVG with specified template"""
+        
+        # Check if template has inline groups
+        inline_groups = getattr(template, 'inline_groups', [])
+        
+        # Single column layout
+        lines_data = []
+        line_configs = []
+        
+        title_idx = 0
+        
+        for line_idx, line_config in enumerate(template.lines):
+            # Determine which text to use based on role
+            if line_config.role == 'main':
+                # Use title lines split by LLM
+                if title_idx < len(title_lines):
+                    text = title_lines[title_idx]
+                    title_idx += 1
+                else:
+                    continue
+            elif line_config.role == 'description':
+                if description:
+                    text = description
+                else:
+                    continue
+            else:
+                continue
+            
+            # Convert to dict and apply colors
+            config = line_config.to_dict()
+            
+            # Parse color
+            if config['color_type'] == COLOR_TYPE_PRIMARY:
+                config['final_color'] = primary_color
+            elif config['color_type'] == COLOR_TYPE_SECONDARY:
+                config['final_color'] = secondary_color or primary_color
+            else:  # FIXED
+                config['final_color'] = config['color_value']
+            
+            # Handle background color (if background exists and color is primary_color)
+            if config.get('background') and isinstance(config['background'], dict):
+                bg_color = config['background'].get('color')
+                if bg_color == 'primary_color':
+                    config['background']['color'] = primary_color
+                elif bg_color == 'secondary_color':
+                    config['background']['color'] = secondary_color or primary_color
+            
+            lines_data.append(text)
+            line_configs.append(config)
+        
+        # Mark inline groups in configs (don't merge yet, let renderer handle it)
+        if inline_groups:
+            for i, config in enumerate(line_configs):
+                # Check if this index is in an inline group
+                for group_start, group_end in inline_groups:
+                    if group_start <= i <= group_end:
+                        config['inline_group'] = (group_start, group_end)
+                        config['inline_position'] = i - group_start  # Position within group (0, 1, 2...)
+                        break
+        
+        if not lines_data:
+            return None
+        
+        # Render SVG (with inline group info in configs)
+        svg_string, (width, height) = self.renderer.render_svg(
+            lines_data, line_configs, template.alignment, max_width, background_color
+        )
+
+        # Build a self-contained, render-reproducible record for each segment.
+        # We resolve color_type → final hex here so consumers don't need the
+        # original primary/secondary palette to recreate the look.
+        segments = []
+        for txt, cfg in zip(lines_data, line_configs):
+            seg = {
+                'text': txt,
+                'role': cfg.get('role'),
+                'importance': cfg.get('importance'),
+                'font_family': cfg.get('font_family'),
+                'font_size': cfg.get('font_size'),
+                'font_weight': cfg.get('font_weight'),
+                'font_style': cfg.get('font_style'),
+                'color': cfg.get('final_color') or cfg.get('color_value'),
+                'text_transform': cfg.get('text_transform', 'none'),
+                'letter_spacing': cfg.get('letter_spacing', 0),
+                'background': cfg.get('background') or None,
+                'underline': cfg.get('underline', False),
+                'strikethrough': cfg.get('strikethrough', False),
+                'outline': cfg.get('outline', False),
+                'shadow': cfg.get('shadow', False),
+                'inline_group': list(cfg['inline_group']) if cfg.get('inline_group') else None,
+            }
+            segments.append(seg)
+
+        return {
+            'template_name': template.name,
+            'template_description': template.description,
+            'svg': svg_string,
+            'width': width,
+            'height': height,
+            'alignment': template.alignment,
+            'segments': segments,
+            'primary_color': primary_color,
+            'secondary_color': secondary_color,
+            'background_color': background_color,
+        }
+    
+    def analyze_title(self,
+                      title: str,
+                      description: Optional[str] = None,
+                      primary_color: str = '#2E7D32',
+                      background_color: str = '#FFFFFF',
+                      alignment: Optional[str] = None,
+                      top_k: int = 3,
+                      style: Optional[str] = None) -> Optional[Dict]:
+        """
+        Analyze title with LLM to get template recommendations and title splitting.
+        This method only calls LLM once and returns analysis results for later SVG generation.
+        
+        Args:
+            title: Main title text
+            description: Subtitle/description text (optional)
+            primary_color: Primary color for contrast checking
+            background_color: Background color for contrast checking
+            alignment: Alignment filter ('left', 'center', 'right')
+            top_k: Number of template recommendations to return
+            style: Template style filter
+        
+        Returns:
+            Dict containing:
+            - recommendations: List of template recommendations with title_split
+            - has_description: Whether description was provided
+            - primary_color: Primary color
+            - background_color: Background color
+            - alignment: Alignment
+            - style: Style filter
+        """
+        if not self.use_llm:
+            print("❌ LLM is disabled, cannot analyze title")
+            return None
+        
+        print(f"🤖 Analyzing title with LLM to recommend top-{top_k} templates...")
+        
+        # Step 1: Pre-filter all templates by contrast, style, and alignment
+        print(f"  📋 Step 1: Filtering templates by contrast with background {background_color}")
+        
+        # Apply style filter first if specified
+        templates_to_check = self.templates
+        if style and style != 'all':
+            templates_to_check = [t for t in templates_to_check if t.style == style]
+            print(f"  🎨 Style filter: {style} ({len(templates_to_check)} templates match)")
+        
+        all_contrast_valid = self._filter_templates_by_contrast(
+            templates_to_check, background_color, primary_color
+        )
+        
+        if not all_contrast_valid:
+            print("  ❌ All templates filtered out by contrast check")
+            return None
+        
+        print(f"  ✅ {len(all_contrast_valid)}/{len(templates_to_check)} templates passed contrast check")
+
+        # Hard cap on total visible rows (main segments + optional desc).
+        row_budget_kept = self._filter_templates_by_row_budget(
+            all_contrast_valid, has_description=(description is not None)
+        )
+        if row_budget_kept:
+            if len(row_budget_kept) != len(all_contrast_valid):
+                print(f"  ✂️  Row-budget filter (<= {self.max_total_rows} rows total): "
+                      f"{len(row_budget_kept)}/{len(all_contrast_valid)} kept")
+            all_contrast_valid = row_budget_kept
+        else:
+            print("  ⚠️  Row-budget filter would drop everything; keeping contrast-valid pool as-is")
+
+        # Apply alignment filter if specified
+        if alignment:
+            templates_with_alignment = [t for t in all_contrast_valid if t.alignment == alignment]
+            if not templates_with_alignment:
+                print(f"  ⚠️  No templates found with alignment='{alignment}', falling back to all alignments")
+            else:
+                all_contrast_valid = templates_with_alignment
+                print(f"  ✅ Alignment filter: {alignment} ({len(all_contrast_valid)} templates match)")
+        
+        # Step 2: Group filtered templates by segment count for diversity
+        print(f"  📊 Step 2: Sampling diverse templates from filtered set")
+        import random
+        templates_by_segments = {}
+        
+        for t in all_contrast_valid:
+            segments = []
+            if t.lines:
+                segments = [l for l in t.lines if l.role == 'main']
+            
+            seg_count = len(segments)
+            if seg_count not in templates_by_segments:
+                templates_by_segments[seg_count] = []
+            
+            templates_by_segments[seg_count].append({
+                'template': t,
+                'segment_count': seg_count
+            })
+        
+        # Sample 3 templates from each segment count group
+        sampled_templates = []
+        for seg_count in sorted(templates_by_segments.keys()):
+            group = templates_by_segments[seg_count]
+            sample_size = min(3, len(group))
+            sampled = random.sample(group, sample_size)
+            sampled_templates.extend(sampled)
+        
+        print(f"  📌 Sampled {len(sampled_templates)} diverse templates")
+        
+        # Step 3: Prepare template info for LLM
+        print(f"  🤖 Step 3: Sending {len(sampled_templates)} templates to LLM")
+        templates_info = []
+        for item in sampled_templates:
+            t = item['template']
+            info = {
+                'name': t.name,
+                'description': t.description,
+                'segment_roles': getattr(t, 'segment_roles', ''),
+                'segment_count': item['segment_count']
+            }
+            templates_info.append(info)
+        
+        top_k_result = self.analyzer.recommend_top_k_templates(title, templates_info, top_k)
+        
+        if not top_k_result:
+            print("  ❌ LLM analysis failed")
+            return None
+        
+        recommendations_list = top_k_result.get('recommendations', [])
+        
+        print(f"  ✅ LLM Analysis - Top {len(recommendations_list)} Recommendations:")
+        for i, rec in enumerate(recommendations_list, 1):
+            print(f"     {i}. {rec['template_name']} (confidence: {rec.get('confidence', 0):.2f})")
+            if rec.get('paraphrased_title'):
+                print(f"        Paraphrased: \"{rec['paraphrased_title']}\"")
+            print(f"        Split: {rec['title_split']}")
+        
+        return {
+            'recommendations': recommendations_list,
+            'has_description': description is not None,
+            'description': description,
+            'primary_color': primary_color,
+            'background_color': background_color,
+            'alignment': alignment,
+            'style': style
+        }
+    
+    def generate_with_analysis(self,
+                               analysis_result: Dict,
+                               max_widths: List[int],
+                               secondary_color: Optional[str] = None,
+                               recommendation_index: int = 0) -> List[Dict]:
+        """
+        Generate SVGs based on pre-computed LLM analysis with multiple widths.
+        This method does not call LLM and generates SVGs for each width.
+        
+        Args:
+            analysis_result: Result from analyze_title()
+            max_widths: List of max_width values to generate for
+            secondary_color: Secondary color (optional)
+            recommendation_index: Which recommendation to use (default 0, the first/best one)
+        
+        Returns:
+            List of results, one for each max_width, each containing:
+            - template_name: Template name used
+            - svg: SVG string
+            - width: SVG width
+            - height: SVG height
+            - max_width_requested: The max_width that was requested
+        """
+        if not analysis_result or 'recommendations' not in analysis_result:
+            print("❌ Invalid analysis result")
+            return []
+        
+        recommendations = analysis_result['recommendations']
+        if not recommendations:
+            print("❌ No recommendations in analysis result")
+            return []
+        
+        if recommendation_index >= len(recommendations):
+            recommendation_index = 0
+        
+        rec = recommendations[recommendation_index]
+        template_name = rec['template_name']
+        title_split = rec['title_split']
+        split_method = rec.get('split_method') or analysis_result.get('split_method') or 'llm'
+
+        description = analysis_result.get('description')
+        primary_color = analysis_result.get('primary_color', '#2E7D32')
+        background_color = analysis_result.get('background_color', '#FFFFFF')
+        alignment = analysis_result.get('alignment')
+        style = analysis_result.get('style')
+        
+        # Find the template
+        templates = self._select_templates(
+            has_description=analysis_result.get('has_description', False),
+            alignment=alignment,
+            template_name=template_name,
+            style=style
+        )
+        
+        if not templates:
+            print(f"❌ Template '{template_name}' not found")
+            return []
+        
+        template = templates[0]
+        
+        print(f"🎨 Generating SVGs for {len(max_widths)} different widths with template '{template_name}'")
+        
+        results = []
+        for max_width in max_widths:
+            result = self._generate_with_template(
+                template, title_split, description,
+                primary_color, secondary_color, background_color, max_width
+            )
+            
+            if result:
+                result['max_width_requested'] = max_width
+                result['split_method'] = split_method
+                results.append(result)
+                print(f"  ✓ Width {max_width}: generated {result['width']}x{result['height']}px")
+        
+        return results
+    
+    def save_result(self, result: Dict, filepath: str):
+        """
+        Save generation result to file
+        
+        Args:
+            result: Generation result dictionary
+            filepath: Output file path
+        """
+        # Ensure directory exists
+        os.makedirs(os.path.dirname(filepath) if os.path.dirname(filepath) else '.', exist_ok=True)
+        
+        with open(filepath, 'w', encoding='utf-8') as f:
+            f.write(result['svg'])
+        
+        print(f"SVGSaved to: {filepath}")
+    
+    def save_all_results(self, results: List[Dict], session_name: str = None) -> str:
+        """
+        Save all generation results to output directory (flat structure)
+        
+        Args:
+            results: Generation result list
+            session_name: Session name or filepath prefix (e.g., "test" or "output/test.svg")
+        
+        Returns:
+            Output directory path
+        """
+        if session_name is None:
+            session_name = datetime.now().strftime("%Y%m%d_%H%M%S")
+        
+        # Remove .svg extension if present
+        if session_name.endswith('.svg'):
+            session_name = session_name[:-4]
+        
+        # Extract directory and base name from session_name
+        if '/' in session_name:
+            output_dir = os.path.dirname(session_name)
+            base_name = os.path.basename(session_name)
+        else:
+            output_dir = "output"
+            base_name = session_name
+        
+        os.makedirs(output_dir, exist_ok=True)
+        
+        print(f"\n📁 Saving to directory: {output_dir}")
+        print(f"{'='*60}")
+        
+        for i, result in enumerate(results, 1):
+            # Use base_name as filename prefix, include template name in filename
+            template_name = result.get('template_name', 'unknown')
+            if len(results) > 1:
+                filename = f"{base_name}_{i}_{template_name}.svg"
+            else:
+                filename = f"{base_name}_{template_name}.svg"
+            filepath = os.path.join(output_dir, filename)
+            
+            with open(filepath, 'w', encoding='utf-8') as f:
+                f.write(result['svg'])
+            
+            print(f"  ✓ {filename} ({result['width']}x{result['height']}px)")
+        
+        print(f"{'='*60}")
+        print(f"✅ Total saved {len(results)} file(s) to {output_dir}/")
+        
+        return output_dir
+
+
+# Convenience functions
+def generate_title(title: str,
+                   description: Optional[str] = None,
+                   primary_color: str = '#2E7D32',
+                   secondary_color: Optional[str] = None,
+                   background_color: str = '#FFFFFF',
+                   max_width: Optional[int] = None,
+                   alignment: Optional[str] = None,
+                   template_name: Optional[str] = None,
+                   use_llm: bool = True,
+                   top_k: Optional[int] = None,
+                   style: Optional[str] = None,
+                   save_to: Optional[str] = None) -> List[Dict]:
+    """
+    Convenience function: Generate infographic title
+    
+    Args:
+        title: Main title
+        description: Subtitle/description
+        primary_color: Primary color
+        secondary_color: Secondary color
+        background_color: Background color
+        max_width: Maximum width
+        alignment: Alignment (left/center/right)
+        template_name: Specify template name
+        use_llm: Whether to use LLM to analyze title (default True)
+        top_k: Number of templates to try (default None, only when use_llm=True and template_name=None)
+        style: Template style filter ('normal', 'comic', 'simple', 'professional', 'all' or None)
+        save_to: Save path (optional), if provided, all results will be saved automatically
+    
+    Returns:
+        Generation result list
+    """
+    generator = InfographicTitleGenerator(use_llm=use_llm)
+    results = generator.generate(
+        title=title,
+        description=description,
+        primary_color=primary_color,
+        secondary_color=secondary_color,
+        background_color=background_color,
+        max_width=max_width,
+        alignment=alignment,
+        template_name=template_name,
+        top_k=top_k,
+        style=style
+    )
+    
+    # If save_to is specified, automatically save all results
+    if save_to and results:
+        generator.save_all_results(results, save_to)
+    
+    return results
+
+
+

modules/title_styler/llm_analyzer.py

@@ -0,0 +1,628 @@
+"""
+Infographic Title Generator - LLM Analyzer
+Use LLM to analyze title structure and recommend suitable templates
+"""
+
+import json
+import os
+import random
+import re
+import requests
+from typing import Dict, List, Optional
+
+
+def _split_title_evenly(title: str, n_segments: int) -> List[str]:
+    """按词把 title 大致均分成 n 段，作为最后兜底（语义切分也失败时使用）。"""
+    if n_segments <= 0:
+        n_segments = 1
+    text = (title or "").strip()
+    if not text:
+        return [""] * n_segments
+    words = re.split(r"\s+", text)
+    if len(words) <= n_segments:
+        out = list(words)
+        while len(out) < n_segments:
+            out.append("")
+        return out
+    base = len(words) // n_segments
+    extra = len(words) % n_segments
+    parts: List[str] = []
+    idx = 0
+    for i in range(n_segments):
+        take = base + (1 if i < extra else 0)
+        parts.append(" ".join(words[idx:idx + take]))
+        idx += take
+    return parts
+
+
+# === Heuristic semantic splitter ===================================
+# When LLM is disabled (default in the prod pipeline) we still want the
+# title to break at natural language boundaries — colons, commas, the
+# word "vs.", before prepositions / conjunctions — instead of a blind
+# even-by-words split. This module-local DP picks N-1 break points to
+# maximise a token-gap score table.
+
+_PREPOSITIONS = frozenset({
+    "of", "in", "by", "with", "for", "from", "on", "over", "per",
+    "to", "at", "into", "across", "between", "after", "before",
+    "during", "since", "through", "via", "under", "above",
+})
+_CONJUNCTIONS = frozenset({"and", "or", "but", "vs", "vs.", "versus", "&"})
+
+
+def _gap_score(left_word: str, right_word: str) -> float:
+    """Score the desirability of breaking after ``left_word``.
+
+    Higher = more natural break point. Negative numbers mean "fairly
+    arbitrary place to break" (we still let length-balance decide there).
+    """
+    lw = (left_word or "").rstrip()
+    rw_lower = (right_word or "").lower().lstrip()
+    if not lw or not rw_lower:
+        return 0.0
+
+    # Hard punctuation at the end of left word — strongest preference.
+    last = lw[-1]
+    if last == ":":
+        return 1000.0
+    if last == ";":
+        return 900.0
+    if last in {"—", "–"}:
+        return 850.0
+    if last == "?" or last == "!":
+        return 800.0
+    if last == "." and len(lw) > 2 and not lw.endswith(("Mr.", "Mrs.", "Dr.", "St.", "vs.")):
+        # Likely sentence-ending period (skip common abbreviations and "vs.").
+        return 700.0
+    if last == ",":
+        return 500.0
+
+    # Soft preference: break BEFORE conjunctions / prepositions.
+    rw_clean = rw_lower.rstrip(",.;:")
+    if rw_clean in _CONJUNCTIONS:
+        return 250.0
+    if rw_clean in _PREPOSITIONS:
+        return 150.0
+
+    # Fallback: arbitrary mid-phrase break, no bonus, length balance wins.
+    return 0.0
+
+
+def _split_title_semantic(title: str, n_segments: int) -> List[str]:
+    """Split ``title`` into ``n_segments`` segments by maximising a
+    semantic-break score subject to length balance.
+
+    Algorithm:
+      1) Tokenise on whitespace; collect word widths in characters.
+      2) For every gap i (between word[i] and word[i+1]) compute a
+         positive bonus from punctuation/POS, then add a length-balance
+         term that penalises uneven segment widths.
+      3) Greedy DP: dp[k][i] = best score for splitting the first i words
+         into k segments. Pick the top N-1 gaps that maximise the sum.
+
+    Falls back to even split when title is too short for ``n_segments``.
+    """
+    if n_segments <= 0:
+        n_segments = 1
+    text = (title or "").strip()
+    if not text:
+        return [""] * n_segments
+    words = re.split(r"\s+", text)
+    W = len(words)
+    if n_segments == 1:
+        return [" ".join(words)]
+    if W <= n_segments:
+        out = list(words)
+        while len(out) < n_segments:
+            out.append("")
+        return out
+
+    # Per-word "width" in characters (proxy for visual width). Spaces between
+    # words add 1 char.
+    char_lens = [len(w) for w in words]
+    # cumulative chars (each word + 1 space sep, except first), len = W+1
+    cum = [0] * (W + 1)
+    for i, c in enumerate(char_lens):
+        cum[i + 1] = cum[i] + c + (1 if i > 0 else 0)
+    total_chars = cum[W]
+    target_seg = total_chars / n_segments
+
+    def seg_chars(s: int, e: int) -> int:
+        """Chars in words[s..e-1] joined by spaces."""
+        if e <= s:
+            return 0
+        return cum[e] - cum[s] - (1 if s > 0 else 0)
+
+    # Pre-compute gap bonuses for every internal gap i (break AFTER word i).
+    gap_bonus = [0.0] * (W - 1)
+    for i in range(W - 1):
+        gap_bonus[i] = _gap_score(words[i], words[i + 1])
+
+    def seg_score(s: int, e: int) -> float:
+        """Score of segment words[s..e-1] viewed as one row."""
+        if e <= s:
+            return -1e9
+        c = seg_chars(s, e)
+        # Penalise distance from ideal segment length (per char).
+        # Coefficient 5 keeps it on the same order as gap bonuses for typical
+        # text (10-50 char titles), so a "+150 break before preposition"
+        # never beats a 30-char balance issue.
+        return -5.0 * abs(c - target_seg)
+
+    # dp[k][i] = best total score using first i words in exactly k segments.
+    # Track parent pointers to reconstruct the breaks.
+    NEG_INF = float("-inf")
+    dp = [[NEG_INF] * (W + 1) for _ in range(n_segments + 1)]
+    parent = [[-1] * (W + 1) for _ in range(n_segments + 1)]
+    dp[0][0] = 0.0
+    for k in range(1, n_segments + 1):
+        # Each segment must have at least 1 word; previous segments need
+        # at least k-1 words; final segment must leave at least 1 word.
+        for i in range(k, W + 1):
+            best = NEG_INF
+            best_j = -1
+            for j in range(k - 1, i):
+                if dp[k - 1][j] == NEG_INF:
+                    continue
+                # Break after word j (i.e. between word j-1 and word j when
+                # j > 0); add the gap bonus for that break.
+                gap = gap_bonus[j - 1] if j > 0 else 0.0
+                cand = dp[k - 1][j] + seg_score(j, i) + gap
+                if cand > best:
+                    best = cand
+                    best_j = j
+            dp[k][i] = best
+            parent[k][i] = best_j
+
+    # Reconstruct boundaries.
+    boundaries = []
+    i = W
+    for k in range(n_segments, 0, -1):
+        j = parent[k][i]
+        boundaries.append((j, i))
+        i = j
+    boundaries.reverse()
+
+    parts = [" ".join(words[s:e]) for s, e in boundaries]
+    # Safety net — should never trigger, but keep length contract.
+    while len(parts) < n_segments:
+        parts.append("")
+    return parts[:n_segments]
+
+
+class LLMAnalyzer:
+    """LLM Title Analyzer"""
+    
+    def __init__(self, api_key=None, base_url=None, model=None):
+        """
+        Initialize LLM analyzer
+        
+        Args:
+            api_key: API key (default uses built-in key)
+            base_url: API base URL (default uses built-in URL)
+            model: Model name (default uses gpt-5-mini)
+        """
+        # Use provided API configuration（环境变量优先，缺省禁用 LLM 走 fallback）
+        self.api_key = api_key or os.environ.get('CHARTPIPELINE_LLM_API_KEY') or ''
+        self.base_url = base_url or os.environ.get('CHARTPIPELINE_LLM_BASE_URL') or 'https://aihubmix.com/v1'
+        self.model = model or os.environ.get('CHARTPIPELINE_LLM_MODEL') or 'deepseek-v3.2'
+        self.llm_disabled = os.environ.get('CHARTPIPELINE_DISABLE_LLM', '1') == '1' or not self.api_key
+        # 仅第一次失败时打印 fallback 提示，避免刷屏
+        self._fallback_logged = False
+
+    def _log_fallback_once(self, reason: str):
+        if not self._fallback_logged:
+            print(f"  ⚠️  LLM unavailable ({reason}), using local heuristic fallback for title styling")
+            self._fallback_logged = True
+
+    def _fallback_single(self, title: str, templates_info: Optional[List[Dict]]) -> Dict:
+        """LLM 失败时的单模板 fallback。"""
+        self._log_fallback_once("single-template")
+        if templates_info:
+            chosen = random.choice(templates_info)
+            name = chosen['name']
+            seg = int(chosen.get('segment_count') or len(chosen.get('segments', [])) or 1)
+        else:
+            name = 'infographic_standard'
+            seg = 1
+        return {
+            'recommended_template': name,
+            'title_split': _split_title_semantic(title, seg),
+            'split_method': 'semantic_dp',
+            'reasoning': 'fallback: LLM disabled, picked template by random sampling and split title via semantic DP',
+        }
+
+    def _fallback_top_k(self, title: str, all_templates_info: list, top_k: int) -> Dict:
+        """LLM 失败时的 top-k fallback。"""
+        self._log_fallback_once("top-k")
+        if not all_templates_info:
+            return {'recommendations': []}
+        pool = list(all_templates_info)
+        random.shuffle(pool)
+        recs = []
+        for info in pool[:max(1, top_k)]:
+            seg = int(info.get('segment_count') or 1)
+            recs.append({
+                'template_name': info['name'],
+                'title_split': _split_title_semantic(title, seg),
+                'split_method': 'semantic_dp',
+                'paraphrased_title': None,
+                'confidence': 0.5,
+                'reasoning': 'fallback: LLM disabled, random template + semantic DP split',
+            })
+        return {'recommendations': recs}
+    
+    def recommend_template(self, title: str, has_description: bool = True, templates_info: Optional[List[Dict]] = None) -> Dict:
+        """
+        Analyze title and recommend suitable template with splitting scheme
+        
+        Args:
+            title: Main title text
+            has_description: Whether description is provided
+            templates_info: List of template info dicts (optional, for filtering by style)
+        
+        Returns:
+            Dictionary containing:
+            {
+                'recommended_template': 'template_name',
+                'title_split': ['line1', 'line2', ...],
+                'reasoning': 'explanation'
+            }
+        """
+        return self._analyze_with_llm(title, has_description, templates_info)
+    
+    def recommend_top_k_templates(self, title: str, all_templates_info: list, top_k: int = 3) -> Dict:
+        """
+        Analyze title and recommend top-k suitable templates with splitting schemes
+        
+        Args:
+            title: Main title text
+            all_templates_info: List of template info dicts with name, description, segment_roles, segments
+            top_k: Number of templates to recommend (default 3)
+        
+        Returns:
+            Dictionary containing:
+            {
+                'recommendations': [
+                    {
+                        'template_name': 'template1',
+                        'title_split': ['line1', 'line2', ...],
+                        'paraphrased_title': 'Restructured title or null',
+                        'confidence': 0.95,
+                        'reasoning': 'explanation'
+                    },
+                    ...
+                ]
+            }
+        """
+        return self._analyze_with_llm_top_k(title, all_templates_info, top_k)
+    
+    
+    def _analyze_with_llm(self, title: str, has_description: bool, templates_info: Optional[List[Dict]] = None) -> Dict:
+        """
+        Use LLM API to analyze and recommend template
+        """
+        if self.llm_disabled:
+            return self._fallback_single(title, templates_info)
+
+        # Build prompt
+        prompt = self._build_recommendation_prompt(title, has_description, templates_info)
+        
+        # Call LLM API
+        try:
+            response = self._query_llm(prompt)
+            
+            if response:
+                # Parse JSON response
+                try:
+                    # Try to clean possible markdown code blocks
+                    cleaned_response = response.strip()
+                    if cleaned_response.startswith('```'):
+                        lines = cleaned_response.split('\n')
+                        cleaned_response = '\n'.join(lines[1:-1] if lines[-1].strip() == '```' else lines[1:])
+                        cleaned_response = cleaned_response.replace('```json', '').replace('```', '').strip()
+                    
+                    result = json.loads(cleaned_response)
+                    
+                    # Validate return format
+                    if 'recommended_template' in result and 'title_split' in result:
+                        # Validate template name if templates_info is provided
+                        if templates_info:
+                            available_names = [t['name'] for t in templates_info]
+                            if result['recommended_template'] not in available_names:
+                                print(f"❌ Unknown template '{result['recommended_template']}'")
+                                return None
+                        return result
+                    else:
+                        print("❌ LLM response missing required fields")
+                        return self._fallback_single(title, templates_info)
+                        
+                except json.JSONDecodeError as e:
+                    print(f"❌ LLM response is not valid JSON")
+                    print(f"Response: {response[:200]}...")
+                    return self._fallback_single(title, templates_info)
+            else:
+                return self._fallback_single(title, templates_info)
+                
+        except Exception as e:
+            print(f"❌ LLM analysis error: {e}")
+            return self._fallback_single(title, templates_info)
+    
+    def _query_llm(self, prompt: str) -> Optional[str]:
+        """
+        Query LLM API
+        
+        Args:
+            prompt: Prompt to send to LLM
+        
+        Returns:
+            str: LLM response content
+        """
+        headers = {
+            'Authorization': f'Bearer {self.api_key}',
+            'Content-Type': 'application/json'
+        }
+        
+        data = {
+            'model': self.model,
+            'messages': [
+                {
+                    'role': 'system', 
+                    'content': 'You are a professional infographic design assistant, skilled at analyzing title structure and visual hierarchy. Always return valid JSON format only, without any markdown formatting or extra text.'
+                },
+                {
+                    'role': 'user', 
+                    'content': prompt
+                }
+            ],
+            'temperature': 0.3
+        }
+        
+        try:
+            response = requests.post(
+                f'{self.base_url}/chat/completions',
+                headers=headers,
+                json=data,
+                timeout=30
+            )
+            response.raise_for_status()
+            
+            result = response.json()
+            return result['choices'][0]['message']['content'].strip()
+            
+        except requests.exceptions.Timeout:
+            print("❌ LLM API timeout")
+            return None
+        except requests.exceptions.HTTPError as e:
+            print(f"❌ LLM API HTTP error: {e}")
+            if hasattr(e.response, 'text'):
+                print(f"   Response: {e.response.text[:200]}")
+            return None
+        except requests.exceptions.RequestException as e:
+            print(f"❌ LLM API request error: {e}")
+            return None
+        except KeyError as e:
+            print(f"❌ LLM API response format error: {e}")
+            return None
+    
+    def _analyze_with_llm_top_k(self, title: str, all_templates_info: list, top_k: int = 3) -> Dict:
+        """
+        Use LLM API to recommend top-k templates
+        
+        Args:
+            title: Main title text
+            all_templates_info: List of template info dicts
+            top_k: Number of templates to recommend
+        
+        Returns:
+            Dictionary with recommendations list
+        """
+        if self.llm_disabled:
+            return self._fallback_top_k(title, all_templates_info, top_k)
+
+        # Build prompt for top-k recommendation
+        prompt = self._build_top_k_prompt(title, all_templates_info, top_k)
+        
+        # Call LLM API
+        try:
+            response = self._query_llm(prompt)
+            
+            if response:
+                # Parse JSON response
+                try:
+                    cleaned_response = response.strip()
+                    if cleaned_response.startswith('```'):
+                        lines = cleaned_response.split('\n')
+                        cleaned_response = '\n'.join(lines[1:-1] if lines[-1].strip() == '```' else lines[1:])
+                        cleaned_response = cleaned_response.replace('```json', '').replace('```', '').strip()
+                    
+                    result = json.loads(cleaned_response)
+                    
+                    # Validate return format
+                    if 'recommendations' in result and isinstance(result['recommendations'], list):
+                        return result
+                    else:
+                        print("❌ LLM response missing required 'recommendations' field")
+                        return self._fallback_top_k(title, all_templates_info, top_k)
+                        
+                except json.JSONDecodeError as e:
+                    print(f"❌ LLM response is not valid JSON")
+                    return self._fallback_top_k(title, all_templates_info, top_k)
+            else:
+                return self._fallback_top_k(title, all_templates_info, top_k)
+                
+        except Exception as e:
+            print(f"❌ LLM analysis error: {e}")
+            return self._fallback_top_k(title, all_templates_info, top_k)
+    
+    def _build_recommendation_prompt(self, title: str, has_description: bool, templates_info: Optional[List[Dict]] = None) -> str:
+        """Build LLM recommendation prompt"""
+        
+        # Build default templates info if not provided
+        if not templates_info:
+            # Use a basic set of templates
+            templates_list = [
+                {"name": "infographic_standard", "description": "Single line bold title", "segments": 1},
+                {"name": "two_line_hierarchy", "description": "Two-line: small prefix + large main title", "segments": 2},
+                {"name": "three_line_emphasis", "description": "Three-line: prefix + emphasized middle + suffix", "segments": 3}
+            ]
+        else:
+            templates_list = templates_info
+        
+        templates_desc = "\n".join([
+            f"- **{t['name']}**: {t.get('description', 'No description')}, segments: {t.get('segment_count', len(t.get('segments', [])))}"
+            for t in templates_list
+        ])
+        
+        prompt = f"""
+Analyze this infographic title to recommend the layout template and split strategy.
+
+Input Data:
+- Title: "{title}"
+- Has Subtitle/Description: {has_description}
+
+### Task
+1. Identify the **PRIMARY** focus (The "Hero" of the title) and **SECONDARY** context.
+2. Recommend the best template (`infographic_standard`, `two_line_hierarchy`, or `three_line_emphasis`).
+3. Split the title text strictly according to the template rules.
+
+### 1. Semantic Analysis Rules
+**PRIMARY Segment (The "Hero"):**
+- The core metric, main topic, or "What" the chart shows.
+- *Examples:* "GDP Growth", "Carbon Emissions", "Mobile Phones", "Annual Report".
+- **Constraint:** NEVER split a noun phrase inside the Primary segment.
+
+**SECONDARY Segment (The "Context"):**
+- Modifiers, Prepositions, Locations, Time, or "Which/Where/When".
+- *Examples:* "The United States of...", "Trends in...", "...of All Time", "Global...", "Top 10...".
+- *Note:* If a title contains both a Metric (e.g., Inflation) and a Location (e.g., in Europe), treat the Metric as PRIMARY and Location as SECONDARY.
+
+### 2. Template Selection Guidelines
+**Option A: infographic_standard**
+- *Criteria:* Short titles (1-5 words) OR titles that are a single cohesive phrase.
+- *Split Strategy:* Return as a single string in the array.
+- *Example:* ["Annual Report 2023"]
+
+**Option B: two_line_hierarchy**
+- *Criteria:* Strong prefix (Context) + Main Topic (Hero). Good for "The X of Y" structures.
+- *Split Strategy:* - Line 1: Secondary Context (Prefix)
+  - Line 2: Primary Topic (Hero)
+- *Example:* ["The United States of", "Food Inflation"]
+
+**Option C: three_line_emphasis**
+- *Criteria:* Long titles (6+ words) with a "Sandwich" structure: Context + Hero + Context.
+- *Split Strategy:*
+  - Line 1: Secondary Context (Prefix)
+  - Line 2: Primary Topic (Hero - Centerpiece)
+  - Line 3: Secondary Context (Suffix)
+- *Example:* ["The Best Selling", "Mobile Phones", "of All Time"]
+
+### Output Format
+Return ONLY valid JSON:
+```json
+{{
+  "recommended_template": "template_name",
+  "title_split": ["string1", "string2", ...],
+  "reasoning": "Explain why this template was chosen based on the Primary/Secondary analysis."
+}}
+"""
+        
+        return prompt
+    
+    def _build_top_k_prompt(self, title: str, all_templates_info: list, top_k: int) -> str:
+        """
+        Build prompt for top-k template recommendation
+        
+        Args:
+            title: Main title text
+            all_templates_info: List of template info with segment_roles
+            top_k: Number of recommendations
+        
+        Returns:
+            Prompt string
+        """
+        # Build templates list for prompt
+        templates_desc = []
+        for info in all_templates_info:
+            name = info['name']
+            segment_roles = info.get('segment_roles', 'No role description available')
+            segment_count = info.get('segment_count', 1)
+            templates_desc.append(f"- **{name}** ({segment_count} segments): {segment_roles}")
+        
+        templates_text = "\n".join(templates_desc)
+        
+        prompt = f"""You are an expert in infographic title design and linguistic analysis.
+
+**Task**: Analyze the given title and recommend the top {top_k} most suitable templates based on grammatical structure and semantic roles.
+
+**Input Title**: "{title}"
+
+**Available Templates** (with segment role descriptions):
+{templates_text}
+
+**Your Responsibilities**:
+
+1. **Grammatical Analysis**: Parse the title to identify its grammatical components (subject, modifier, qualifier, possessive, prepositional phrase, etc.)
+
+2. **Structural Matching**: Match the title's structure against each template's segment_roles based on:
+   - Number of natural semantic units in the title
+   - Grammatical roles of each unit (modifier, subject, qualifier, etc.)
+   - Visual hierarchy implied by the content
+
+3. **Title Adaptation**: If necessary, **paraphrase or restructure** the title to better fit the template:
+   - Preserve the core meaning
+   - Adjust phrasing to match segment roles
+   - Optimize for visual impact
+
+4. **Segmentation**: For each recommended template, split the title (original or paraphrased) into segments that match the template's segment_roles.
+
+5. **Ranking**: Order recommendations by confidence, considering both grammatical fit and visual effectiveness.
+
+**Output Format** (return ONLY valid JSON, no markdown):
+{{
+  "recommendations": [
+    {{
+      "template_name": "template_name",
+      "title_split": ["segment1", "segment2", ...],
+      "paraphrased_title": "Restructured title if modified, or null if unchanged",
+      "confidence": 0.95,
+      "reasoning": "Brief explanation of grammatical structure match and any paraphrasing done"
+    }}
+  ]
+}}
+
+**Critical Guidelines on Segment Importance**:
+- **PRIMARY importance**: Core subject nouns, key entities, or concrete data/metrics that form the main topic
+  * Examples: "Life Expectancy", "Mobile Phones", "Carbon Emissions", "Europe", "GDP Growth"
+  * These are the focal subjects - the "what" the infographic is about
+  * Will be rendered with larger, bolder, more prominent styling
+  * **KEEP PRIMARY INTACT**: Do not split core noun phrases (e.g., keep "Life Expectancy" together)
+  
+- **SECONDARY importance**: Modifiers, time references, actions, prepositions, and contextual phrases
+  * Examples: 
+    - Time references: "Since 1950", "in 2023", "by 2030"
+    - Actions/verbs: "Gains", "Changes", "Growth"
+    - Prepositions: "by Country", "via Technology", "of All Time"
+    - Quantifiers/modifiers: "Top 10", "Best-Selling", "Average"
+  * These provide context but are NOT the main subject
+  * Will be rendered with smaller, less prominent styling
+
+**Key Principle**: Identify the SUBJECT first (PRIMARY), then treat everything else as decoration (SECONDARY).
+  - Example: "Average Life Expectancy Gains Since 1950" → PRIMARY: "Life Expectancy", SECONDARY: "Average...Gains Since 1950"
+  - Example: "Europe's Best-Selling Car Brands" → PRIMARY: "Car Brands" (or "Europe"), SECONDARY: "Best-Selling"
+
+**Other Guidelines**:
+- Ensure title_split length matches the template's segment count
+- Consider grammatical roles (possessive, modifier, subject, etc.)
+- Paraphrase when it improves fit without changing meaning
+- Prioritize templates with natural grammatical alignment
+- Provide diverse options (avoid similar templates)
+- Order by confidence (highest first)
+- **Identify topic keywords and metrics for PRIMARY segments, context for SECONDARY**
+"""
+        return prompt
+    
+
+
+# Convenience function
+

modules/title_styler/svg_renderer.py

@@ -0,0 +1,1507 @@
+"""
+Infographic Title Generator - SVG Renderer
+Renders title content in SVG format with unified row/column layout
+"""
+
+import xml.etree.ElementTree as ET
+import os
+from typing import List, Tuple, Dict, Optional
+from modules.title_styler.config import (
+    LINE_HEIGHT_RATIO,
+    SVG_PADDING, ALIGNMENT_LEFT, ALIGNMENT_CENTER, ALIGNMENT_RIGHT
+)
+
+from modules.title_styler.font_metrics import (
+    get_font_metrics,
+    measure_text_width,
+    measure_text_bbox,
+)
+
+SINGLE_WEIGHT_FONTS = {'Impact'}
+MEASUREMENT_FALLBACKS_WHEN_UNAVAILABLE = {
+    'Impact': 'Arial',
+    'Bebas Neue': 'Arial',
+    'Comic Sans MS': 'Times New Roman',
+    'Comic Neue': 'Times New Roman',
+    'Brush Script': 'Times New Roman',
+    'Pacifico': 'Times New Roman',
+}
+FONT_FAMILY_FALLBACKS = {
+    'Georgia': 'serif',
+    'Times': 'serif',
+    'Times New Roman': 'serif',
+    'Cambria': 'serif',
+    'Garamond': 'serif',
+    'Book Antiqua': 'serif',
+    'Palatino': 'serif',
+    'Palatino Linotype': 'serif',
+    'Noto Serif': 'serif',
+    'DejaVu Serif': 'serif',
+
+    'Arial': 'sans-serif',
+    'Helvetica': 'sans-serif',
+    'Verdana': 'sans-serif',
+    'Tahoma': 'sans-serif',
+    'Trebuchet MS': 'sans-serif',
+    'Segoe UI': 'sans-serif',
+    'Calibri': 'sans-serif',
+    'Roboto': 'sans-serif',
+    'Open Sans': 'sans-serif',
+    'Montserrat': 'sans-serif',
+    'Oswald': 'sans-serif',
+    'Lato': 'sans-serif',
+    'Source Sans Pro': 'sans-serif',
+    'Noto Sans': 'sans-serif',
+    'DejaVu Sans': 'sans-serif',
+    'Liberation Sans': 'sans-serif',
+    'Impact': 'sans-serif',
+    'Bebas Neue': 'sans-serif',
+
+    'Courier': 'monospace',
+    'Courier New': 'monospace',
+    'Consolas': 'monospace',
+    'Monaco': 'monospace',
+    'Menlo': 'monospace',
+    'DejaVu Sans Mono': 'monospace',
+    'Liberation Mono': 'monospace',
+
+    'Comic Sans MS': 'cursive',
+    'Comic Neue': 'cursive',
+    'Brush Script': 'cursive',
+    'Pacifico': 'cursive',
+}
+
+
+def _font_family_base(font_family):
+    if not font_family:
+        return ''
+    return str(font_family).split(',')[0].strip().strip("'").strip('"')
+
+
+def _font_key(text):
+    return ''.join(ch for ch in str(text).lower() if ch.isalnum())
+
+
+def _font_family_for_measurement(font_family, font_weight, font_style):
+    """Pick the family whose metrics best match the emitted SVG on this host.
+
+    Some named display fonts are often missing on Linux servers. Fontconfig may
+    report Noto Sans for them, while Chrome's SVG renderer falls through to the
+    generic CSS family. In those cases, measuring the requested family makes
+    background pills far wider than the rendered text.
+    """
+    base = _font_family_base(font_family)
+    fallback = MEASUREMENT_FALLBACKS_WHEN_UNAVAILABLE.get(base)
+    if not fallback:
+        return font_family
+
+    resolved_path = get_font_metrics()._fc_match(base, font_weight, font_style)
+    if resolved_path and _font_key(base) in _font_key(os.path.basename(resolved_path)):
+        return font_family
+    return fallback
+
+
+def _normalize_weight_for_output(font_family, font_weight):
+    """Some display fonts (Impact) ship only a Regular face; emitting font-weight=bold
+    causes browsers/Cairo to synthesise fake bold (visibly thicker than intended).
+    Strip the weight for those fonts so the rasterised PNG matches the original face.
+    """
+    base = _font_family_base(font_family)
+    if base in SINGLE_WEIGHT_FONTS:
+        return 'normal'
+    return font_weight
+
+
+def _font_family_for_output(font_family):
+    """Emit an explicit generic fallback so Chrome and PIL land in the same
+    font category when a named family (notably Impact) is unavailable.
+    """
+    if not font_family:
+        return 'Arial, sans-serif'
+    if ',' in str(font_family):
+        return str(font_family)
+    base = _font_family_base(font_family)
+    fallback = FONT_FAMILY_FALLBACKS.get(base)
+    if not fallback:
+        return str(font_family)
+    return f"{font_family}, {fallback}"
+
+
+class LayoutElement:
+    """Represents a layout element with its bounding box"""
+    def __init__(self, text: str, config: dict, width: float, height: float, metrics: dict = None):
+        self.text = text
+        self.config = config
+        self.width = width  # Total width (including background)
+        self.height = height  # Total height (including background)
+        self.metrics = metrics or {}  # Text metrics (text_width, text_height, text_ascent, text_descent)
+        
+        # Bounding box (will be set during layout)
+        self.x1 = 0.0  # Left edge
+        self.y1 = 0.0  # Top edge
+        self.x2 = 0.0  # Right edge (x1 + width)
+        self.y2 = 0.0  # Bottom edge (y1 + height)
+        
+        # Text rendering position
+        self.text_baseline_y = 0.0  # Text baseline Y position
+        self.text_x = 0.0  # Text X position (left edge of text, not including bg padding)
+        self.text_anchor = 'start'
+        
+        # Background rect position (if has background)
+        self.bg_rect_x = 0.0
+        self.bg_rect_y = 0.0
+        self.bg_rect_width = 0.0
+        self.bg_rect_height = 0.0
+    
+    def set_position(self, x: float, y: float):
+        """Set element position (x, y is top-left corner)"""
+        self.x1 = x
+        self.y1 = y
+        self.x2 = x + self.width
+        self.y2 = y + self.height
+
+
+class SVGRenderer:
+    """SVG Renderer class with unified layout system"""
+    
+    def __init__(self):
+        self.svg_padding = SVG_PADDING
+    
+    def measure_element_size(self, text: str, config: dict) -> Tuple[float, float, dict]:
+        """
+        Measure actual element size including background padding
+        
+        Returns:
+            (width, height, metrics) tuple
+            metrics contains: text_width, text_height, text_ascent, text_descent
+        """
+        # Apply text transform first (affects measurement)
+        text_transform = config.get('text_transform', 'none')
+        if text_transform == 'uppercase':
+            text = text.upper()
+        elif text_transform == 'lowercase':
+            text = text.lower()
+        elif text_transform == 'capitalize':
+            text = text.capitalize()
+        
+        font_size = config.get('font_size', 48)
+        font_family = config.get('font_family') or 'Arial'
+        font_weight = _normalize_weight_for_output(
+            font_family,
+            config.get('font_weight') or 'normal',
+        )
+        font_style = config.get('font_style') or 'normal'
+        measurement_family = _font_family_for_measurement(
+            font_family,
+            font_weight,
+            font_style,
+        )
+        
+        # Parse letter_spacing
+        spacing_value = 0
+        ls = config.get('letter_spacing', 0)
+        if isinstance(ls, str) and ls.endswith('em'):
+            spacing_value = float(ls[:-2])
+        elif isinstance(ls, (int, float)):
+            spacing_value = ls
+        
+        # Measure text bbox
+        ascent, descent, text_width, text_height = measure_text_bbox(
+            text,
+            measurement_family,
+            int(font_size),
+            font_weight,
+            font_style,
+            spacing_value,
+        )
+        
+        metrics = {
+            'text_width': text_width,
+            'text_height': text_height,
+            'text_ascent': ascent,
+            'text_descent': descent
+        }
+        
+        # Check if element has background padding
+        bg_config = config.get('background', False)
+        if bg_config and isinstance(bg_config, dict):
+            bg_padding = bg_config.get('padding', 10)
+            # Background expands the bounding box
+            width = text_width + 2 * bg_padding
+            height = text_height + 2 * bg_padding
+        else:
+            width = text_width
+            height = text_height
+        
+        return width, height, metrics
+    
+    def layout_row(self, elements: List[LayoutElement], gap: float = 10.0, 
+                   vertical_align: str = 'baseline') -> Tuple[float, float]:
+        """
+        Layout elements horizontally (row layout)
+        
+        In baseline mode: text baselines align first, then backgrounds adjust around text
+        
+        Args:
+            elements: List of LayoutElement objects
+            gap: Gap between elements
+            vertical_align: Vertical alignment ('baseline', 'center', 'start', 'end')
+        
+        Returns:
+            (total_width, max_height) of the row
+        """
+        if not elements:
+            return 0.0, 0.0
+        
+        current_x = 0.0
+        
+        # For baseline alignment: align text baselines, then adjust backgrounds
+        if vertical_align == 'baseline':
+            # Find the maximum ascent and descent among all elements (text only)
+            max_ascent = 0.0
+            max_descent = 0.0
+            for elem in elements:
+                text_ascent = elem.metrics.get('text_ascent', elem.height * 0.75)
+                text_descent = elem.metrics.get('text_descent', elem.height * 0.25)
+                max_ascent = max(max_ascent, text_ascent)
+                max_descent = max(max_descent, text_descent)
+            
+            # Row height is based on text metrics, but may extend for backgrounds
+            row_content_height = max_ascent + max_descent
+            max_top_extend = 0.0  # Maximum extension above baseline
+            max_bottom_extend = 0.0  # Maximum extension below baseline
+            
+            for elem in elements:
+                text_ascent = elem.metrics.get('text_ascent', elem.height * 0.75)
+                text_descent = elem.metrics.get('text_descent', elem.height * 0.25)
+                text_height = text_ascent + text_descent
+                
+                # Check if element has background
+                bg_config = elem.config.get('background', False)
+                if bg_config and isinstance(bg_config, dict):
+                    bg_padding = bg_config.get('padding', 10)
+                    # Background extends beyond text
+                    top_extend = text_ascent + bg_padding
+                    bottom_extend = text_descent + bg_padding
+                else:
+                    # No background, just text
+                    top_extend = text_ascent
+                    bottom_extend = text_descent
+                
+                max_top_extend = max(max_top_extend, top_extend)
+                max_bottom_extend = max(max_bottom_extend, bottom_extend)
+            
+            # Total row height includes maximum extensions
+            max_height = max_top_extend + max_bottom_extend
+            
+            # Now position each element
+            for i, elem in enumerate(elements):
+                text_ascent = elem.metrics.get('text_ascent', elem.height * 0.75)
+                text_descent = elem.metrics.get('text_descent', elem.height * 0.25)
+                text_width = elem.metrics.get('text_width', elem.width)
+                text_height = text_ascent + text_descent
+                
+                # Text baseline is at max_top_extend from row top
+                # This ensures all text baselines align
+                text_baseline_y = max_top_extend
+                
+                # Check if element has background
+                bg_config = elem.config.get('background', False)
+                if bg_config and isinstance(bg_config, dict):
+                    bg_padding = bg_config.get('padding', 10)
+                    
+                    # Text position (within the element)
+                    elem.text_x = current_x + bg_padding
+                    elem.text_baseline_y = text_baseline_y
+                    
+                    # Background rect: centered vertically around text
+                    elem.bg_rect_x = current_x
+                    elem.bg_rect_y = text_baseline_y - text_ascent - bg_padding
+                    elem.bg_rect_width = text_width + 2 * bg_padding
+                    elem.bg_rect_height = text_height + 2 * bg_padding
+                    
+                    # Element bbox is the background rect
+                    elem.set_position(current_x, elem.bg_rect_y)
+                    
+                    # Move x for next element (based on background width)
+                    current_x += elem.bg_rect_width + gap
+                else:
+                    # No background: element bbox is just the text bbox
+                    elem.text_x = current_x
+                    elem.text_baseline_y = text_baseline_y
+                    
+                    # Element bbox
+                    elem_y1 = text_baseline_y - text_ascent
+                    elem.set_position(current_x, elem_y1)
+                    
+                    # Move x for next element (based on text width)
+                    current_x += text_width + gap
+                
+                # Verify gap (for debugging)
+                if i > 0:
+                    prev_elem = elements[i - 1]
+                    actual_gap = elem.x1 - prev_elem.x2
+                    # Gap should be exactly as specified
+                    assert abs(actual_gap - gap) < 0.01, f"Gap mismatch: expected {gap}, got {actual_gap}"
+        
+        else:
+            # Other alignment modes (center, start, end)
+            max_height = max(elem.height for elem in elements)
+            
+            for i, elem in enumerate(elements):
+                # Calculate y offset based on vertical alignment
+                if vertical_align == 'center':
+                    y_offset = (max_height - elem.height) / 2
+                elif vertical_align == 'start':
+                    y_offset = 0.0
+                elif vertical_align == 'end':
+                    y_offset = max_height - elem.height
+                else:
+                    y_offset = 0.0
+                
+                # Set position
+                elem.set_position(current_x, y_offset)
+                
+                # Text position
+                bg_config = elem.config.get('background', False)
+                if bg_config and isinstance(bg_config, dict):
+                    bg_padding = bg_config.get('padding', 10)
+                    text_ascent = elem.metrics.get('text_ascent', elem.height * 0.75)
+                    text_height = elem.metrics.get('text_height', elem.height)
+                    
+                    elem.text_x = elem.x1 + bg_padding
+                    elem.text_baseline_y = elem.y1 + (elem.height - text_height) / 2 + text_ascent
+                    
+                    elem.bg_rect_x = elem.x1
+                    elem.bg_rect_y = elem.y1
+                    elem.bg_rect_width = elem.width
+                    elem.bg_rect_height = elem.height
+                else:
+                    text_ascent = elem.metrics.get('text_ascent', elem.height * 0.75)
+                    elem.text_x = elem.x1
+                    elem.text_baseline_y = elem.y1 + text_ascent
+                
+                # Verify gap
+                if i > 0:
+                    prev_elem = elements[i - 1]
+                    actual_gap = elem.x1 - prev_elem.x2
+                    assert abs(actual_gap - gap) < 0.01, f"Gap mismatch: expected {gap}, got {actual_gap}"
+                
+                # Move x for next element
+                current_x = elem.x2 + gap
+        
+        # Total width is last element's x2 (no gap after last element)
+        total_width = elements[-1].x2
+        
+        return total_width, max_height
+    
+    def layout_column(self, elements: List[LayoutElement], gap: float = 0.0) -> Tuple[float, float]:
+        """
+        Layout elements vertically (column layout)
+        
+        Args:
+            elements: List of LayoutElement objects
+            gap: Gap between elements
+        
+        Returns:
+            (max_width, total_height) of the column
+        """
+        if not elements:
+            return 0.0, 0.0
+        
+        current_y = 0.0
+        max_width = max(elem.width for elem in elements)
+        
+        for i, elem in enumerate(elements):
+            # Set position: x at 0 (will be adjusted by alignment later), y from current_y
+            elem.set_position(0, current_y)
+            
+            # Text baseline is at y1 + ascent (from top of bbox)
+            font_size = elem.config.get('font_size', 48)
+            elem.baseline_y = elem.y1 + elem.height * 0.75  # Approximate baseline position
+            
+            # Verify gap (for debugging)
+            if i > 0:
+                prev_elem = elements[i - 1]
+                actual_gap = elem.y1 - prev_elem.y2
+                # Gap should be exactly as specified
+                assert abs(actual_gap - gap) < 0.01, f"Gap mismatch: expected {gap}, got {actual_gap}"
+            
+            # Move y for next element: y2 + gap = next y1
+            current_y = elem.y2 + gap
+        
+        # Total height is last element's y2 (no gap after last element)
+        total_height = elements[-1].y2
+        
+        return max_width, total_height
+    
+    def render_svg_unified(self, lines_data: List[str], line_configs: List[dict], 
+                          alignment: str, max_width: Optional[int] = None,
+                          background_color: str = '#FFFFFF') -> Tuple[str, Tuple[int, int]]:
+        """
+        Unified SVG rendering with proper row/column layout
+        
+        Args:
+            lines_data: Text content list
+            line_configs: Line configuration list
+            alignment: Alignment (left/center/right)
+            max_width: Maximum width for text wrapping
+            background_color: Background color
+        
+        Returns:
+            (svg_string, (width, height))
+        """
+        # Check for inline groups
+        inline_groups = []
+        for i, config in enumerate(line_configs):
+            if config.get('inline_group'):
+                group_start, group_end = config['inline_group']
+                if (group_start, group_end) not in inline_groups:
+                    inline_groups.append((group_start, group_end))
+        
+        # Build layout structure: list of rows, each row is a list of elements
+        rows = []
+        processed_indices = set()
+        wrap_group_seq = 0
+        
+        for i, (text, config) in enumerate(zip(lines_data, line_configs)):
+            if i in processed_indices:
+                continue
+            
+            inline_group = config.get('inline_group')
+            if inline_group:
+                # This is part of an inline group - create a row with all group elements
+                group_start, group_end = inline_group
+                row_elements = []
+                
+                for j in range(group_start, group_end + 1):
+                    if j < len(lines_data):
+                        elem_text = lines_data[j]
+                        elem_config = line_configs[j]
+                        width, height, metrics = self.measure_element_size(elem_text, elem_config)
+                        elem = LayoutElement(elem_text, elem_config, width, height, metrics)
+                        row_elements.append(elem)
+                        processed_indices.add(j)
+                
+                # Check if inline row needs wrapping
+                if max_width and row_elements:
+                    total_width = sum(elem.width for elem in row_elements) + 10.0 * (len(row_elements) - 1)
+                    content_max_width = max_width - 2 * self.svg_padding
+                    
+                    # If row exceeds max_width, check for wrappable elements
+                    if total_width > content_max_width:
+                        # Find elements without background (they should wrap)
+                        # Elements with background should NOT wrap
+                        wrappable_indices = []
+                        for idx, elem in enumerate(row_elements):
+                            has_bg = elem.config.get('background') and isinstance(elem.config.get('background'), dict)
+                            if not has_bg:
+                                wrappable_indices.append(idx)
+                        
+                        if wrappable_indices:
+                            # For now, wrap the first wrappable element
+                            # Future: could implement more sophisticated wrapping strategy
+                            wrap_idx = wrappable_indices[0]
+                            elem_to_wrap = row_elements[wrap_idx]
+                            wrap_group_seq += 1
+                            wrap_group_id = f"inline-{i}-{wrap_group_seq}"
+                            
+                            # Calculate line height for wrap gap
+                            font_size = elem_to_wrap.config.get('font_size', 48)
+                            line_height = elem_to_wrap.metrics.get('text_height', font_size)
+                            wrap_gap = min(line_height * 0.25, 10.0)
+                            
+                            # Split the row into multiple rows
+                            # Row 1: elements before wrap point
+                            # Row 2: wrapped element on new line
+                            # Row 3: elements after wrap point (if any)
+                            
+                            if wrap_idx > 0:
+                                # Add elements before wrap point as a row
+                                rows.append(row_elements[:wrap_idx])
+                            
+                            # Add wrapped element as its own row with special gap
+                            wrapped_row = [row_elements[wrap_idx]]
+                            rows.append({
+                                'elements': wrapped_row,
+                                'is_wrapped': True,
+                                'wrap_gap': wrap_gap,
+                                'wrap_group_id': wrap_group_id,
+                            })
+                            
+                            # Add remaining elements as another row if any
+                            if wrap_idx < len(row_elements) - 1:
+                                rows.append(row_elements[wrap_idx + 1:])
+                        else:
+                            # No wrappable elements, just add the row as-is (will overflow)
+                            rows.append(row_elements)
+                    else:
+                        # Fits within width, add as normal row
+                        rows.append(row_elements)
+                else:
+                    # No max_width constraint, add as normal row
+                    rows.append(row_elements)
+            else:
+                # Single element row
+                width, height, metrics = self.measure_element_size(text, config)
+                
+                # Check if element has background color - elements with background should NOT wrap
+                has_background = config.get('background') and isinstance(config.get('background'), dict)
+                
+                # All elements without background should wrap when exceeding max_width
+                # Elements with background should NOT wrap (to preserve the background box)
+                should_wrap = not has_background and max_width
+                
+                if should_wrap:
+                    content_max_width = max_width - 2 * self.svg_padding
+                    
+                    if width > content_max_width:
+                        # Need to wrap text into multiple lines
+                        font_size = config.get('font_size', 48)
+                        font_weight = config.get('font_weight', 'normal')
+                        font_family = config.get('font_family', 'Arial')
+                        letter_spacing = config.get('letter_spacing', 0)
+                        
+                        wrapped_lines = self.wrap_text(
+                            text, max_width, font_size, font_weight, font_family, letter_spacing
+                        )
+                        
+                        if len(wrapped_lines) > 1:
+                            # Create multiple rows for wrapped text
+                            # Calculate line height for wrap gap
+                            line_height = metrics.get('text_height', font_size)
+                            wrap_gap = min(line_height * 0.25, 10.0)
+                            wrap_group_seq += 1
+                            wrap_group_id = f"line-{i}-{wrap_group_seq}"
+                            
+                            for wrap_idx, line_text in enumerate(wrapped_lines):
+                                line_width, line_height, line_metrics = self.measure_element_size(line_text, config)
+                                line_elem = LayoutElement(line_text, config, line_width, line_height, line_metrics)
+                                rows.append({
+                                    'elements': [line_elem],
+                                    'is_wrapped': wrap_idx > 0,
+                                    'wrap_gap': wrap_gap,
+                                    'wrap_group_id': wrap_group_id,
+                                })
+                            
+                            processed_indices.add(i)
+                            continue
+                
+                # No wrapping needed or wrapping not applicable
+                elem = LayoutElement(text, config, width, height, metrics)
+                rows.append([elem])
+                processed_indices.add(i)
+        
+        # Layout each row
+        row_layouts = []
+        for row_data in rows:
+            # Handle both list and dict (dict is for wrapped rows with metadata)
+            if isinstance(row_data, dict):
+                row_elements = row_data['elements']
+                is_wrapped = row_data.get('is_wrapped', False)
+                wrap_gap = row_data.get('wrap_gap', 0)
+                wrap_group_id = row_data.get('wrap_group_id')
+            else:
+                row_elements = row_data
+                is_wrapped = False
+                wrap_gap = 0
+                wrap_group_id = None
+            
+            if len(row_elements) > 1:
+                # Row layout (inline elements) - default to baseline alignment
+                row_width, row_height = self.layout_row(row_elements, gap=10.0, vertical_align='baseline')
+            else:
+                # Single element
+                elem = row_elements[0]
+                text_ascent = elem.metrics.get('text_ascent', elem.height * 0.75)
+                text_descent = elem.metrics.get('text_descent', elem.height * 0.25)
+                text_width = elem.metrics.get('text_width', elem.width)
+                text_height = elem.metrics.get('text_height', elem.height)
+                
+                # Set text position
+                bg_config = elem.config.get('background', False)
+                if bg_config and isinstance(bg_config, dict):
+                    bg_padding = bg_config.get('padding', 10)
+                    
+                    # Text position: padding from left, baseline at ascent + padding from top
+                    elem.text_x = bg_padding
+                    elem.text_baseline_y = bg_padding + text_ascent
+                    
+                    # Background rect: wraps around text with padding
+                    elem.bg_rect_x = 0
+                    elem.bg_rect_y = 0
+                    elem.bg_rect_width = text_width + 2 * bg_padding
+                    elem.bg_rect_height = text_height + 2 * bg_padding
+                    
+                    # Element bbox is the background rect
+                    elem.set_position(0, 0)
+                    row_width, row_height = elem.bg_rect_width, elem.bg_rect_height
+                else:
+                    # No background: just text
+                    elem.text_x = 0
+                    elem.text_baseline_y = text_ascent
+                    elem.set_position(0, 0)
+                    row_width, row_height = text_width, text_height
+            
+            row_layouts.append({
+                'elements': row_elements,
+                'width': row_width,
+                'height': row_height,
+                'is_wrapped': is_wrapped,
+                'wrap_gap': wrap_gap,
+                'wrap_group_id': wrap_group_id,
+            })
+        
+        # Calculate total dimensions
+        max_content_width = max(layout['width'] for layout in row_layouts) if row_layouts else 0
+        
+        # Layout rows vertically with proper gap
+        current_y = self.svg_padding
+        for row_idx, layout in enumerate(row_layouts):
+            # Position row based on alignment
+            row_x_offset = 0
+            if alignment == ALIGNMENT_CENTER:
+                row_x_offset = (max_content_width - layout['width']) / 2
+            elif alignment == ALIGNMENT_RIGHT:
+                row_x_offset = max_content_width - layout['width']
+            
+            # Adjust all elements in this row
+            for elem in layout['elements']:
+                elem.x1 += self.svg_padding + row_x_offset
+                elem.x2 += self.svg_padding + row_x_offset
+                elem.y1 += current_y
+                elem.y2 += current_y
+                elem.text_x += self.svg_padding + row_x_offset
+                elem.text_baseline_y += current_y
+                
+                # Adjust background rect if exists
+                bg_config = elem.config.get('background', False)
+                if bg_config and isinstance(bg_config, dict):
+                    elem.bg_rect_x += self.svg_padding + row_x_offset
+                    elem.bg_rect_y += current_y
+                elif (
+                    len(layout['elements']) == 1
+                    and os.environ.get("TITLE_STYLER_NATIVE_TEXT_ANCHOR", "1") != "0"
+                ):
+                    # For plain single-line rows, use SVG's native anchoring
+                    # instead of converting measured text width into a left
+                    # x-coordinate. PIL and Chrome can still disagree by a few
+                    # pixels for fallback fonts (Comic Sans -> Noto Sans, etc.);
+                    # with text-anchor="middle"/"end" that residual metric
+                    # drift no longer turns into visibly misaligned rows.
+                    if alignment == ALIGNMENT_CENTER:
+                        elem.text_x = self.svg_padding + max_content_width / 2
+                        elem.text_anchor = 'middle'
+                    elif alignment == ALIGNMENT_RIGHT:
+                        elem.text_x = self.svg_padding + max_content_width
+                        elem.text_anchor = 'end'
+            '''
+            # Print row layout info
+            if len(layout['elements']) > 1:
+                # Inline row (multiple elements)
+                print(f"[Row {row_idx}] Inline layout with {len(layout['elements'])} elements:")
+                print(f"  Row bbox: y1={current_y:.1f}, y2={current_y + layout['height']:.1f}")
+                for elem_idx, elem in enumerate(layout['elements']):
+                    bg_config = elem.config.get('background', False)
+                    if bg_config:
+                        print(f"    Element {elem_idx} (with bg): bbox=({elem.x1:.1f}, {elem.y1:.1f}, {elem.x2:.1f}, {elem.y2:.1f})")
+                        print(f"        bg_rect=({elem.bg_rect_x:.1f}, {elem.bg_rect_y:.1f}, w={elem.bg_rect_width:.1f}, h={elem.bg_rect_height:.1f})")
+                        print(f"        text=({elem.text_x:.1f}, baseline={elem.text_baseline_y:.1f})")
+                    else:
+                        print(f"    Element {elem_idx} (no bg): bbox=({elem.x1:.1f}, {elem.y1:.1f}, {elem.x2:.1f}, {elem.y2:.1f})")
+                        print(f"        text=({elem.text_x:.1f}, baseline={elem.text_baseline_y:.1f})")
+            else:
+                # Single element row
+                elem = layout['elements'][0]
+                bg_config = elem.config.get('background', False)
+                if bg_config:
+                    print(f"[Row {row_idx}] Single element (with bg):")
+                    print(f"    bbox=({elem.x1:.1f}, {elem.y1:.1f}, {elem.x2:.1f}, {elem.y2:.1f})")
+                    print(f"    bg_rect=({elem.bg_rect_x:.1f}, {elem.bg_rect_y:.1f}, w={elem.bg_rect_width:.1f}, h={elem.bg_rect_height:.1f})")
+                    print(f"    text=({elem.text_x:.1f}, baseline={elem.text_baseline_y:.1f})")
+                else:
+                    print(f"[Row {row_idx}] Single element (no bg):")
+                    print(f"    bbox=({elem.x1:.1f}, {elem.y1:.1f}, {elem.x2:.1f}, {elem.y2:.1f})")
+                    print(f"    text=({elem.text_x:.1f}, baseline={elem.text_baseline_y:.1f})")
+            '''
+            # Move to next row
+            current_y += layout['height']
+            
+            # Calculate row gap
+            if row_idx < len(row_layouts) - 1:  # Not the last row
+                next_layout = row_layouts[row_idx + 1]
+                same_wrapped_text = (
+                    layout.get('wrap_group_id')
+                    and layout.get('wrap_group_id') == next_layout.get('wrap_group_id')
+                )
+                # Row gap must respect BOTH:
+                #   (a) the current row's own line-height (typographically 1.2-1.5 of
+                #       font_size), and
+                #   (b) the next row's ascender — when a small eyebrow (e.g. 18px) is
+                #       followed by a big headline (e.g. 32px) the next row's
+                #       ascenders must NOT visually crash into this row.
+                # The old `min(curr_font*0.5, 15)` ignored (b) entirely and the 15px
+                # cap throttled even single-line tall titles, leading to the
+                # "eyebrow overlaps main title" Bug A.
+                if layout['elements']:
+                    curr_font = layout['elements'][0].config.get('font_size', 48)
+                else:
+                    curr_font = 16.0
+                if next_layout['elements']:
+                    next_font = max(
+                        (e.config.get('font_size', 48) for e in next_layout['elements']),
+                        default=curr_font,
+                    )
+                else:
+                    next_font = curr_font
+                gap = max(curr_font * 0.4, next_font * 0.5, 10.0)
+                if same_wrapped_text:
+                    # Keep wrapped lines visually compact only when the custom
+                    # wrap gap is still large enough for the rendered font.
+                    gap = max(gap, layout.get('wrap_gap', 5.0))
+                next_role = (
+                    next_layout['elements'][0].config.get('role')
+                    if next_layout['elements']
+                    else None
+                )
+                if next_role == 'description':
+                    gap = max(gap, curr_font * 0.55, next_font * 0.8, 14.0)
+                current_y += gap
+        
+        total_height = current_y + self.svg_padding
+        total_width = max_content_width + 2 * self.svg_padding
+        
+        # Create SVG
+        svg = ET.Element('svg')
+        svg.set('xmlns', 'http://www.w3.org/2000/svg')
+        svg.set('width', str(int(total_width)))
+        svg.set('height', str(int(total_height)))
+        svg.set('viewBox', f"0 0 {int(total_width)} {int(total_height)}")
+        
+        # Render all elements
+        for layout in row_layouts:
+            for elem in layout['elements']:
+                self._render_element(svg, elem)
+        
+        # Convert to string
+        svg_string = ET.tostring(svg, encoding='unicode', method='xml')
+        
+        return svg_string, (int(total_width), int(total_height))
+    
+    def _render_element(self, svg_parent: ET.Element, elem: LayoutElement):
+        """Render a single layout element to SVG"""
+        text = elem.text
+        config = elem.config
+        
+        # Get style properties
+        font_size = config.get('font_size', 48)
+        font_family = config.get('font_family') or 'Arial'
+        font_weight = config.get('font_weight') or 'normal'
+        final_color = config.get('final_color') or '#000000'
+        
+        # Text transform
+        text_transform = config.get('text_transform', 'none')
+        if text_transform == 'uppercase':
+            text = text.upper()
+        elif text_transform == 'lowercase':
+            text = text.lower()
+        elif text_transform == 'capitalize':
+            text = text.capitalize()
+        
+        # Render background if exists
+        bg_config = config.get('background', False)
+        if bg_config and isinstance(bg_config, dict):
+            bg_color = bg_config.get('color', '#000000')
+            bg_radius = bg_config.get('radius', bg_config.get('border_radius', 0))
+            
+            # Use pre-calculated background rect position
+            rect_elem = ET.Element('rect')
+            rect_elem.set('x', str(elem.bg_rect_x))
+            rect_elem.set('y', str(elem.bg_rect_y))
+            rect_elem.set('width', str(elem.bg_rect_width))
+            rect_elem.set('height', str(elem.bg_rect_height))
+            rect_elem.set('fill', bg_color)
+            if bg_radius > 0:
+                rect_elem.set('rx', str(bg_radius))
+                rect_elem.set('ry', str(bg_radius))
+            
+            svg_parent.append(rect_elem)
+        
+        # Create text element using pre-calculated position
+        text_elem = ET.Element('text')
+        text_elem.set('x', str(elem.text_x))
+        text_elem.set('y', str(elem.text_baseline_y))
+        text_elem.set('font-family', _font_family_for_output(font_family))
+        text_elem.set('font-size', f"{font_size}px")
+        text_elem.set('font-weight', _normalize_weight_for_output(font_family, font_weight))
+        text_elem.set('text-anchor', elem.text_anchor)
+        text_elem.set('fill', final_color)
+        
+        # Font style
+        font_style = config.get('font_style')
+        if font_style and font_style != 'normal':
+            text_elem.set('font-style', font_style)
+        
+        # Letter spacing
+        letter_spacing = config.get('letter_spacing')
+        if letter_spacing:
+            if isinstance(letter_spacing, (int, float)) and letter_spacing != 0:
+                text_elem.set('letter-spacing', f"{letter_spacing}em")
+            elif isinstance(letter_spacing, str):
+                text_elem.set('letter-spacing', letter_spacing)
+        
+        text_elem.text = text
+        svg_parent.append(text_elem)
+    
+    def estimate_text_width(self, text, font_size, font_weight='normal', 
+                           font_family='Arial', letter_spacing=0):
+        """
+        Calculate text width using Pillow for precise measurement
+        """
+        # Parse letter_spacing (from '0.1em' to number)
+        spacing_value = 0
+        if isinstance(letter_spacing, str) and letter_spacing.endswith('em'):
+            spacing_value = float(letter_spacing[:-2])
+        elif isinstance(letter_spacing, (int, float)):
+            spacing_value = letter_spacing
+        
+        normalized_weight = _normalize_weight_for_output(font_family, font_weight)
+        measurement_family = _font_family_for_measurement(
+            font_family,
+            normalized_weight,
+            'normal',
+        )
+        width = measure_text_width(
+            text, 
+            measurement_family,
+            int(font_size), 
+            normalized_weight,
+            spacing_value
+        )
+        
+        # Comic Sans MS tends to be wider than calculated, add safety margin
+        if 'Comic Sans' in font_family:
+            width *= 1.08  # Add 8% safety margin for Comic Sans
+        
+        return width
+    
+    def render_line(self, text, line_config, y_position, svg_width, alignment):
+        """
+        渲染单行文本
+        
+        Returns:
+            text_element: SVG text元素
+            line_height: 该行的高度
+        """
+        font_size = line_config.get('font_size', 48)  # 直接使用绝对字号
+        
+        # 计算x位置
+        if alignment == ALIGNMENT_LEFT:
+            x_position = self.svg_padding
+            text_anchor = 'start'
+        elif alignment == ALIGNMENT_RIGHT:
+            x_position = svg_width - self.svg_padding
+            text_anchor = 'end'
+        else:  # center
+            x_position = svg_width / 2
+            text_anchor = 'middle'
+        
+        # 文本转换
+        if line_config.get('text_transform') == 'uppercase':
+            text = text.upper()
+        elif line_config.get('text_transform') == 'lowercase':
+            text = text.lower()
+        elif line_config.get('text_transform') == 'capitalize':
+            text = text.capitalize()
+        
+        elements = []
+        
+        # 添加背景矩形
+        background_config = line_config.get('background', False)
+        if background_config:
+            bg_padding = background_config.get('padding', 10)
+            bg_color = background_config.get('color', '#000000')
+            bg_radius = background_config.get('radius', background_config.get('border_radius', 0))
+            
+            # 测量文本实际bbox（相对于baseline）
+            # Parse letter_spacing
+            spacing_value = 0
+            ls = line_config.get('letter_spacing', 0)
+            if isinstance(ls, str) and ls.endswith('em'):
+                spacing_value = float(ls[:-2])
+            elif isinstance(ls, (int, float)):
+                spacing_value = ls
+            
+            font_family = line_config.get('font_family') or 'Arial'
+            font_weight = _normalize_weight_for_output(
+                font_family,
+                line_config.get('font_weight') or 'normal',
+            )
+            font_style = line_config.get('font_style') or 'normal'
+            measurement_family = _font_family_for_measurement(
+                font_family,
+                font_weight,
+                font_style,
+            )
+            ascent, descent, text_width, text_height = measure_text_bbox(
+                text,
+                measurement_family,
+                int(font_size),
+                font_weight,
+                font_style,
+                spacing_value
+            )
+            
+            # 根据对齐方式计算矩形位置
+            if alignment == ALIGNMENT_LEFT:
+                rect_x = x_position - bg_padding
+            elif alignment == ALIGNMENT_RIGHT:
+                rect_x = x_position - text_width - bg_padding
+            else:  # center
+                rect_x = x_position - text_width/2 - bg_padding
+            
+            # 矩形顶部 = baseline - ascent - padding
+            # 矩形底部 = baseline + descent + padding
+            rect_y = y_position - ascent - bg_padding
+            rect_width = text_width + 2*bg_padding
+            rect_height = text_height + 2*bg_padding
+            
+            # 创建矩形元素
+            rect_elem = ET.Element('rect')
+            rect_elem.set('x', str(rect_x))
+            rect_elem.set('y', str(rect_y))
+            rect_elem.set('width', str(rect_width))
+            rect_elem.set('height', str(rect_height))
+            rect_elem.set('fill', bg_color)
+            if bg_radius > 0:
+                rect_elem.set('rx', str(bg_radius))
+                rect_elem.set('ry', str(bg_radius))
+            
+            elements.append(rect_elem)
+        
+        # 添加阴影效果
+        shadow_config = line_config.get('shadow', False)
+        if shadow_config:
+            shadow_offset = shadow_config.get('offset', (3, 3))
+            shadow_blur = shadow_config.get('blur', 4)
+            shadow_color = shadow_config.get('color', 'rgba(0,0,0,0.3)')
+            
+            shadow_elem = ET.Element('text')
+            shadow_elem.set('x', str(x_position + shadow_offset[0]))
+            shadow_elem.set('y', str(y_position + shadow_offset[1]))
+            shadow_elem.set(
+                'font-family',
+                _font_family_for_output(line_config.get('font_family') or 'Arial'),
+            )
+            shadow_elem.set('font-size', f"{font_size}px")
+            shadow_elem.set('font-weight', _normalize_weight_for_output(
+                line_config.get('font_family'),
+                line_config.get('font_weight') or 'normal',
+            ))
+            shadow_elem.set('text-anchor', text_anchor)
+            shadow_elem.set('fill', shadow_color)
+            
+            if shadow_blur > 0:
+                shadow_elem.set('filter', f'url(#shadow-blur-{shadow_blur})')
+            
+            if line_config.get('font_style'):
+                shadow_elem.set('font-style', line_config['font_style'])
+            if line_config.get('letter_spacing'):
+                ls = line_config['letter_spacing']
+                if isinstance(ls, (int, float)) and ls != 0:
+                    shadow_elem.set('letter-spacing', f"{ls}em")
+                elif isinstance(ls, str):
+                    shadow_elem.set('letter-spacing', ls)
+            
+            shadow_elem.text = text
+            elements.append(shadow_elem)
+        
+        # 创建主text元素
+        text_elem = ET.Element('text')
+        text_elem.set('x', str(x_position))
+        text_elem.set('y', str(y_position))
+        text_elem.set(
+            'font-family',
+            _font_family_for_output(line_config.get('font_family') or 'Arial'),
+        )
+        text_elem.set('font-size', f"{font_size}px")
+        text_elem.set('font-weight', _normalize_weight_for_output(
+            line_config.get('font_family'),
+            line_config.get('font_weight') or 'normal',
+        ))
+        text_elem.set('text-anchor', text_anchor)
+        
+        # 空心字效果
+        if line_config.get('outline', False):
+            outline_width = line_config.get('outline_width', 2)
+            text_elem.set('fill', 'none')
+            text_elem.set('stroke', line_config.get('final_color') or '#000000')
+            text_elem.set('stroke-width', str(outline_width))
+        else:
+            text_elem.set('fill', line_config.get('final_color') or '#000000')
+        
+        # 字体样式
+        if line_config.get('font_style'):
+            text_elem.set('font-style', line_config['font_style'])
+        
+        # 字母间距
+        if line_config.get('letter_spacing'):
+            ls = line_config['letter_spacing']
+            if isinstance(ls, (int, float)) and ls != 0:
+                text_elem.set('letter-spacing', f"{ls}em")
+            elif isinstance(ls, str):
+                text_elem.set('letter-spacing', ls)
+        
+        # 文本装饰（下划线、删除线）
+        decorations = []
+        if line_config.get('underline', False):
+            decorations.append('underline')
+        if line_config.get('strikethrough', False):
+            decorations.append('line-through')
+        
+        if decorations:
+            text_elem.set('text-decoration', ' '.join(decorations))
+        
+        text_elem.text = text
+        elements.append(text_elem)
+        
+        # 计算line_height：如果有背景，需要加上padding
+        line_height = font_size * LINE_HEIGHT_RATIO
+        if background_config:
+            bg_padding = background_config.get('padding', 10)
+            line_height = max(line_height, font_size + 2*bg_padding)
+        
+        return elements, line_height
+    
+    def wrap_text(self, text, max_width, font_size, font_weight, font_family, letter_spacing):
+        """
+        将文本分成多行以适应最大宽度。
+
+        采用「行数最少 + 行宽平衡」两步法：
+          1) 贪心算出在 max_width 下需要的最少行数 N；
+          2) 二分搜索最小的 target_width <= max_width，使得贪心仍能在 N 行内装下；
+             以这个 target 再做一次贪心打包，让各行宽度尽量接近，避免出现
+             「长 / 短 / 短」这种典型不平衡（First-Fit 贪心的经典缺陷）。
+
+        Returns:
+            lines: 分割后的行列表
+        """
+        words = text.split()
+        if not words:
+            return [text]
+
+        content_max = max_width - 2 * self.svg_padding
+        if content_max <= 0:
+            return [text]
+
+        # 预测每个 word 的宽度，避免反复调用 Pillow。
+        word_widths = [
+            self.estimate_text_width(w, font_size, font_weight, font_family, letter_spacing)
+            for w in words
+        ]
+        space_width = self.estimate_text_width(
+            ' ', font_size, font_weight, font_family, letter_spacing
+        )
+
+        def greedy_pack(target):
+            """尝试用 First-Fit 把 words 装到行宽 <= target 的若干行。
+            返回 (行数, [(start_idx, end_idx_exclusive), ...])；若有单 word
+            超过 target 也算 1 行（与原行为一致：单词过长直接成一行）。"""
+            n_lines = 1
+            cur_w = 0.0
+            cur_start = 0
+            packs = []
+            for i, ww in enumerate(word_widths):
+                extra = ww if cur_w == 0 else (space_width + ww)
+                if cur_w + extra <= target or cur_w == 0:
+                    cur_w += extra
+                else:
+                    packs.append((cur_start, i))
+                    n_lines += 1
+                    cur_start = i
+                    cur_w = ww
+            packs.append((cur_start, len(words)))
+            return n_lines, packs
+
+        # 第 1 步：用原始 max_width 下的最少行数 N。
+        n_lines, _ = greedy_pack(content_max)
+        if n_lines <= 1:
+            return [' '.join(words)]
+
+        # 第 2 步：二分最小化 target_width，使贪心仍能装进 N 行。
+        # 下界必须能容下最长的单 word，否则会无谓增加行数。
+        lo = max(word_widths)
+        hi = content_max
+        # target 不能小于 lo，否则单词放不下
+        if lo >= hi:
+            target = hi
+        else:
+            # 浮点二分：精度 0.5 px 足够，文本宽度本身也是近似值。
+            for _ in range(40):  # log2(content_max / 0.5) 上限充裕
+                if hi - lo < 0.5:
+                    break
+                mid = (lo + hi) / 2
+                fit_n, _ = greedy_pack(mid)
+                if fit_n <= n_lines:
+                    hi = mid
+                else:
+                    lo = mid
+            target = hi
+
+        # 第 3 步：用平衡 target 重新打包。
+        _, packs = greedy_pack(target)
+        lines = [' '.join(words[s:e]) for s, e in packs]
+        return lines if lines else [text]
+    
+    def calculate_svg_dimensions(self, lines_data, line_configs, alignment, max_width=None):
+        """
+        计算SVG总尺寸
+        
+        Args:
+            lines_data: 文本内容列表
+            line_configs: 行配置列表
+            alignment: 对齐方式
+            max_width: 最大宽度限制
+        
+        Returns:
+            (width, height): SVG尺寸
+            wrapped_lines: 考虑换行后的实际行数据
+        """
+        # 单列布局
+        max_width_content = 0
+        total_height = self.svg_padding
+        wrapped_lines = []  # 存储实际渲染的行（包括换行后的）
+        
+        for text, config in zip(lines_data, line_configs):
+            font_size = config.get('font_size', 48)
+            
+            # 处理换行
+            if config.get('allow_wrap') and max_width:
+                text_lines = self.wrap_text(
+                    text, max_width, font_size, 
+                    config.get('font_weight', 'normal'),
+                    config.get('font_family', 'Arial'),
+                    config.get('letter_spacing', 0)
+                )
+            else:
+                text_lines = [text]
+            
+            # 为每个实际行添加配置
+            for line_text in text_lines:
+                text_width = self.estimate_text_width(
+                    line_text, 
+                    font_size, 
+                    config.get('font_weight', 'normal'),
+                    config.get('font_family', 'Arial'),
+                    config.get('letter_spacing', 0)
+                )
+                max_width_content = max(max_width_content, text_width)
+                total_height += font_size * LINE_HEIGHT_RATIO
+                wrapped_lines.append((line_text, config))
+        
+        total_height += self.svg_padding
+        total_width = max_width_content + 2 * self.svg_padding
+        
+        # Add extra margin for Comic Sans fonts to prevent truncation
+        has_comic_sans = any(
+            config.get('font_family', '').startswith('Comic Sans') 
+            for _, config in wrapped_lines
+        )
+        if has_comic_sans:
+            total_width += 20  # Extra 20px safety margin for Comic Sans
+        
+        # Always use actual content width to avoid text truncation
+        # max_width is only used to determine when to wrap text, not to limit SVG size
+        
+        return total_width, total_height, wrapped_lines
+    
+    def _calculate_element_bbox(self, element):
+        """
+        Calculate bounding box for an SVG element (text, rect, or g)
+        
+        Returns:
+            (min_x, min_y, max_x, max_y) or None
+        """
+        tag = element.tag
+        
+        if tag == 'rect':
+            # For rect: x, y, width, height are explicit
+            # Skip background rect with percentage values
+            width_str = element.get('width', '0')
+            height_str = element.get('height', '0')
+            if '%' in width_str or '%' in height_str:
+                return None  # Skip percentage-based rects (background)
+            
+            x = float(element.get('x', 0))
+            y = float(element.get('y', 0))
+            width = float(width_str)
+            height = float(height_str)
+            
+            # Consider border-radius (rx/ry) if present - doesn't change bbox
+            return (x, y, x + width, y + height)
+        
+        elif tag == 'text':
+            # For text: need to measure text dimensions
+            text_content = element.text or ''
+            if not text_content:
+                return None
+            
+            x = float(element.get('x', 0))
+            y = float(element.get('y', 0))
+            font_family = element.get('font-family', 'Arial')
+            font_size = int(element.get('font-size', '16px').replace('px', ''))
+            font_weight = element.get('font-weight', 'normal')
+            text_anchor = element.get('text-anchor', 'start')
+            
+            # Parse letter-spacing from SVG element
+            letter_spacing_str = element.get('letter-spacing', '0')
+            letter_spacing = 0
+            if letter_spacing_str and letter_spacing_str != '0':
+                if letter_spacing_str.endswith('em'):
+                    letter_spacing = float(letter_spacing_str[:-2])
+            
+            # Measure text width and height (including letter-spacing)
+            text_width = self.estimate_text_width(
+                text_content, font_size, font_weight, font_family, letter_spacing
+            )
+            
+            # Consider stroke width for outline text
+            stroke_width = 0
+            if element.get('stroke'):
+                stroke_width_str = element.get('stroke-width', '0')
+                try:
+                    stroke_width = float(stroke_width_str)
+                except:
+                    stroke_width = 0
+            
+            # Text height with stroke consideration
+            text_height = font_size + stroke_width
+            
+            # Calculate bbox based on text-anchor
+            if text_anchor == 'start':
+                min_x = x - stroke_width / 2
+                max_x = x + text_width + stroke_width / 2
+            elif text_anchor == 'middle':
+                min_x = x - text_width / 2 - stroke_width / 2
+                max_x = x + text_width / 2 + stroke_width / 2
+            elif text_anchor == 'end':
+                min_x = x - text_width - stroke_width / 2
+                max_x = x + stroke_width / 2
+            else:
+                min_x = x - stroke_width / 2
+                max_x = x + text_width + stroke_width / 2
+            
+            # Y coordinates: y is baseline, text extends above
+            # Add extra space for ascenders and stroke
+            min_y = y - text_height - stroke_width / 2
+            max_y = y + stroke_width / 2
+            
+            return (min_x, min_y, max_x, max_y)
+        
+        return None
+    
+    def _adjust_svg_dimensions_to_content(self, svg_element):
+        """
+        Adjust SVG width/height to fit all content without clipping, ensuring uniform padding
+        
+        Args:
+            svg_element: SVG root element
+        
+        Returns:
+            (adjusted_width, adjusted_height)
+        """
+        # Collect all bounding boxes
+        bboxes = []
+        
+        for child in svg_element:
+            bbox = self._calculate_element_bbox(child)
+            if bbox:
+                bboxes.append(bbox)
+        
+        if not bboxes:
+            # No content, keep original dimensions
+            width = int(svg_element.get('width', 100))
+            height = int(svg_element.get('height', 100))
+            return (width, height)
+        
+        # Calculate overall bounding box of all visible content
+        min_x = min(bbox[0] for bbox in bboxes)
+        min_y = min(bbox[1] for bbox in bboxes)
+        max_x = max(bbox[2] for bbox in bboxes)
+        max_y = max(bbox[3] for bbox in bboxes)
+        
+        # Target padding
+        padding = self.svg_padding
+        
+        # Calculate required dimensions to maintain uniform padding on all sides
+        # Left padding: ensure min_x >= padding (shift if needed)
+        # Right padding: ensure max_x + padding is within bounds
+        # Top padding: ensure min_y >= padding (shift if needed)
+        # Bottom padding: ensure max_y + padding is within bounds
+        
+        # Calculate content dimensions
+        content_width = max_x - min_x
+        content_height = max_y - min_y
+        
+        # Required SVG dimensions = content + padding on both sides
+        required_width = content_width + 2 * padding
+        required_height = content_height + 2 * padding
+        
+        # Get current dimensions (from initial calculation)
+        current_width = int(svg_element.get('width', 100))
+        current_height = int(svg_element.get('height', 100))
+        
+        # Use maximum of current and required to ensure all content fits
+        final_width = max(current_width, int(required_width))
+        final_height = max(current_height, int(required_height))
+        
+        # Check if content is positioned correctly (starts at padding)
+        # If min_x or min_y is less than padding, we need to shift content or increase dimensions
+        if min_x < padding:
+            # Content extends beyond left padding - increase width
+            extra_width = padding - min_x
+            final_width += int(extra_width)
+        
+        if min_y < padding:
+            # Content extends beyond top padding - increase height
+            extra_height = padding - min_y
+            final_height += int(extra_height)
+        
+        # Ensure right and bottom padding
+        if max_x + padding > final_width:
+            final_width = int(max_x + padding)
+        
+        if max_y + padding > final_height:
+            final_height = int(max_y + padding)
+        
+        return (final_width, final_height)
+    
+    def render_svg(self, lines_data, line_configs, alignment, max_width=None, background_color='#FFFFFF', inline=False):
+        """
+        渲染完整的SVG (uses unified layout system)
+        
+        Args:
+            lines_data: 文本内容列表
+            line_configs: 行配置列表
+            alignment: 对齐方式
+            max_width: 最大宽度限制（可选）
+            background_color: 背景颜色
+            inline: If True, render segments horizontally on same line instead of stacking
+        
+        Returns:
+            svg_string: SVG XML字符串
+            dimensions: (width, height)
+        """
+        # Use unified layout system
+        return self.render_svg_unified(lines_data, line_configs, alignment, max_width, background_color)
+    
+    def _render_inline_segment(self, text, line_config, y_position, x_position, alignment):
+        """
+        Render a single segment for inline layout (horizontal positioning)
+        
+        Args:
+            text: Text content
+            line_config: Line configuration
+            y_position: Y position (baseline)
+            x_position: X position (left edge)
+            alignment: Alignment (ignored for inline, always uses start)
+        
+        Returns:
+            (elements, line_height)
+        """
+        font_size = line_config['font_size']
+        line_height = font_size * LINE_HEIGHT_RATIO
+        
+        elements = []
+        
+        # Add background rectangle if exists
+        background_config = line_config.get('background', False)
+        if background_config:
+            bg_padding = background_config.get('padding', 10)
+            bg_color = background_config.get('color', '#000000')
+            bg_radius = background_config.get('radius', background_config.get('border_radius', 0))
+            
+            # 测量文本实际bbox（相对于baseline）
+            spacing_value = 0
+            ls = line_config.get('letter_spacing', 0)
+            if isinstance(ls, str) and ls.endswith('em'):
+                spacing_value = float(ls[:-2])
+            elif isinstance(ls, (int, float)):
+                spacing_value = ls
+            
+            font_family = line_config.get('font_family') or 'Arial'
+            font_weight = _normalize_weight_for_output(
+                font_family,
+                line_config.get('font_weight') or 'normal',
+            )
+            font_style = line_config.get('font_style') or 'normal'
+            measurement_family = _font_family_for_measurement(
+                font_family,
+                font_weight,
+                font_style,
+            )
+            ascent, descent, text_width, text_height = measure_text_bbox(
+                text,
+                measurement_family,
+                int(font_size),
+                font_weight,
+                font_style,
+                spacing_value
+            )
+            
+            rect_x = x_position - bg_padding
+            rect_y = y_position - ascent - bg_padding
+            rect_width = text_width + 2*bg_padding
+            rect_height = text_height + 2*bg_padding
+            
+            rect_elem = ET.Element('rect')
+            rect_elem.set('x', str(rect_x))
+            rect_elem.set('y', str(rect_y))
+            rect_elem.set('width', str(rect_width))
+            rect_elem.set('height', str(rect_height))
+            rect_elem.set('fill', bg_color)
+            if bg_radius > 0:
+                rect_elem.set('rx', str(bg_radius))
+                rect_elem.set('ry', str(bg_radius))
+            
+            elements.append(rect_elem)
+        
+        # Create text element
+        text_elem = ET.Element('text')
+        text_elem.set('x', str(x_position))
+        text_elem.set('y', str(y_position))
+        text_elem.set(
+            'font-family',
+            _font_family_for_output(line_config.get('font_family') or 'Arial'),
+        )
+        text_elem.set('font-size', f"{font_size}px")
+        text_elem.set('font-weight', _normalize_weight_for_output(
+            line_config.get('font_family'),
+            line_config.get('font_weight') or 'normal',
+        ))
+        text_elem.set('text-anchor', 'start')  # Always start for inline
+        text_elem.set('fill', line_config.get('final_color') or '#000000')
+        
+        # Font style (only set if not None and not 'normal')
+        font_style = line_config.get('font_style')
+        if font_style and font_style != 'normal':
+            text_elem.set('font-style', font_style)
+        
+        # Letter spacing
+        if line_config.get('letter_spacing'):
+            ls = line_config['letter_spacing']
+            if isinstance(ls, (int, float)) and ls != 0:
+                text_elem.set('letter-spacing', f"{ls}em")
+            elif isinstance(ls, str):
+                text_elem.set('letter-spacing', ls)
+        
+        text_elem.text = text
+        elements.append(text_elem)
+        
+        # 计算line_height：如果有背景，需要加上padding
+        line_height = font_size * LINE_HEIGHT_RATIO
+        if background_config:
+            bg_padding = background_config.get('padding', 10)
+            line_height = max(line_height, font_size + 2*bg_padding)
+        
+        return elements, line_height

modules/title_styler/template_schema.json

@@ -0,0 +1,359 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "InfographicLayout",
+  "type": "object",
+  "description": "Infographic layout description with theme and node tree",
+  "properties": {
+    "theme": {
+      "type": "object",
+      "description": "Global design tokens (colors, typography, etc.)",
+      "properties": {
+        "colors": {
+          "type": "object",
+          "description": "Color tokens used across the infographic",
+          "patternProperties": {
+            "^[a-zA-Z_][a-zA-Z0-9_]*$": {
+              "type": "string",
+              "description": "Color value (e.g. hex, rgba, or implementation-defined token)"
+            }
+          },
+          "additionalProperties": false
+        },
+        "typography": {
+          "type": "object",
+          "description": "Typography style tokens (e.g. H1, H2, Body)",
+          "patternProperties": {
+            "^[a-zA-Z_][a-zA-Z0-9_]*$": {
+              "type": "object",
+              "properties": {
+                "font": {
+                  "type": "string",
+                  "description": "Font family name (and optionally style info, implementation-defined)"
+                },
+                "size": {
+                  "type": "number",
+                  "description": "Font size, typically in px"
+                },
+                "weight": {
+                  "type": "string",
+                  "description": "Font weight (e.g. 'normal', 'bold', '600')"
+                }
+              },
+              "required": ["font", "size"],
+              "additionalProperties": true
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "root": {
+      "$ref": "#/definitions/Node",
+      "description": "Root node of the infographic layout tree"
+    }
+  },
+  "required": ["root"],
+  "additionalProperties": false,
+
+  "definitions": {
+    "Node": {
+      "oneOf": [
+        { "$ref": "#/definitions/Group" },
+        { "$ref": "#/definitions/Stack" },
+        { "$ref": "#/definitions/Text" },
+        { "$ref": "#/definitions/Image" },
+        { "$ref": "#/definitions/Chart" },
+        { "$ref": "#/definitions/Shape" }
+      ]
+    },
+
+    "Padding": {
+      "oneOf": [
+        {
+          "type": "number",
+          "description": "Uniform padding on all sides (px)"
+        },
+        {
+          "type": "object",
+          "description": "Per-side padding (px)",
+          "properties": {
+            "top": { "type": "number" },
+            "right": { "type": "number" },
+            "bottom": { "type": "number" },
+            "left": { "type": "number" }
+          },
+          "required": ["top", "right", "bottom", "left"],
+          "additionalProperties": false
+        }
+      ]
+    },
+
+    "OverlapConstraint": {
+      "type": "object",
+      "description": "Relative overlap constraint between two children in a STACK",
+      "properties": {
+        "sourceId": {
+          "type": "string",
+          "description": "ID of the element being constrained"
+        },
+        "targetId": {
+          "type": "string",
+          "description": "ID of the reference element"
+        },
+        "type": {
+          "type": "string",
+          "enum": ["FULLY_INSIDE", "NON_OVERLAP", "PARTIALLY_OVERLAP"],
+          "description": "Overlap constraint type"
+        },
+        "minDistance": {
+          "type": "number",
+          "description": "Minimum distance in pixels when type is NON_OVERLAP"
+        },
+        "overlapPercentage": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 100,
+          "description": "Required overlap percentage (0–100) when type is PARTIALLY_OVERLAP"
+        }
+      },
+      "required": ["sourceId", "targetId", "type"],
+      "additionalProperties": false
+    },
+
+    "AlignmentConstraint": {
+      "type": "object",
+      "description": "Simple pairwise alignment constraint between two children in a STACK",
+      "properties": {
+        "sourceId": {
+          "type": "string",
+          "description": "ID of the element being aligned"
+        },
+        "targetId": {
+          "type": "string",
+          "description": "ID of the reference element to align to"
+        },
+        "type": {
+          "type": "string",
+          "enum": ["TOP", "BOTTOM", "LEFT", "RIGHT"],
+          "description": "Which edge of source should align to the same edge of target"
+        }
+      },
+      "required": ["sourceId", "targetId", "type"],
+      "additionalProperties": false
+    },
+
+    "Group": {
+      "type": "object",
+      "description": "Flow layout container (row/column)",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique identifier for the group element"
+        },
+        "type": {
+          "const": "GROUP"
+        },
+        "direction": {
+          "type": "string",
+          "enum": ["ROW", "COLUMN"],
+          "description": "Layout direction of children"
+        },
+        "alignment": {
+          "type": "object",
+          "description": "Main-axis and cross-axis alignment (simplified)",
+          "properties": {
+            "main": {
+              "type": "string",
+              "enum": ["START", "CENTER", "END"],
+              "description": "Alignment along the layout direction"
+            },
+            "cross": {
+              "type": "string",
+              "enum": ["START", "CENTER", "END", "STRETCH"],
+              "description": "Alignment perpendicular to the layout direction"
+            }
+          },
+          "required": ["main", "cross"],
+          "additionalProperties": false
+        },
+        "spacing": {
+          "type": "number",
+          "description": "Spacing between children (px)"
+        },
+        "padding": {
+          "$ref": "#/definitions/Padding"
+        },
+        "children": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/Node" }
+        }
+      },
+      "required": ["id", "type", "direction", "alignment", "children"],
+      "additionalProperties": false
+    },
+
+    "Stack": {
+      "type": "object",
+      "description": "Stacked layout (children layered in z-order, like a Stack/ZStack)",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique identifier for the stack element"
+        },
+        "type": {
+          "const": "STACK"
+        },
+        "alignment": {
+          "type": "string",
+          "enum": [
+            "TOP_LEFT", "TOP_CENTER", "TOP_RIGHT",
+            "CENTER_LEFT", "CENTER", "CENTER_RIGHT",
+            "BOTTOM_LEFT", "BOTTOM_CENTER", "BOTTOM_RIGHT"
+          ],
+          "description": "Default alignment of children within the stack bounds"
+        },
+        "children": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/Node" }
+        },
+        "overlapConstraints": {
+          "type": "array",
+          "description": "Overlap constraints between children in this stack",
+          "items": { "$ref": "#/definitions/OverlapConstraint" }
+        },
+        "alignmentConstraints": {
+          "type": "array",
+          "description": "Pairwise alignment constraints between children in this stack",
+          "items": { "$ref": "#/definitions/AlignmentConstraint" }
+        }
+      },
+      "required": ["id", "type", "alignment", "children"],
+      "additionalProperties": false
+    },
+
+    "Chart": {
+      "type": "object",
+      "description": "Chart placeholder node (semantics handled outside this grammar)",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique identifier for the chart element"
+        },
+        "type": {
+          "const": "CHART"
+        },
+        "width": {
+          "type": "number",
+          "description": "Chart width (px)"
+        },
+        "height": {
+          "type": "number",
+          "description": "Chart height (px)"
+        }
+      },
+      "required": ["id", "type", "width", "height"],
+      "additionalProperties": false
+    },
+
+    "Text": {
+      "type": "object",
+      "description": "Text node; visual style is driven mainly by theme.typography + role",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique identifier for the text element"
+        },
+        "type": {
+          "const": "TEXT"
+        },
+        "content": {
+          "type": "string",
+          "description": "Text content"
+        },
+        "role": {
+          "type": "string",
+          "enum": [
+            "TITLE_PRIMARY",
+            "TITLE_NUMBER",
+            "TITLE_CONTEXT",
+            "SUBTITLE",
+            "CAPTION"
+          ],
+          "description": "Semantic role of the text, used to map to typography tokens"
+        },
+        "color": {
+          "type": "string",
+          "description": "Optional color override; if omitted, renderer may use theme colors based on role"
+        },
+        "maxLines": {
+          "type": "integer",
+          "description": "Maximum number of lines to render (truncation behavior is implementation-defined)"
+        }
+      },
+      "required": ["id", "type", "content", "role"],
+      "additionalProperties": false
+    },
+
+    "Image": {
+      "type": "object",
+      "description": "Image node",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique identifier for the image element"
+        },
+        "type": {
+          "const": "IMAGE"
+        },
+        "src": {
+          "type": "string",
+          "description": "Image source (URL or asset identifier)"
+        },
+        "width": {
+          "type": "number",
+          "description": "Image width (px)"
+        },
+        "height": {
+          "type": "number",
+          "description": "Image height (px)"
+        },
+        "fit": {
+          "type": "string",
+          "enum": ["COVER", "CONTAIN", "FILL"],
+          "description": "How the image fits into its bounding box"
+        },
+        "radius": {
+          "type": "number",
+          "description": "Corner radius for rounded images (px)"
+        }
+      },
+      "required": ["id", "type", "src"],
+      "additionalProperties": false
+    },
+
+    "Shape": {
+      "type": "object",
+      "description": "Basic geometric or path-based shape with free-form attributes",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique identifier for the shape element"
+        },
+        "type": {
+          "type": "string",
+          "enum": ["RECT", "CIRCLE", "PATH"],
+          "description": "Shape type"
+        },
+        "attrs": {
+          "type": "object",
+          "description": "Implementation-defined attributes for the shape (e.g. width, height, radius, path, color, strokeColor, strokeWidth, etc.)",
+          "additionalProperties": true
+        }
+      },
+      "required": ["id", "type"],
+      "additionalProperties": false
+    }
+  }
+}

modules/title_styler/templates.json

@@ -0,0 +1,2010 @@
+{
+  "templates": [
+    {
+      "name": "three_line_emphasis",
+      "description": "Single-line emphasis: fully inline, bold colored highlight for main phrase",
+      "style": "normal",
+      "layout_type": "single_column",
+      "alignment": "left",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 20px",
+              "color": "#000000",
+              "importance": "secondary",
+              "id": 1,
+              "allow_wrap": false
+            },
+            {
+              "font": "Arial 28px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "effects": {
+                "shadow": {
+                  "blur": 4,
+                  "offset": [
+                    3,
+                    3
+                  ],
+                  "color": "rgba(0,0,0,0.3)"
+                }
+              },
+              "id": 2,
+              "allow_wrap": false
+            },
+            {
+              "font": "Arial 20px",
+              "color": "#000000",
+              "importance": "secondary",
+              "id": 3,
+              "allow_wrap": false
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 17px italic",
+          "color": "#333333",
+          "allow_wrap": true
+        }
+      },
+      "segment_roles": "$S1 is an introductory modifier or context setter, $S2 is the focal subject (emphasized and prominent), $S3 is a qualifier or concluding phrase.",
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "two_line_hierarchy",
+      "description": "Two-line hierarchy: secondary prefix + PRIMARY main title",
+      "segment_roles": "$S1 is a categorical prefix or contextual modifier, $S2 is the primary subject or topic.",
+      "style": "professional",
+      "layout_type": "single_column",
+      "alignment": "left",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 19px",
+              "color": "#FFFFFF",
+              "importance": "secondary",
+              "text_transform": "uppercase",
+              "letter_spacing": 0.1,
+              "id": 1,
+              "allow_wrap": true
+            },
+            {
+              "font": "Arial 34px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "id": 2,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 17px",
+          "color": "#CCCCCC",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "lithium_countries",
+      "description": "World's Largest style: elegant italic prefix + bold main title",
+      "segment_roles": "$S1 is a superlative or descriptive qualifier, $S2 is the main noun phrase or topic.",
+      "style": "professional",
+      "layout_type": "single_column",
+      "alignment": "left",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Georgia 23px italic",
+              "color": "#333333",
+              "importance": "secondary",
+              "id": 1,
+              "allow_wrap": false
+            },
+            {
+              "font": "Arial 28px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "id": 2,
+              "allow_wrap": false
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 17px",
+          "color": "#666666",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "european_adults",
+      "description": "Two-line stacked: small serif prefix + large sans-serif main title",
+      "style": "professional",
+      "layout_type": "single_column",
+      "alignment": "center",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Georgia 20px",
+              "color": "#8B7355",
+              "importance": "secondary",
+              "id": 1,
+              "allow_wrap": false
+            },
+            {
+              "font": "Arial 27px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "id": 2,
+              "allow_wrap": false
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 16px",
+          "color": "#666666",
+          "allow_wrap": true
+        }
+      },
+      "segment_roles": "$S1 is a demographic or geographic qualifier, $S2 is the subject matter or metric.",
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "millionaires_green",
+      "description": "Green theme with background: small text on green + large white text on black background",
+      "segment_roles": "$S1 is a prepositional phrase or categorical context, $S2 is the emphasized core subject (with background, less than 3 words).",
+      "style": "professional",
+      "layout_type": "single_column",
+      "alignment": "center",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 21px bold",
+              "color": "#2C5F2D",
+              "importance": "secondary",
+              "id": 1,
+              "allow_wrap": false
+            },
+            {
+              "font": "Arial 30px bold",
+              "color": "#ffffff",
+              "importance": "primary",
+              "effects": {
+                "background": {
+                  "color": "#1A1A1A",
+                  "padding": 8,
+                  "border_radius": 10
+                }
+              },
+              "id": 2,
+              "allow_wrap": false
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 17px",
+          "color": "#555555",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "america_valuable",
+      "description": "America's Most Valuable style: small prefix + 2 lines of huge text + small suffix",
+      "style": "professional",
+      "layout_type": "single_column",
+      "alignment": "left",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 20px",
+              "color": "#999999",
+              "importance": "secondary",
+              "text_transform": "uppercase",
+              "id": 1,
+              "allow_wrap": false
+            },
+            {
+              "font": "Arial 34px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "text_transform": "uppercase",
+              "id": 2,
+              "allow_wrap": false
+            },
+            {
+              "font": "Arial 34px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "text_transform": "uppercase",
+              "id": 3,
+              "allow_wrap": false
+            },
+            {
+              "font": "Arial 19px bold",
+              "color": "#000000",
+              "importance": "secondary",
+              "text_transform": "uppercase",
+              "id": 4,
+              "allow_wrap": false
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 17px",
+          "color": "#666666",
+          "allow_wrap": true
+        }
+      },
+      "segment_roles": "$S1 is a possessive or geographic prefix, $S2 is the main subject (with visual emphasis through background).",
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "dentist_question",
+      "description": "Question style: medium setup + huge question + small caption",
+      "style": "normal",
+      "layout_type": "single_column",
+      "alignment": "left",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 24px bold",
+              "color": "#2C5F4D",
+              "importance": "secondary",
+              "text_transform": "uppercase",
+              "id": 1,
+              "allow_wrap": false
+            },
+            {
+              "font": "Arial 40px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "text_transform": "uppercase",
+              "id": 2,
+              "allow_wrap": false
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 18px bold",
+          "color": "#000000",
+          "allow_wrap": true,
+          "text_transform": "uppercase"
+        }
+      },
+      "segment_roles": "$S1 is an interrogative phrase or question prefix, $S2 is the specific subject being questioned.",
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "infant_mortality",
+      "description": "Dark background style: small text with white background + large white text",
+      "style": "professional",
+      "layout_type": "single_column",
+      "alignment": "left",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 21px",
+              "color": "#000000",
+              "importance": "secondary",
+              "effects": {
+                "background": {
+                  "color": "#FFFFFF",
+                  "padding": 8,
+                  "border_radius": 0
+                }
+              },
+              "id": 1,
+              "allow_wrap": false
+            },
+            {
+              "font": "Arial 31px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "id": 2,
+              "allow_wrap": false
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 17px",
+          "color": "#CCCCCC",
+          "allow_wrap": true
+        }
+      },
+      "segment_roles": "$S1 is a categorical tag (with background, less than 3 words), $S2 is the emphasized main metric or topic.",
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "financial_centers",
+      "description": "Three-line with colored background: black + primary background + black",
+      "style": "professional",
+      "layout_type": "single_column",
+      "alignment": "left",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 28px bold",
+              "color": "#000000",
+              "importance": "secondary",
+              "id": 1,
+              "allow_wrap": false
+            },
+            {
+              "font": "Arial 28px bold",
+              "color": "#FFFFFF",
+              "importance": "primary",
+              "effects": {
+                "background": {
+                  "color": "primary_color",
+                  "padding": 12,
+                  "border_radius": 0
+                }
+              },
+              "id": 2,
+              "allow_wrap": false
+            },
+            {
+              "font": "Arial 28px bold",
+              "color": "#000000",
+              "importance": "secondary",
+              "id": 3,
+              "allow_wrap": false
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 17px",
+          "color": "#666666",
+          "allow_wrap": true
+        }
+      },
+      "segment_roles": "$S1 is a ranking or quantitative modifier, $S2 is the emphasized subject (with background, less than 3 words).",
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "innovative_countries",
+      "description": "Three-line emphasis with purple background: black + primary background + black",
+      "style": "professional",
+      "layout_type": "single_column",
+      "alignment": "left",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 27px bold",
+              "color": "#000000",
+              "importance": "secondary",
+              "id": 1,
+              "allow_wrap": false
+            },
+            {
+              "font": "Arial 32px bold",
+              "color": "#FFFFFF",
+              "importance": "primary",
+              "effects": {
+                "background": {
+                  "color": "primary_color",
+                  "padding": 14,
+                  "border_radius": 8
+                }
+              },
+              "id": 2,
+              "allow_wrap": false
+            },
+            {
+              "font": "Arial 27px bold",
+              "color": "#000000",
+              "importance": "secondary",
+              "id": 3,
+              "allow_wrap": false
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 17px",
+          "color": "#666666",
+          "allow_wrap": true
+        }
+      },
+      "segment_roles": "$S1 is a metric label or index name, $S2 is the main subject (with background, less than 3 words).",
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "americas_wealth",
+      "description": "Large elegant title + smaller subtitle on dark background (white text)",
+      "style": "professional",
+      "layout_type": "single_column",
+      "alignment": "center",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Georgia 28px bold",
+              "color": "#FFFFFF",
+              "importance": "primary",
+              "id": 1,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 17px",
+          "color": "#CCCCCC",
+          "allow_wrap": true
+        }
+      },
+      "segment_roles": "$S1 is a complete formal title without internal segmentation.",
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "china_dominance",
+      "description": "Three-line bold title with alternating primary/secondary colors (red-black-red pattern)",
+      "style": "professional",
+      "layout_type": "single_column",
+      "alignment": "left",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Impact 34px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "letter_spacing": "0.02em",
+              "id": 1,
+              "allow_wrap": false
+            },
+            {
+              "font": "Arial 23px bold",
+              "color": "#1A1A1A",
+              "importance": "secondary",
+              "id": 2,
+              "allow_wrap": false
+            },
+            {
+              "font": "Impact 34px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "letter_spacing": "0.02em",
+              "id": 3,
+              "allow_wrap": false
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 16px",
+          "color": "#555555",
+          "allow_wrap": true
+        }
+      },
+      "segment_roles": "$S1 is a possessive or subject identifier, $S2 is a descriptive/categorical modifier, $S3 is an abstract noun or conclusion.",
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "magazine_cover",
+      "description": "Magazine cover style: small eyebrow + huge bold title + elegant subtitle",
+      "style": "professional",
+      "layout_type": "single_column",
+      "alignment": "center",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 19px bold",
+              "color": "primary_color",
+              "importance": "secondary",
+              "text_transform": "uppercase",
+              "letter_spacing": "0.2em",
+              "id": 1,
+              "allow_wrap": true
+            },
+            {
+              "font": "Georgia 32px bold",
+              "color": "#1A1A1A",
+              "importance": "primary",
+              "id": 2,
+              "allow_wrap": true
+            },
+            {
+              "font": "Georgia 19px italic",
+              "color": "#666666",
+              "importance": "secondary",
+              "id": 3,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 16px",
+          "color": "#888888",
+          "allow_wrap": true
+        }
+      },
+      "segment_roles": "$S1 is a meta-label or section tag, $S2 is the main headline, $S3 is a subtitle or elaborative phrase.",
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "newspaper_headline",
+      "description": "Newspaper headline: all caps bold with strong hierarchy",
+      "style": "professional",
+      "layout_type": "single_column",
+      "alignment": "left",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 28px bold",
+              "color": "#000000",
+              "importance": "primary",
+              "text_transform": "uppercase",
+              "letter_spacing": "0.01em",
+              "id": 1,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Georgia 17px",
+          "color": "#333333",
+          "allow_wrap": true
+        }
+      },
+      "segment_roles": "$S1 is a complete declarative sentence or statement headline.",
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "elegant_serif",
+      "description": "Elegant serif: centered thin + thick combination with line spacing",
+      "style": "professional",
+      "layout_type": "single_column",
+      "alignment": "center",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Georgia 20px",
+              "color": "#555555",
+              "importance": "secondary",
+              "letter_spacing": "0.05em",
+              "id": 1,
+              "allow_wrap": true
+            },
+            {
+              "font": "Georgia 27px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "id": 2,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Georgia 16px italic",
+          "color": "#777777",
+          "allow_wrap": true
+        }
+      },
+      "segment_roles": "$S1 is an abstract or philosophical prefix, $S2 is the main conceptual subject.",
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "data_report",
+      "description": "Data report: number emphasis with highlighted background",
+      "style": "professional",
+      "layout_type": "single_column",
+      "alignment": "left",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 20px bold",
+              "color": "#444444",
+              "importance": "secondary",
+              "text_transform": "uppercase",
+              "letter_spacing": "0.15em",
+              "id": 1,
+              "allow_wrap": false
+            },
+            {
+              "font": "Impact 34px bold",
+              "color": "#FFFFFF",
+              "importance": "primary",
+              "background": {
+                "color": "primary_color",
+                "padding": 12,
+                "border_radius": 8
+              },
+              "id": 2,
+              "allow_wrap": false
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 16px",
+          "color": "#666666",
+          "allow_wrap": true
+        }
+      },
+      "segment_roles": "$S1 is a temporal label or reporting period, $S2 is a numeric metric or key finding (with background, less than 3 words).",
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "corporate_brand",
+      "description": "Corporate brand: wide letter spacing + underline emphasis",
+      "style": "professional",
+      "layout_type": "single_column",
+      "alignment": "center",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 28px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "text_transform": "uppercase",
+              "letter_spacing": "0.08em",
+              "id": 1,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 17px",
+          "color": "#555555",
+          "allow_wrap": true
+        }
+      },
+      "segment_roles": "$S1 is a brand statement or corporate message (typically uppercase).",
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "academic_paper",
+      "description": "Academic paper: formal serif with subtitle line",
+      "style": "professional",
+      "layout_type": "single_column",
+      "alignment": "center",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Georgia 24px bold",
+              "color": "#1A1A1A",
+              "importance": "primary",
+              "id": 1,
+              "allow_wrap": true
+            },
+            {
+              "font": "Georgia 20px",
+              "color": "#555555",
+              "importance": "secondary",
+              "id": 2,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Georgia 16px",
+          "color": "#666666",
+          "allow_wrap": true
+        }
+      },
+      "segment_roles": "$S1 is the research topic or phenomenon, $S2 is a methodological or scope qualifier.",
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "tech_startup",
+      "description": "Tech startup: bold sans-serif + colored accent word",
+      "style": "normal",
+      "layout_type": "single_column",
+      "alignment": "left",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 29px bold",
+              "color": "#1A1A1A",
+              "importance": "secondary",
+              "id": 1,
+              "allow_wrap": true
+            },
+            {
+              "font": "Arial 29px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "id": 2,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 17px",
+          "color": "#777777",
+          "allow_wrap": true
+        }
+      },
+      "segment_roles": "$S1 is the first part of a compound statement, $S2 is the complementary second part (color-emphasized).",
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "poster_impact",
+      "description": "Poster impact: mixed sizes with strong contrast",
+      "style": "normal",
+      "layout_type": "single_column",
+      "alignment": "left",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Impact 37px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "letter_spacing": "0.02em",
+              "id": 1,
+              "allow_wrap": false
+            },
+            {
+              "font": "Arial 19px bold",
+              "color": "#2A2A2A",
+              "importance": "secondary",
+              "text_transform": "uppercase",
+              "letter_spacing": "0.1em",
+              "id": 2,
+              "allow_wrap": false
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 16px",
+          "color": "#666666",
+          "allow_wrap": true
+        }
+      },
+      "segment_roles": "$S1 is a declarative statement or call-to-action (huge impact), $S2 is a supporting phrase or continuation.",
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "vintage_style",
+      "description": "Vintage style: decorative serif with layered text",
+      "style": "normal",
+      "layout_type": "single_column",
+      "alignment": "center",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Georgia 19px",
+              "color": "#8B7355",
+              "importance": "secondary",
+              "letter_spacing": "0.3em",
+              "text_transform": "uppercase",
+              "id": 1,
+              "allow_wrap": true
+            },
+            {
+              "font": "Georgia 28px bold",
+              "color": "#2C1810",
+              "importance": "primary",
+              "letter_spacing": "0.05em",
+              "id": 2,
+              "allow_wrap": true
+            },
+            {
+              "font": "Georgia 19px italic",
+              "color": "#A0826D",
+              "importance": "secondary",
+              "letter_spacing": "0.15em",
+              "id": 3,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Georgia 16px",
+          "color": "#6B5D52",
+          "allow_wrap": true
+        }
+      },
+      "segment_roles": "$S1 is a temporal marker or establishment tag, $S2 is a proper noun or brand name, $S3 is a descriptor or tagline.",
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "europe_brands",
+      "description": "Small colored tag + large black title (primary color tag with white text)",
+      "style": "normal",
+      "layout_type": "single_column",
+      "alignment": "left",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 24px bold",
+              "color": "#FFFFFF",
+              "importance": "secondary",
+              "background": {
+                "color": "primary_color",
+                "padding": 12,
+                "border_radius": 12
+              },
+              "id": 1,
+              "allow_wrap": false
+            },
+            {
+              "font": "Arial 32px bold",
+              "color": "#000000",
+              "importance": "primary",
+              "id": 2,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 16px",
+          "color": "#2A2A2A",
+          "allow_wrap": true
+        }
+      },
+      "segment_roles": "$S1 is a geographic or possessive tag (with background, less than 3 words), $S2 is the main headline or topic.",
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "international_students",
+      "description": "Geographic prefix + multi-line stacked emphasis + temporal subtitle",
+      "style": "normal",
+      "layout_type": "single_column",
+      "alignment": "center",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 20px",
+              "color": "#444444",
+              "importance": "secondary",
+              "text_transform": "uppercase",
+              "letter_spacing": 0.08,
+              "id": 1,
+              "allow_wrap": false
+            },
+            {
+              "font": "Impact 34px bold",
+              "color": "#1A1A1A",
+              "importance": "primary",
+              "text_transform": "uppercase",
+              "id": 2,
+              "allow_wrap": false
+            },
+            {
+              "font": "Arial 19px",
+              "color": "#555555",
+              "importance": "secondary",
+              "id": 3,
+              "allow_wrap": false
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 16px",
+          "color": "#666666",
+          "allow_wrap": true
+        }
+      },
+      "segment_roles": "$S1 is a geographic or possessive identifier, $S2 is the main emphasized subject (multi-line capable), $S3 is a temporal or scope qualifier.",
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "kpi_number_pill",
+      "description": "KPI pill: small uppercase label + huge number in rounded pill",
+      "segment_roles": "$S1 is a category/metric label (SECONDARY), $S2 is the key number or data fact (with background, less than 3 words).",
+      "style": "professional",
+      "layout_type": "single_column",
+      "alignment": "left",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 20px bold",
+              "color": "#444444",
+              "importance": "secondary",
+              "text_transform": "uppercase",
+              "letter_spacing": 0.12,
+              "id": 1,
+              "allow_wrap": false
+            },
+            {
+              "font": "Impact 36px",
+              "color": "#FFFFFF",
+              "importance": "primary",
+              "background": {
+                "color": "primary_color",
+                "padding": 12,
+                "border_radius": 15
+              },
+              "id": 2,
+              "allow_wrap": false
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 16px",
+          "color": "#666666",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "timeline_year_span",
+      "description": "Timeline span: small prefix + large year range + small suffix",
+      "segment_roles": "$S1 is a contextual lead-in (SECONDARY), $S2 is the year range / time span (PRIMARY), $S3 is a topic noun or qualifier (SECONDARY).",
+      "style": "normal",
+      "layout_type": "single_column",
+      "alignment": "center",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Georgia 18px italic",
+              "color": "#555555",
+              "importance": "secondary",
+              "id": 1,
+              "allow_wrap": false
+            },
+            {
+              "font": "Arial 34px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "id": 2,
+              "allow_wrap": false
+            },
+            {
+              "font": "Arial 19px",
+              "color": "#333333",
+              "importance": "secondary",
+              "id": 3,
+              "allow_wrap": false
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 16px",
+          "color": "#777777",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "stacked_badge_headline",
+      "description": "Badge + headline + tagline: small label in rounded badge, big headline, small italic tagline",
+      "segment_roles": "$S1 is a label/tag (with background, less than 3 words), $S2 is the main topic or metric (PRIMARY), $S3 is a short qualifier or context (SECONDARY).",
+      "style": "professional",
+      "layout_type": "single_column",
+      "alignment": "left",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 19px bold",
+              "color": "#FFFFFF",
+              "importance": "secondary",
+              "text_transform": "uppercase",
+              "letter_spacing": 0.18,
+              "background": {
+                "color": "primary_color",
+                "padding": 10,
+                "border_radius": 14
+              },
+              "id": 1,
+              "allow_wrap": false
+            },
+            {
+              "font": "Arial 33px bold",
+              "color": "#111111",
+              "importance": "primary",
+              "id": 2,
+              "allow_wrap": true
+            },
+            {
+              "font": "Georgia 18px italic",
+              "color": "#666666",
+              "importance": "secondary",
+              "id": 3,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 16px",
+          "color": "#777777",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "right_align_elegant_duo",
+      "description": "Right aligned duo: small serif context + large bold headline",
+      "segment_roles": "$S1 is context or scope (SECONDARY), $S2 is the core subject (PRIMARY).",
+      "style": "professional",
+      "layout_type": "single_column",
+      "alignment": "right",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Georgia 19px italic",
+              "color": "#666666",
+              "importance": "secondary",
+              "id": 1,
+              "allow_wrap": true
+            },
+            {
+              "font": "Georgia 31px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "id": 2,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 16px",
+          "color": "#666666",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "inline_contrast_triple",
+      "description": "Inline triple: text + highlighted keyword + trailing qualifier (single line)",
+      "segment_roles": "$S1 is a lead-in phrase (SECONDARY), $S2 is the key noun/metric (with background, less than 3 words), $S3 is a short qualifier (SECONDARY). All three are inline.",
+      "style": "normal",
+      "layout_type": "single_column",
+      "alignment": "left",
+      "parts": {
+        "main_title": {
+          "segments": [
+            [
+              {
+                "font": "Arial 25px bold",
+                "color": "#1A1A1A",
+                "importance": "secondary",
+                "id": 1,
+                "allow_wrap": false
+              },
+              {
+                "font": "Arial 25px bold",
+                "color": "#FFFFFF",
+                "importance": "primary",
+                "background": {
+                  "color": "primary_color",
+                  "padding": 10,
+                  "border_radius": 10
+                },
+                "id": 2,
+                "allow_wrap": false
+              },
+              {
+                "font": "Arial 25px bold",
+                "color": "#1A1A1A",
+                "importance": "secondary",
+                "id": 3,
+                "allow_wrap": false
+              }
+            ]
+          ]
+        },
+        "description": {
+          "font": "Arial 17px",
+          "color": "#555555",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "split_colon_emphasis",
+      "description": "Colon split: label on top + main topic highlighted below",
+      "segment_roles": "$S1 is a label/category (SECONDARY), $S2 is the main topic/metric after the colon (with background, less than 3 words).",
+      "style": "professional",
+      "layout_type": "single_column",
+      "alignment": "left",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 18px bold",
+              "color": "#555555",
+              "importance": "secondary",
+              "text_transform": "uppercase",
+              "letter_spacing": 0.12,
+              "id": 1,
+              "allow_wrap": false
+            },
+            {
+              "font": "Arial 32px bold",
+              "color": "#FFFFFF",
+              "importance": "primary",
+              "effects": {
+                "background": {
+                  "color": "primary_color",
+                  "padding": 14,
+                  "border_radius": 8
+                }
+              },
+              "id": 2,
+              "allow_wrap": false
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 16px",
+          "color": "#666666",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "minimal_right_caption",
+      "description": "Minimal right aligned: clean title + italic caption",
+      "segment_roles": "$S1 is a concise headline (PRIMARY).",
+      "style": "simple",
+      "layout_type": "single_column",
+      "alignment": "right",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 28px bold",
+              "color": "#1A1A1A",
+              "importance": "primary",
+              "id": 1,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 16px italic",
+          "color": "#666666",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "two_tone_upper",
+      "description": "Two-tone uppercase: secondary color line + primary color line",
+      "segment_roles": "$S1 is context/scope (SECONDARY), $S2 is the main subject (PRIMARY). Both are uppercase for strong hierarchy.",
+      "style": "normal",
+      "layout_type": "single_column",
+      "alignment": "left",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 22px bold",
+              "color": "secondary_color",
+              "importance": "secondary",
+              "text_transform": "uppercase",
+              "letter_spacing": 0.1,
+              "id": 1,
+              "allow_wrap": false
+            },
+            {
+              "font": "Arial 29px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "text_transform": "uppercase",
+              "letter_spacing": 0.04,
+              "id": 2,
+              "allow_wrap": false
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 16px",
+          "color": "#555555",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "duotone"
+    },
+    {
+      "name": "rounded_label_big_title",
+      "description": "Rounded label + big title: compact label badge above large headline",
+      "segment_roles": "$S1 is a category label (with background, less than 3 words), $S2 is the primary topic/metric (PRIMARY).",
+      "style": "normal",
+      "layout_type": "single_column",
+      "alignment": "left",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 19px bold",
+              "color": "#FFFFFF",
+              "importance": "secondary",
+              "text_transform": "uppercase",
+              "letter_spacing": 0.16,
+              "effects": {
+                "background": {
+                  "color": "#1A1A1A",
+                  "padding": 10,
+                  "border_radius": 15
+                }
+              },
+              "id": 1,
+              "allow_wrap": true
+            },
+            {
+              "font": "Arial 33px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "id": 2,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 16px",
+          "color": "#666666",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "underlined_statement",
+      "description": "Underlined headline: bold title with underline emphasis",
+      "segment_roles": "$S1 is the main statement headline (PRIMARY) with underline emphasis.",
+      "style": "simple",
+      "layout_type": "single_column",
+      "alignment": "left",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 30px bold",
+              "color": "#111111",
+              "importance": "primary",
+              "effects": {
+                "underline": {
+                  "color": "primary_color",
+                  "thickness": 4
+                }
+              },
+              "id": 1,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 16px",
+          "color": "#666666",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "soft_shadow_duo",
+      "description": "Soft shadow duo: small context + big headline with gentle drop shadow",
+      "segment_roles": "$S1 is a context qualifier (SECONDARY), $S2 is the main topic/metric (PRIMARY) with soft shadow for depth.",
+      "style": "normal",
+      "layout_type": "single_column",
+      "alignment": "left",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 18px",
+              "color": "#666666",
+              "importance": "secondary",
+              "id": 1,
+              "allow_wrap": true
+            },
+            {
+              "font": "Arial 33px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "effects": {
+                "shadow": {
+                  "blur": 10,
+                  "offset": [
+                    0,
+                    8
+                  ],
+                  "color": "rgba(0,0,0,0.22)"
+                }
+              },
+              "id": 2,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 16px",
+          "color": "#777777",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "comic_fun_title",
+      "description": "Comic fun title: playful Comic Sans with shadow",
+      "segment_roles": "$S1 is the main fun headline (PRIMARY).",
+      "style": "comic",
+      "layout_type": "single_column",
+      "alignment": "center",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Comic Sans MS 28px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "effects": {
+                "shadow": {
+                  "blur": 6,
+                  "offset": [
+                    4,
+                    4
+                  ],
+                  "color": "rgba(0,0,0,0.3)"
+                }
+              },
+              "id": 1,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Comic Sans MS 17px",
+          "color": "#555555",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "comic_bubble_speech",
+      "description": "Comic bubble speech: small prefix + big Comic Sans title with rounded background",
+      "segment_roles": "$S1 is a playful prefix (SECONDARY), $S2 is the main fun headline (PRIMARY) with bubble background.",
+      "style": "comic",
+      "layout_type": "single_column",
+      "alignment": "left",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Comic Sans MS 19px bold",
+              "color": "#FF6B6B",
+              "importance": "secondary",
+              "id": 1,
+              "allow_wrap": true
+            },
+            {
+              "font": "Comic Sans MS 32px bold",
+              "color": "#FFFFFF",
+              "importance": "primary",
+              "background": {
+                "color": "primary_color",
+                "padding": 15,
+                "border_radius": 20
+              },
+              "id": 2,
+              "allow_wrap": false
+            }
+          ]
+        },
+        "description": {
+          "font": "Comic Sans MS 16px",
+          "color": "#666666",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "comic_colorful_stack",
+      "description": "Comic colorful stack: two-line playful Comic Sans with different colors",
+      "segment_roles": "$S1 is the first part of the fun message (SECONDARY), $S2 is the second part (PRIMARY).",
+      "style": "comic",
+      "layout_type": "single_column",
+      "alignment": "center",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Comic Sans MS 25px bold",
+              "color": "#4ECDC4",
+              "importance": "secondary",
+              "id": 1,
+              "allow_wrap": false
+            },
+            {
+              "font": "Comic Sans MS 30px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "id": 2,
+              "allow_wrap": false
+            }
+          ]
+        },
+        "description": {
+          "font": "Comic Sans MS 17px",
+          "color": "#777777",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "comic_bouncy_emphasis",
+      "description": "Comic bouncy emphasis: inline Comic Sans with highlighted keyword",
+      "segment_roles": "$S1 is the lead-in text (SECONDARY), $S2 is the emphasized fun word (PRIMARY) with rounded background, $S3 is the trailing text (SECONDARY). All inline.",
+      "style": "comic",
+      "layout_type": "single_column",
+      "alignment": "left",
+      "parts": {
+        "main_title": {
+          "segments": [
+            [
+              {
+                "font": "Comic Sans MS 27px bold",
+                "color": "#333333",
+                "importance": "secondary",
+                "id": 1,
+                "allow_wrap": false
+              },
+              {
+                "font": "Comic Sans MS 28px bold",
+                "color": "#FFFFFF",
+                "importance": "primary",
+                "background": {
+                  "color": "primary_color",
+                  "padding": 12,
+                  "border_radius": 18
+                },
+                "id": 2,
+                "allow_wrap": false
+              },
+              {
+                "font": "Comic Sans MS 27px bold",
+                "color": "#333333",
+                "importance": "secondary",
+                "id": 3,
+                "allow_wrap": false
+              }
+            ]
+          ]
+        },
+        "description": {
+          "font": "Comic Sans MS 16px",
+          "color": "#666666",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "comic_playful_label",
+      "description": "Comic playful label: fun rounded badge + big Comic Sans headline",
+      "segment_roles": "$S1 is a playful category label (SECONDARY) in a badge, $S2 is the fun main headline (PRIMARY).",
+      "style": "comic",
+      "layout_type": "single_column",
+      "alignment": "left",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Comic Sans MS 20px bold",
+              "color": "#FFFFFF",
+              "importance": "secondary",
+              "text_transform": "uppercase",
+              "effects": {
+                "background": {
+                  "color": "#FF6B6B",
+                  "padding": 12,
+                  "border_radius": 20
+                }
+              },
+              "id": 1,
+              "allow_wrap": true
+            },
+            {
+              "font": "Comic Sans MS 34px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "id": 2,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Comic Sans MS 17px",
+          "color": "#555555",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "comic_question_fun",
+      "description": "Comic question fun: playful question style with exclamation",
+      "segment_roles": "$S1 is the question setup (SECONDARY), $S2 is the big fun question (PRIMARY).",
+      "style": "comic",
+      "layout_type": "single_column",
+      "alignment": "center",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Comic Sans MS 21px bold",
+              "color": "#FF6B6B",
+              "importance": "secondary",
+              "id": 1,
+              "allow_wrap": true
+            },
+            {
+              "font": "Comic Sans MS 35px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "effects": {
+                "shadow": {
+                  "blur": 8,
+                  "offset": [
+                    5,
+                    5
+                  ],
+                  "color": "rgba(0,0,0,0.25)"
+                }
+              },
+              "id": 2,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Comic Sans MS 17px bold",
+          "color": "#666666",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "comic_bold_announcement",
+      "description": "Comic bold announcement: single huge Comic Sans title with colorful background",
+      "segment_roles": "$S1 is the main announcement (PRIMARY) with bold colorful styling.",
+      "style": "comic",
+      "layout_type": "single_column",
+      "alignment": "center",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Comic Sans MS 33px bold",
+              "color": "#FFFFFF",
+              "importance": "primary",
+              "background": {
+                "color": "primary_color",
+                "padding": 18,
+                "border_radius": 25
+              },
+              "effects": {
+                "shadow": {
+                  "blur": 10,
+                  "offset": [
+                    6,
+                    6
+                  ],
+                  "color": "rgba(0,0,0,0.3)"
+                }
+              },
+              "id": 1,
+              "allow_wrap": false
+            }
+          ]
+        },
+        "description": {
+          "font": "Comic Sans MS 17px",
+          "color": "#555555",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "comic_wavy_text",
+      "description": "Comic wavy text: playful two-line with different Comic Sans styles",
+      "segment_roles": "$S1 is the first playful line (SECONDARY), $S2 is the second emphasized line (PRIMARY).",
+      "style": "comic",
+      "layout_type": "single_column",
+      "alignment": "left",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Comic Sans MS 23px bold",
+              "color": "#FF6B6B",
+              "importance": "secondary",
+              "id": 1,
+              "allow_wrap": true
+            },
+            {
+              "font": "Comic Sans MS 31px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "id": 2,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Comic Sans MS 17px",
+          "color": "#666666",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "comic_mega_title",
+      "description": "Comic mega title: enormous single-line Comic Sans with outline",
+      "segment_roles": "$S1 is the mega headline (PRIMARY) with strong visual impact.",
+      "style": "comic",
+      "layout_type": "single_column",
+      "alignment": "center",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Comic Sans MS 40px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "effects": {
+                "shadow": {
+                  "blur": 12,
+                  "offset": [
+                    6,
+                    6
+                  ],
+                  "color": "rgba(0,0,0,0.4)"
+                }
+              },
+              "id": 1,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Comic Sans MS 18px",
+          "color": "#555555",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "comic_sticker_style",
+      "description": "Comic sticker style: rounded sticker badge + Comic Sans title",
+      "segment_roles": "$S1 is a sticker-like badge (SECONDARY), $S2 is the main title (PRIMARY).",
+      "style": "comic",
+      "layout_type": "single_column",
+      "alignment": "center",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Comic Sans MS 20px bold",
+              "color": "#FFFFFF",
+              "importance": "secondary",
+              "text_transform": "uppercase",
+              "background": {
+                "color": "#FF6B6B",
+                "padding": 14,
+                "border_radius": 25
+              },
+              "effects": {
+                "shadow": {
+                  "blur": 6,
+                  "offset": [
+                    3,
+                    3
+                  ],
+                  "color": "rgba(0,0,0,0.3)"
+                }
+              },
+              "id": 1,
+              "allow_wrap": false
+            },
+            {
+              "font": "Comic Sans MS 32px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "id": 2,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Comic Sans MS 17px",
+          "color": "#666666",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "right_bold_statement",
+      "description": "Right aligned bold statement: single bold headline",
+      "segment_roles": "$S1 is a powerful headline (PRIMARY).",
+      "style": "normal",
+      "layout_type": "single_column",
+      "alignment": "right",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 30px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "id": 1,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 17px",
+          "color": "#666666",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "right_two_tone",
+      "description": "Right aligned two-tone: colored prefix + bold main",
+      "segment_roles": "$S1 is context or category (SECONDARY), $S2 is the main subject (PRIMARY).",
+      "style": "normal",
+      "layout_type": "single_column",
+      "alignment": "right",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 21px",
+              "color": "secondary_color",
+              "importance": "secondary",
+              "text_transform": "uppercase",
+              "letter_spacing": 0.1,
+              "id": 1,
+              "allow_wrap": true
+            },
+            {
+              "font": "Arial 30px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "id": 2,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 16px",
+          "color": "#777777",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "right_serif_classic",
+      "description": "Right aligned classic serif: elegant Georgia headline",
+      "segment_roles": "$S1 is a sophisticated statement (PRIMARY).",
+      "style": "professional",
+      "layout_type": "single_column",
+      "alignment": "right",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Georgia 29px bold",
+              "color": "#1A1A1A",
+              "importance": "primary",
+              "id": 1,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Georgia 17px italic",
+          "color": "#666666",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "right_modern_duo",
+      "description": "Right aligned modern duo: thin secondary + bold primary",
+      "segment_roles": "$S1 is a light descriptor (SECONDARY), $S2 is the bold subject (PRIMARY).",
+      "style": "simple",
+      "layout_type": "single_column",
+      "alignment": "right",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 21px",
+              "color": "#999999",
+              "importance": "secondary",
+              "id": 1,
+              "allow_wrap": true
+            },
+            {
+              "font": "Arial 30px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "id": 2,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 16px",
+          "color": "#888888",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "right_triple_emphasis",
+      "description": "Right aligned triple emphasis: secondary + bold primary + secondary",
+      "segment_roles": "$S1 is context (SECONDARY), $S2 is core subject (PRIMARY), $S3 is closing context (SECONDARY).",
+      "style": "normal",
+      "layout_type": "single_column",
+      "alignment": "right",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 20px",
+              "color": "#333333",
+              "importance": "secondary",
+              "id": 1,
+              "allow_wrap": false
+            },
+            {
+              "font": "Arial 28px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "id": 2,
+              "allow_wrap": false
+            },
+            {
+              "font": "Arial 20px",
+              "color": "#333333",
+              "importance": "secondary",
+              "id": 3,
+              "allow_wrap": false
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 17px italic",
+          "color": "#555555",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "right_impact_headline",
+      "description": "Right aligned impact: large bold uppercase statement",
+      "segment_roles": "$S1 is a powerful declaration (PRIMARY).",
+      "style": "normal",
+      "layout_type": "single_column",
+      "alignment": "right",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Impact 34px bold",
+              "color": "primary_color",
+              "importance": "primary",
+              "text_transform": "uppercase",
+              "letter_spacing": 0.02,
+              "id": 1,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 16px",
+          "color": "#666666",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "right_elegant_stack",
+      "description": "Right aligned elegant stack: small caps + large bold",
+      "segment_roles": "$S1 is a category or subtitle (SECONDARY), $S2 is the main headline (PRIMARY).",
+      "style": "professional",
+      "layout_type": "single_column",
+      "alignment": "right",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 18px",
+              "color": "#888888",
+              "importance": "secondary",
+              "text_transform": "uppercase",
+              "letter_spacing": 0.15,
+              "id": 1,
+              "allow_wrap": true
+            },
+            {
+              "font": "Georgia 32px bold",
+              "color": "#1A1A1A",
+              "importance": "primary",
+              "id": 2,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 17px",
+          "color": "#777777",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    },
+    {
+      "name": "right_minimal_focus",
+      "description": "Right aligned minimal: clean and focused single line",
+      "segment_roles": "$S1 is a clear statement (PRIMARY).",
+      "style": "simple",
+      "layout_type": "single_column",
+      "alignment": "right",
+      "parts": {
+        "main_title": {
+          "segments": [
+            {
+              "font": "Arial 27px",
+              "color": "#2A2A2A",
+              "importance": "primary",
+              "id": 1,
+              "allow_wrap": true
+            }
+          ]
+        },
+        "description": {
+          "font": "Arial 16px",
+          "color": "#999999",
+          "allow_wrap": true
+        }
+      },
+      "color_mode": "monochrome"
+    }
+  ]
+}

modules/title_styler/templates.py

@@ -0,0 +1,494 @@
+"""
+Infographic Title Generator - Template Loader
+Load and parse templates from JSON configuration file
+"""
+
+import json
+import os
+from typing import List, Dict, Optional
+from modules.title_styler.config import (
+    COLOR_TYPE_PRIMARY, COLOR_TYPE_SECONDARY, COLOR_TYPE_FIXED,
+    NEUTRAL_COLORS
+)
+
+
+class LineConfig:
+    """Single line configuration"""
+    
+    def __init__(self, 
+                 role,  # 'main' or 'description'
+                 font_family,
+                 font_size,  # Absolute size in pixels
+                 font_weight='normal',
+                 color_type=COLOR_TYPE_PRIMARY,
+                 color_value=None,
+                 text_transform='none',
+                 letter_spacing=0,
+                 font_style='normal',
+                 allow_wrap=False,
+                 importance=None,       # 'primary' or 'secondary' (for main title only)
+                 # Simplified style options
+                 underline=False,       # True or {'color': '#000', 'thickness': 1}
+                 strikethrough=False,   # True or {'color': '#000', 'thickness': 1}
+                 outline=False,         # True or {'width': 2, 'color': None}
+                 shadow=False,          # True or {'blur': 4, 'offset': (3, 3), 'color': 'rgba(0,0,0,0.3)'}
+                 background=False):     # True or {'color': '#000', 'padding': 10, 'border_radius': 0}
+        """
+        Initialize line configuration
+        
+        Args:
+            role: 'main' for main title, 'description' for subtitle
+            font_family: Font name
+            font_size: Font size in pixels (e.g. 48, 32)
+            font_weight: Font weight ('normal', 'bold', 'bolder', 'lighter')
+            color_type: Color type
+            color_value: Fixed color value
+            text_transform: Text transform ('none', 'uppercase', 'lowercase', 'capitalize')
+            letter_spacing: Letter spacing in em units
+            font_style: Font style ('normal', 'italic', 'oblique')
+            allow_wrap: Whether to allow text wrapping (when exceeding max_width)
+            importance: Importance level (for main title only)
+                - 'primary': Most relevant part (e.g. "Mobile Phones"), usually larger and bolder
+                - 'secondary': Supporting part (e.g. "The Best Selling"), usually smaller
+                - None: Not specified (default)
+            
+            underline: Underline
+                - False: Not used
+                - True: Use default style
+                - dict: {'color': '#000000', 'thickness': 1}
+            
+            strikethrough: Strikethrough
+                - False: Not used
+                - True: Use default style
+                - dict: {'color': '#000000', 'thickness': 1}
+            
+            outline: Outline text
+                - False: Not used
+                - True: Use default style (2px width)
+                - dict: {'width': 2, 'color': None}  # None means use primary color
+            
+            shadow: Shadow
+                - False: Not used
+                - True: Use default style (offset 3,3, blur 4)
+                - dict: {'blur': 4, 'offset': (3, 3), 'color': 'rgba(0,0,0,0.3)'}
+            
+            background: Background rectangle
+                - False: Not used
+                - True: Use default style (black bg, 10px padding)
+                - dict: {'color': '#000000', 'padding': 10, 'border_radius': 0}
+        """
+        self.role = role
+        self.importance = importance  # Added: importance marker
+        self.font_family = font_family
+        self.font_size = font_size
+        self.font_weight = font_weight
+        self.color_type = color_type
+        self.color_value = color_value
+        self.text_transform = text_transform
+        self.letter_spacing = letter_spacing
+        self.font_style = font_style
+        self.allow_wrap = allow_wrap
+        
+        # Normalize style parameters
+        self.underline = self._normalize_style_param(underline, {
+            'color': None,  # None means use text color
+            'thickness': 1
+        })
+        
+        self.strikethrough = self._normalize_style_param(strikethrough, {
+            'color': None,
+            'thickness': 1
+        })
+        
+        self.outline = self._normalize_style_param(outline, {
+            'width': 2,
+            'color': None  # None means use text color
+        })
+        
+        self.shadow = self._normalize_style_param(shadow, {
+            'blur': 4,
+            'offset': (3, 3),
+            'color': 'rgba(0,0,0,0.3)'
+        })
+        self.background = self._normalize_style_param(background, {
+            'color': '#000000',
+            'padding': 10,
+            'border_radius': 0
+        })
+    
+    def _normalize_style_param(self, param, defaults):
+        """
+        Normalize style parameter
+        
+        Args:
+            param: False / True / dict
+            defaults: Default values dictionary
+        
+        Returns:
+            False or dictionary with complete parameters
+        """
+        if param is False or param is None:
+            return False
+        elif param is True:
+            return defaults.copy()
+        elif isinstance(param, dict):
+            # Merge user parameters and defaults
+            result = defaults.copy()
+            result.update(param)
+            return result
+        else:
+            # Other cases treated as True
+            return defaults.copy()
+    
+    def to_dict(self):
+        """Convert to dictionary"""
+        return {
+            'role': self.role,
+            'importance': self.importance,
+            'font_family': self.font_family,
+            'font_size': self.font_size,
+            'font_weight': self.font_weight,
+            'color_type': self.color_type,
+            'color_value': self.color_value,
+            'text_transform': self.text_transform,
+            'letter_spacing': self.letter_spacing,
+            'font_style': self.font_style,
+            'allow_wrap': self.allow_wrap,
+            'underline': self.underline,
+            'strikethrough': self.strikethrough,
+            'outline': self.outline,
+            'shadow': self.shadow,
+            'background': self.background,
+        }
+    
+    def to_json_dict(self):
+        """Convert to JSON format (simplified version, conforms to template_schema.json)"""
+        # Build font string: e.g. "Arial 68px bold" or "Arial 24px normal italic"
+        font_parts = [self.font_family, f"{self.font_size}px"]
+        if self.font_weight and self.font_weight != 'normal':
+            font_parts.append(self.font_weight)
+        if self.font_style and self.font_style != 'normal':
+            font_parts.append(self.font_style)
+        font_string = ' '.join(font_parts)
+        
+        # Build color string: either hex color or variable name
+        if self.color_type == COLOR_TYPE_PRIMARY:
+            color_string = 'primary_color'
+        elif self.color_type == COLOR_TYPE_SECONDARY:
+            color_string = 'secondary_color'
+        else:  # FIXED
+            color_string = self.color_value
+        
+        # Build effects object (only include non-False effects)
+        effects = {}
+        if self.shadow:
+            effects['shadow'] = self.shadow
+        if self.outline:
+            effects['outline'] = self.outline
+        if self.underline:
+            effects['underline'] = self.underline
+        if self.strikethrough:
+            effects['strikethrough'] = self.strikethrough
+        
+        result = {
+            'font': font_string,
+            'color': color_string,
+        }
+        
+        # Only main role has importance
+        if self.role == 'main':
+            result['importance'] = self.importance or 'primary'
+        
+        # Add optional fields
+        if self.text_transform and self.text_transform != 'none':
+            result['text_transform'] = self.text_transform
+        if self.letter_spacing and self.letter_spacing != 0:
+            result['letter_spacing'] = self.letter_spacing
+        if effects:
+            result['effects'] = effects
+        
+        return result
+
+
+class TitleTemplate:
+    """Title template class"""
+    
+    def __init__(self, name, description, lines=None, alignment='center', style='normal', 
+                 color_mode='monochrome'):
+        """
+        Initialize template
+        
+        Args:
+            name: Template name
+            description: Template description
+            lines: List of LineConfig objects (single column layout)
+            alignment: Alignment (left/center/right)
+            style: Template style ('normal', 'comic', 'simple', 'professional')
+            color_mode: Color mode ('monochrome' or 'duotone')
+        """
+        self.name = name
+        self.description = description
+        self.alignment = alignment
+        self.style = style
+        self.color_mode = color_mode
+        
+        # Single column layout
+        self.lines = lines
+        self.columns = None  # Single column mode
+    
+    def has_main(self):
+        """Check if contains main title line"""
+        return any(line.role == 'main' for line in self.lines)
+    
+    def has_description(self):
+        """Check if contains description line"""
+        return any(line.role == 'description' for line in self.lines)
+    
+    def __repr__(self):
+        main_count = sum(1 for l in self.lines if l.role == 'main')
+        desc_count = sum(1 for l in self.lines if l.role == 'description')
+        return f"<TitleTemplate: {self.name} (main:{main_count}, desc:{desc_count}, {self.color_mode})>"
+
+
+# Template cache (loaded from JSON)
+_TEMPLATES_CACHE = None
+
+
+def _parse_font_string(font_string: str) -> Dict:
+    """
+    Parse font string like "Arial 68px bold" or "Comic Sans MS 72px bold" into components
+    
+    Returns:
+        {
+            'font_family': 'Arial' or 'Comic Sans MS',
+            'font_size': 68,
+            'font_weight': 'bold',
+            'font_style': 'normal'
+        }
+    """
+    parts = font_string.split()
+    
+    # Find the part with "px" - that's the font size
+    size_index = -1
+    font_size = 0
+    for i, part in enumerate(parts):
+        if 'px' in part:
+            size_index = i
+            font_size = int(part.replace('px', ''))
+            break
+    
+    if size_index == -1:
+        raise ValueError(f"Invalid font string: {font_string} - no size found")
+    
+    # Everything before the size is the font family
+    font_family = ' '.join(parts[:size_index])
+    
+    # Everything after the size is weight/style
+    font_weight = 'normal'
+    font_style = 'normal'
+    
+    for part in parts[size_index + 1:]:
+        if part in ['bold', 'bolder', 'lighter', 'normal']:
+            font_weight = part
+        elif part in ['italic', 'oblique']:
+            font_style = part
+    
+    return {
+        'font_family': font_family,
+        'font_size': font_size,
+        'font_weight': font_weight,
+        'font_style': font_style
+    }
+
+
+def _parse_color_string(color_string: str) -> tuple:
+    """
+    Parse color string into (color_type, color_value)
+    
+    Args:
+        color_string: "#000000", "primary_color", or "secondary_color"
+    
+    Returns:
+        (COLOR_TYPE_*, color_value)
+    """
+    if color_string == 'primary_color':
+        return (COLOR_TYPE_PRIMARY, None)
+    elif color_string == 'secondary_color':
+        return (COLOR_TYPE_SECONDARY, None)
+    else:
+        return (COLOR_TYPE_FIXED, color_string)
+
+
+def _load_templates_from_json(json_file='templates.json') -> List[TitleTemplate]:
+    """
+    Load templates from JSON configuration file
+    
+    Args:
+        json_file: Path to templates JSON file
+    
+    Returns:
+        List of TitleTemplate objects
+    """
+    json_path = os.path.join(os.path.dirname(__file__), json_file)
+    
+    if not os.path.exists(json_path):
+        raise FileNotFoundError(f"Templates file not found: {json_path}")
+    
+    with open(json_path, 'r', encoding='utf-8') as f:
+        data = json.load(f)
+    
+    templates = []
+    
+    for template_dict in data.get('templates', []):
+        name = template_dict['name']
+        description = template_dict.get('description', '')
+        style = template_dict.get('style', 'normal')
+        color_mode = template_dict.get('color_mode', 'monochrome')
+        layout_type = template_dict['layout_type']
+        alignment = template_dict.get('alignment', 'center')
+        parts = template_dict['parts']
+        
+        if layout_type == 'single_column':
+            # Single column layout
+            lines = []
+            
+            # Parse main_title segments (supports nested arrays for inline groups)
+            main_title = parts.get('main_title', {})
+            segments_raw = main_title.get('segments', [])
+            
+            # Flatten segments and track inline groups
+            # Format: [seg1, [seg2, seg3], seg4] where array means inline
+            inline_groups = []  # List of (start_idx, end_idx) for inline groups
+            flat_segments = []
+            current_idx = 0
+            
+            for item in segments_raw:
+                if isinstance(item, list):
+                    # Inline group
+                    group_start = current_idx
+                    for seg in item:
+                        flat_segments.append(seg)
+                        current_idx += 1
+                    inline_groups.append((group_start, current_idx - 1))
+                else:
+                    # Single segment
+                    flat_segments.append(item)
+                    current_idx += 1
+            
+            for segment in flat_segments:
+                # Regular text segment
+                font_info = _parse_font_string(segment['font'])
+                color_type, color_value = _parse_color_string(segment['color'])
+                
+                # Get background from either 'background' or 'effects.background'
+                background = segment.get('background', False)
+                if not background and 'effects' in segment:
+                    background = segment['effects'].get('background', False)
+                
+                # Determine allow_wrap: if has background, force to False; otherwise use segment's setting
+                if background:
+                    allow_wrap = False
+                else:
+                    allow_wrap = segment.get('allow_wrap', False)
+                
+                line = LineConfig(
+                    role='main',
+                    importance=segment.get('importance', 'primary'),
+                    font_family=font_info['font_family'],
+                    font_size=font_info['font_size'],
+                    font_weight=font_info['font_weight'],
+                    font_style=font_info['font_style'],
+                    color_type=color_type,
+                    color_value=color_value,
+                    text_transform=segment.get('text_transform', 'none'),
+                    letter_spacing=segment.get('letter_spacing', 0),
+                    allow_wrap=allow_wrap,
+                    shadow=segment.get('effects', {}).get('shadow', False) if 'effects' in segment else False,
+                    outline=segment.get('effects', {}).get('outline', False) if 'effects' in segment else False,
+                    underline=segment.get('effects', {}).get('underline', False) if 'effects' in segment else False,
+                    strikethrough=segment.get('effects', {}).get('strikethrough', False) if 'effects' in segment else False,
+                    background=background,
+                )
+                lines.append(line)
+            
+            # Parse description
+            if 'description' in parts:
+                desc = parts['description']
+                font_info = _parse_font_string(desc['font'])
+                color_type, color_value = _parse_color_string(desc['color'])
+                
+                line = LineConfig(
+                    role='description',
+                    font_family=font_info['font_family'],
+                    font_size=font_info['font_size'],
+                    font_weight=font_info['font_weight'],
+                    font_style=font_info['font_style'],
+                    color_type=color_type,
+                    color_value=color_value,
+                    allow_wrap=desc.get('allow_wrap', True),
+                    text_transform=desc.get('text_transform', 'none'),
+                    letter_spacing=desc.get('letter_spacing', 0),
+                )
+                lines.append(line)
+            
+            template = TitleTemplate(
+                name=name,
+                description=description,
+                lines=lines,
+                alignment=alignment,
+                style=style,
+                color_mode=color_mode
+            )
+            # Store inline groups as an attribute
+            template.inline_groups = inline_groups  # List of (start_idx, end_idx)
+            templates.append(template)
+    
+    return templates
+
+
+def get_all_templates() -> List[TitleTemplate]:
+    """Get all templates (loaded from JSON)"""
+    global _TEMPLATES_CACHE
+    
+    if _TEMPLATES_CACHE is None:
+        _TEMPLATES_CACHE = _load_templates_from_json()
+    
+    return _TEMPLATES_CACHE
+
+
+def reload_templates():
+    """Reload templates from JSON file"""
+    global _TEMPLATES_CACHE
+    _TEMPLATES_CACHE = None
+    return get_all_templates()
+
+
+def get_templates_by_alignment(alignment: str) -> List[TitleTemplate]:
+    """Get templates by alignment"""
+    return [t for t in get_all_templates() if t.alignment == alignment]
+
+
+def get_templates_with_description() -> List[TitleTemplate]:
+    """Get templates with description"""
+    return [t for t in get_all_templates() if t.has_description()]
+
+
+def get_templates_main_only() -> List[TitleTemplate]:
+    """Get templates with main title only"""
+    return [t for t in get_all_templates() if not t.has_description()]
+
+
+def get_templates_by_style(style: str) -> List[TitleTemplate]:
+    """
+    Get templates by style
+    
+    Args:
+        style: Template style ('normal', 'comic', 'simple', 'professional', 'all')
+               'all' means return all templates regardless of style
+    
+    Returns:
+        List of templates matching the style
+    """
+    if style == 'all':
+        return get_all_templates()
+    return [t for t in get_all_templates() if t.style == style]

modules/title_styler/test_cases.py

@@ -0,0 +1,607 @@
+"""
+Test script for specific problematic SVG cases
+Tests the following cases that were reported to have issues:
+1. tourism_cities_3_financial_centers.svg
+2. tech_companies_1_rounded_label_big_title.svg
+3. renewable_power_3_inline_contrast_triple.svg
+4. life_expectancy_2_comic_bouncy_emphasis.svg
+5. life_expectancy_1_stacked_badge_headline.svg
+6. europe_cars_2_comic_bouncy_emphasis.svg
+7. education_cost_1_comic_bold_announcement.svg
+8. arctic_ice_decline_1_highlight_stripe.svg
+"""
+
+from modules.title_styler.infographic_title_generator import generate_title
+
+# Problematic cases with their corresponding test data and templates
+# Each case includes manually segmented title text to match template segments
+PROBLEMATIC_CASES = [
+    {
+        "test_id": "tourism_cities",
+        # financial_centers: 3 segments (black + primary bg + black)
+        "title_segments": "Top 10 Most\nVisited Cities\nin 2024",
+        "description": "Annual tourism statistics reveal which urban destinations attracted the most international visitors last year",
+        "primary_color": "#E67E22",
+        "background_color": "#FFFFFF",
+        "template_name": "financial_centers",
+        "output_file": "tourism_cities_3_financial_centers.svg"
+    },
+    {
+        "test_id": "tech_companies",
+        # rounded_label_big_title: 2 segments (label badge + headline)
+        "title_segments": "TECH\nAmerica's Largest Technology Companies",
+        "description": "Market capitalization comparison of leading tech firms headquartered in the United States",
+        "primary_color": "#8E44AD",
+        "background_color": "#F5F5F5",
+        "template_name": "rounded_label_big_title",
+        "output_file": "tech_companies_1_rounded_label_big_title.svg"
+    },
+    {
+        "test_id": "renewable_power",
+        # inline_contrast_triple: 3 inline segments
+        "title_segments": "Renewable Energy\nShare\nof Total Electricity Generation",
+        "description": "Tracking the percentage of power generated from solar, wind, hydro, and other renewable sources by country",
+        "primary_color": "#16A085",
+        "background_color": "#ECF0F1",
+        "template_name": "inline_contrast_triple",
+        "output_file": "renewable_power_3_inline_contrast_triple.svg"
+    },
+    {
+        "test_id": "life_expectancy",
+        # comic_bouncy_emphasis: 3 inline segments
+        "title_segments": "Average\nLife Expectancy\nGains Since 1950",
+        "description": "How longevity has improved across different regions over seven decades of global development",
+        "primary_color": "#9B59B6",
+        "background_color": "#FFFFFF",
+        "template_name": "comic_bouncy_emphasis",
+        "output_file": "life_expectancy_2_comic_bouncy_emphasis.svg"
+    },
+    {
+        "test_id": "life_expectancy",
+        # stacked_badge_headline: 3 segments (badge + headline + tagline)
+        "title_segments": "LONGEVITY\nLife Expectancy Gains\nSince 1950",
+        "description": "How longevity has improved across different regions over seven decades of global development",
+        "primary_color": "#9B59B6",
+        "background_color": "#FFFFFF",
+        "template_name": "stacked_badge_headline",
+        "output_file": "life_expectancy_1_stacked_badge_headline.svg"
+    },
+    {
+        "test_id": "europe_cars",
+        # comic_bouncy_emphasis: 3 inline segments
+        "title_segments": "Europe's\nBest-Selling\nCar Brands in H1 2025",
+        "description": "This visualization shows the best-selling car brands in Europe",
+        "primary_color": "#1E5BBD",
+        "background_color": "#E8E8E8",
+        "template_name": "comic_bouncy_emphasis",
+        "output_file": "europe_cars_2_comic_bouncy_emphasis.svg"
+    },
+    {
+        "test_id": "education_cost",
+        # comic_bold_announcement: 1 segment (single huge title)
+        "title_segments": "The Rising Cost of Higher Education",
+        "description": "How tuition fees have increased across different types of universities over the past two decades",
+        "primary_color": "#C0392B",
+        "background_color": "#F9F9F9",
+        "template_name": "comic_bold_announcement",
+        "output_file": "education_cost_1_comic_bold_announcement.svg"
+    },
+    {
+        "test_id": "arctic_ice_decline",
+        # highlight_stripe: 2 segments (lead-in + highlighted core)
+        "title_segments": "The Dramatic Decline of\nArctic Sea Ice Coverage Over the Past Four Decades",
+        "description": "Satellite imagery and climate data reveal unprecedented melting patterns affecting polar ecosystems and global weather",
+        "primary_color": "#2C3E50",
+        "background_color": "#FFFFFF",
+        "template_name": "highlight_stripe",
+        "output_file": "arctic_ice_decline_1_highlight_stripe.svg"
+    }
+]
+
+
+# Comprehensive test cases for all 48 templates
+FULL_TEMPLATE_TEST_CASES = [
+    {
+        "test_id": "three_line_emphasis",
+        "title_segments": "Average\nLife Expectancy\nGains Since 1950",
+        "description": "How longevity has improved across different regions over seven decades",
+        "primary_color": "#E67E22",
+        "background_color": "#FFFFFF",
+        "template_name": "three_line_emphasis",
+        "output_file": "three_line_emphasis_test.svg"
+    },
+    {
+        "test_id": "two_line_hierarchy",
+        "title_segments": "The Evolution of\nArtificial Intelligence",
+        "description": "From early neural networks to modern large language models",
+        "primary_color": "#F5F5F5",
+        "background_color": "#8E44AD",
+        "template_name": "two_line_hierarchy",
+        "output_file": "two_line_hierarchy_test.svg"
+    },
+    {
+        "test_id": "lithium_countries",
+        "title_segments": "World's Largest\nLithium Producers",
+        "description": "Countries leading the global lithium extraction industry",
+        "primary_color": "#16A085",
+        "background_color": "#ECF0F1",
+        "template_name": "lithium_countries",
+        "output_file": "lithium_countries_test.svg"
+    },
+    {
+        "test_id": "european_adults",
+        "title_segments": "Among European Adults\nSmoking Rates Decline",
+        "description": "Public health campaigns and regulations drive behavioral change",
+        "primary_color": "#9B59B6",
+        "background_color": "#FFFFFF",
+        "template_name": "european_adults",
+        "output_file": "european_adults_test.svg"
+    },
+    {
+        "test_id": "millionaires_green",
+        "title_segments": "Number of\nMillionaires by Country",
+        "description": "Wealth distribution across major economies worldwide",
+        "primary_color": "#1E5BBD",
+        "background_color": "#E8E8E8",
+        "template_name": "millionaires_green",
+        "output_file": "millionaires_green_test.svg"
+    },
+    {
+        "test_id": "america_valuable",
+        "title_segments": "America's\nMost Valuable\nTech\nCompanies",
+        "description": "Market capitalization of leading technology firms",
+        "primary_color": "#C0392B",
+        "background_color": "#F9F9F9",
+        "template_name": "america_valuable",
+        "output_file": "america_valuable_test.svg"
+    },
+    {
+        "test_id": "dentist_question",
+        "title_segments": "How Many People\nVisit the Dentist Annually?",
+        "description": "Dental care access and frequency across different demographics",
+        "primary_color": "#2C3E50",
+        "background_color": "#FFFFFF",
+        "template_name": "dentist_question",
+        "output_file": "dentist_question_test.svg"
+    },
+    {
+        "test_id": "infant_mortality",
+        "title_segments": "HEALTH\nInfant Mortality Rates by Region",
+        "description": "Global health indicators tracking child survival rates",
+        "primary_color": "#FF00FF",
+        "background_color": "#333333",
+        "template_name": "infant_mortality",
+        "output_file": "infant_mortality_test.svg"
+    },
+    {
+        "test_id": "financial_centers",
+        "title_segments": "Top 10\nGlobal Financial Centers\nRanked by GDP",
+        "description": "Economic powerhouses driving international finance",
+        "primary_color": "#E74C3C",
+        "background_color": "#F0F0F0",
+        "template_name": "financial_centers",
+        "output_file": "financial_centers_test.svg"
+    },
+    {
+        "test_id": "innovative_countries",
+        "title_segments": "Innovation Index\nMost Innovative Countries\nand Their Scores",
+        "description": "R&D investment and patent output rankings",
+        "primary_color": "#3498DB",
+        "background_color": "#FFFFFF",
+        "template_name": "innovative_countries",
+        "output_file": "innovative_countries_test.svg"
+    },
+    {
+        "test_id": "americas_wealth",
+        "title_segments": "Total Household Wealth in North America",
+        "description": "Combined assets of families across the United States and Canada",
+        "primary_color": "#E67E22",
+        "background_color": "#2C3E50",
+        "template_name": "americas_wealth",
+        "output_file": "americas_wealth_test.svg"
+    },
+    {
+        "test_id": "china_dominance",
+        "title_segments": "China's\nGrowing\nEconomic Influence",
+        "description": "Trade relationships and investment patterns worldwide",
+        "primary_color": "#16A085",
+        "background_color": "#ECF0F1",
+        "template_name": "china_dominance",
+        "output_file": "china_dominance_test.svg"
+    },
+    {
+        "test_id": "magazine_cover",
+        "title_segments": "FEATURE STORY\nThe Future of Space Exploration\nNew Frontiers Ahead",
+        "description": "Innovations in rocket technology and planetary missions",
+        "primary_color": "#9B59B6",
+        "background_color": "#FFFFFF",
+        "template_name": "magazine_cover",
+        "output_file": "magazine_cover_test.svg"
+    },
+    {
+        "test_id": "newspaper_headline",
+        "title_segments": "Climate Agreement Reached at International Summit",
+        "description": "World leaders commit to ambitious carbon reduction targets",
+        "primary_color": "#1E5BBD",
+        "background_color": "#E8E8E8",
+        "template_name": "newspaper_headline",
+        "output_file": "newspaper_headline_test.svg"
+    },
+    {
+        "test_id": "elegant_serif",
+        "title_segments": "The Philosophy of\nSustainable Development",
+        "description": "Balancing economic growth with environmental preservation",
+        "primary_color": "#C0392B",
+        "background_color": "#F9F9F9",
+        "template_name": "elegant_serif",
+        "output_file": "elegant_serif_test.svg"
+    },
+    {
+        "test_id": "data_report",
+        "title_segments": "Q3 2024\n+18% Revenue Growth",
+        "description": "Quarterly financial performance exceeds analyst expectations",
+        "primary_color": "#2C3E50",
+        "background_color": "#FFFFFF",
+        "template_name": "data_report",
+        "output_file": "data_report_test.svg"
+    },
+    {
+        "test_id": "corporate_brand",
+        "title_segments": "INNOVATION THROUGH COLLABORATION",
+        "description": "Our commitment to advancing technology for everyone",
+        "primary_color": "#27AE60",
+        "background_color": "#FAFAFA",
+        "template_name": "corporate_brand",
+        "output_file": "corporate_brand_test.svg"
+    },
+    {
+        "test_id": "corporate_brand_desc_gap",
+        "title_segments": "Full-Day Kindergarten Outperforms Half-Day on Reading Scores",
+        "description": "ReadingScores for Half-Day and Full-Day kindergarten students (from 2015 to 2023) consistently indicate higher performance in Full-Day.",
+        "primary_color": "#f8dd3d",
+        "background_color": "#E2F1F6",
+        "template_name": "corporate_brand",
+        "output_file": "corporate_brand_desc_gap_test.svg"
+    },
+    {
+        "test_id": "academic_paper",
+        "title_segments": "Machine Learning Applications\nin Climate Science",
+        "description": "Improving weather prediction models with AI techniques",
+        "primary_color": "#E74C3C",
+        "background_color": "#F0F0F0",
+        "template_name": "academic_paper",
+        "output_file": "academic_paper_test.svg"
+    },
+    {
+        "test_id": "tech_startup",
+        "title_segments": "Move Fast\nBreak Barriers",
+        "description": "Our mission to disrupt traditional industries",
+        "primary_color": "#3498DB",
+        "background_color": "#FFFFFF",
+        "template_name": "tech_startup",
+        "output_file": "tech_startup_test.svg"
+    },
+    {
+        "test_id": "poster_impact",
+        "title_segments": "JOIN THE REVOLUTION\nTogether We Rise",
+        "description": "Community-driven social change movement",
+        "primary_color": "#E67E22",
+        "background_color": "#FFFFFF",
+        "template_name": "poster_impact",
+        "output_file": "poster_impact_test.svg"
+    },
+    {
+        "test_id": "vintage_style",
+        "title_segments": "Est. 1887\nHeritage Coffee Co.\nAuthentic Roasters",
+        "description": "Traditional craftsmanship meets modern taste",
+        "primary_color": "#8E44AD",
+        "background_color": "#F5F5F5",
+        "template_name": "vintage_style",
+        "output_file": "vintage_style_test.svg"
+    },
+    {
+        "test_id": "europe_brands",
+        "title_segments": "EUROPE\nBest-Selling Car Brands in 2024",
+        "description": "Consumer preferences across major European markets",
+        "primary_color": "#16A085",
+        "background_color": "#ECF0F1",
+        "template_name": "europe_brands",
+        "output_file": "europe_brands_test.svg"
+    },
+    {
+        "test_id": "international_students",
+        "title_segments": "Asia's\nTop Universities\nfor International Students",
+        "description": "Rankings based on diversity and academic excellence",
+        "primary_color": "#9B59B6",
+        "background_color": "#FFFFFF",
+        "template_name": "international_students",
+        "output_file": "international_students_test.svg"
+    },
+    {
+        "test_id": "kpi_number_pill",
+        "title_segments": "QUARTERLY REVENUE\n$2.4 Billion",
+        "description": "Record-breaking sales driven by product innovation",
+        "primary_color": "#1E5BBD",
+        "background_color": "#E8E8E8",
+        "template_name": "kpi_number_pill",
+        "output_file": "kpi_number_pill_test.svg"
+    },
+    {
+        "test_id": "timeline_year_span",
+        "title_segments": "Looking Back at\n1990-2020\nTechnology Evolution",
+        "description": "Three decades of digital transformation",
+        "primary_color": "#C0392B",
+        "background_color": "#F9F9F9",
+        "template_name": "timeline_year_span",
+        "output_file": "timeline_year_span_test.svg"
+    },
+    {
+        "test_id": "stacked_badge_headline",
+        "title_segments": "SUSTAINABILITY\nCarbon Emissions Reduction\nSince 2010",
+        "description": "Progress toward net-zero goals across industries",
+        "primary_color": "#2C3E50",
+        "background_color": "#FFFFFF",
+        "template_name": "stacked_badge_headline",
+        "output_file": "stacked_badge_headline_test.svg"
+    },
+    {
+        "test_id": "right_align_elegant_duo",
+        "title_segments": "Across Major Cities\nUrban Population Density",
+        "description": "Comparing metropolitan areas worldwide",
+        "primary_color": "#27AE60",
+        "background_color": "#FAFAFA",
+        "template_name": "right_align_elegant_duo",
+        "output_file": "right_align_elegant_duo_test.svg"
+    },
+    {
+        "test_id": "inline_contrast_triple",
+        "title_segments": "The Rise of\nElectric Vehicles\nin Global Markets",
+        "description": "Adoption rates accelerate with policy support",
+        "primary_color": "#E74C3C",
+        "background_color": "#F0F0F0",
+        "template_name": "inline_contrast_triple",
+        "output_file": "inline_contrast_triple_test.svg"
+    },
+    {
+        "test_id": "split_colon_emphasis",
+        "title_segments": "INNOVATION REPORT:\nBreakthrough Technologies of 2024",
+        "description": "Scientific advances transforming daily life",
+        "primary_color": "#3498DB",
+        "background_color": "#FFFFFF",
+        "template_name": "split_colon_emphasis",
+        "output_file": "split_colon_emphasis_test.svg"
+    },
+    {
+        "test_id": "minimal_right_caption",
+        "title_segments": "Global Trade Volumes",
+        "description": "International commerce statistics",
+        "primary_color": "#E67E22",
+        "background_color": "#FFFFFF",
+        "template_name": "minimal_right_caption",
+        "output_file": "minimal_right_caption_test.svg"
+    },
+    {
+        "test_id": "two_tone_upper",
+        "title_segments": "MARKET ANALYSIS\nCRYPTOCURRENCY TRENDS",
+        "description": "Digital asset valuations and regulatory developments",
+        "primary_color": "#8E44AD",
+        "background_color": "#F5F5F5",
+        "template_name": "two_tone_upper",
+        "output_file": "two_tone_upper_test.svg"
+    },
+    {
+        "test_id": "rounded_label_big_title",
+        "title_segments": "TECH\nArtificial Intelligence Market Growth",
+        "description": "Industry valuation surpasses $500 billion",
+        "primary_color": "#16A085",
+        "background_color": "#ECF0F1",
+        "template_name": "rounded_label_big_title",
+        "output_file": "rounded_label_big_title_test.svg"
+    },
+    {
+        "test_id": "underlined_statement",
+        "title_segments": "The Future Belongs to Renewable Energy",
+        "description": "Sustainable power generation becomes economically dominant",
+        "primary_color": "#9B59B6",
+        "background_color": "#FFFFFF",
+        "template_name": "underlined_statement",
+        "output_file": "underlined_statement_test.svg"
+    },
+    {
+        "test_id": "soft_shadow_duo",
+        "title_segments": "Throughout History\nRevolutionary Inventions",
+        "description": "Innovations that changed human civilization",
+        "primary_color": "#1E5BBD",
+        "background_color": "#E8E8E8",
+        "template_name": "soft_shadow_duo",
+        "output_file": "soft_shadow_duo_test.svg"
+    },
+    {
+        "test_id": "comic_fun_title",
+        "title_segments": "Super Amazing Facts About Space!",
+        "description": "Mind-blowing discoveries about our universe",
+        "primary_color": "#C0392B",
+        "background_color": "#F9F9F9",
+        "template_name": "comic_fun_title",
+        "output_file": "comic_fun_title_test.svg"
+    },
+    {
+        "test_id": "comic_bubble_speech",
+        "title_segments": "Guess What?\nPandas Eat 40kg Bamboo Daily!",
+        "description": "Incredible animal eating habits revealed",
+        "primary_color": "#2C3E50",
+        "background_color": "#FFFFFF",
+        "template_name": "comic_bubble_speech",
+        "output_file": "comic_bubble_speech_test.svg"
+    },
+    {
+        "test_id": "comic_bouncy_emphasis",
+        "title_segments": "World's\nCoolest\nGadgets of 2024",
+        "description": "The most exciting tech toys released this year",
+        "primary_color": "#E74C3C",
+        "background_color": "#F0F0F0",
+        "template_name": "comic_bouncy_emphasis",
+        "output_file": "comic_bouncy_emphasis_test.svg"
+    },
+    {
+        "test_id": "comic_playful_label",
+        "title_segments": "FUN FACTS\nOceans Cover 71% of Earth!",
+        "description": "Amazing things you never knew about our planet",
+        "primary_color": "#3498DB",
+        "background_color": "#FFFFFF",
+        "template_name": "comic_playful_label",
+        "output_file": "comic_playful_label_test.svg"
+    },
+    {
+        "test_id": "comic_question_fun",
+        "title_segments": "Did You Know?\nBananas Are Berries!",
+        "description": "Surprising botanical classification facts",
+        "primary_color": "#E67E22",
+        "background_color": "#FFFFFF",
+        "template_name": "comic_question_fun",
+        "output_file": "comic_question_fun_test.svg"
+    },
+    {
+        "test_id": "comic_bold_announcement",
+        "title_segments": "The Most Incredible Animal Superpowers!",
+        "description": "Nature's amazing adaptations and abilities",
+        "primary_color": "#8E44AD",
+        "background_color": "#F5F5F5",
+        "template_name": "comic_bold_announcement",
+        "output_file": "comic_bold_announcement_test.svg"
+    },
+    {
+        "test_id": "comic_wavy_text",
+        "title_segments": "Get Ready for\nAdventure Time!",
+        "description": "Exciting outdoor activities for families",
+        "primary_color": "#9B59B6",
+        "background_color": "#FFFFFF",
+        "template_name": "comic_wavy_text",
+        "output_file": "comic_wavy_text_test.svg"
+    },
+    {
+        "test_id": "comic_mega_title",
+        "title_segments": "Ultimate Gaming Champions Tournament!",
+        "description": "Epic esports competition draws global audience",
+        "primary_color": "#2C3E50",
+        "background_color": "#FFFFFF",
+        "template_name": "comic_mega_title",
+        "output_file": "comic_mega_title_test.svg"
+    },
+    {
+        "test_id": "comic_sticker_style",
+        "title_segments": "AWESOME\nSpace Mission Success!",
+        "description": "Satellite deployment achieves perfect orbit",
+        "primary_color": "#27AE60",
+        "background_color": "#FAFAFA",
+        "template_name": "comic_sticker_style",
+        "output_file": "comic_sticker_style_test.svg"
+    },
+]
+
+
+def test_single_case(test_case):
+    """
+    Test a single problematic case
+    
+    Args:
+        test_case: Dictionary containing title_segments, description, colors, template_name, etc.
+    
+    Returns:
+        Result of the generation
+    """
+    print("\n" + "=" * 70)
+    print(f"Testing: {test_case['output_file']}")
+    print("=" * 70)
+    print(f"Title segments: {test_case['title_segments']}")
+    if len(test_case['description']) > 60:
+        print(f"Description: {test_case['description'][:60]}...")
+    else:
+        print(f"Description: {test_case['description']}")
+    print(f"Template: {test_case['template_name']}")
+    print(f"Primary Color: {test_case['primary_color']}")
+    print(f"Background Color: {test_case['background_color']}")
+    print("=" * 70)
+    
+    try:
+        results = generate_title(
+            title=test_case['title_segments'],  # Pass list of segments
+            description=test_case['description'],
+            primary_color=test_case['primary_color'],
+            background_color=test_case['background_color'],
+            template_name=test_case['template_name'],
+            max_width=900,
+            use_llm=False,  # Use specified template directly
+            save_to=f"output/{test_case['test_id']}"
+        )
+        
+        if results:
+            result = results[0]
+            print(f"✅ Successfully generated:")
+            print(f"   Template: {result['template_name']}")
+            print(f"   Size: {result['width']:.0f}px × {result['height']:.0f}px")
+            print(f"   Saved as: output/{test_case['output_file']}")
+            return True
+        else:
+            print(f"❌ Failed to generate")
+            return False
+            
+    except Exception as e:
+        print(f"❌ Error: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+
+if __name__ == "__main__":
+    import sys
+    
+    # Determine which test suite to run
+    if len(sys.argv) > 1 and sys.argv[1] == '--all':
+        test_suite = FULL_TEMPLATE_TEST_CASES
+        suite_name = "ALL TEMPLATES"
+    elif len(sys.argv) > 1 and sys.argv[1] == '--problematic':
+        test_suite = PROBLEMATIC_CASES
+        suite_name = "PROBLEMATIC CASES"
+    else:
+        # Default: run full template tests
+        test_suite = FULL_TEMPLATE_TEST_CASES
+        suite_name = "ALL TEMPLATES (DEFAULT)"
+        print("💡 Tip: Use '--problematic' to run only problematic cases")
+        print("💡 Tip: Use '--all' to explicitly run all template tests")
+        print()
+    
+    print("=" * 70)
+    print(f"TESTING {suite_name}")
+    print(f"Total cases to test: {len(test_suite)}")
+    print("=" * 70)
+    
+    success_count = 0
+    failed_count = 0
+    
+    for i, test_case in enumerate(test_suite, 1):
+        print(f"\n[{i}/{len(test_suite)}]")
+        
+        if test_single_case(test_case):
+            success_count += 1
+        else:
+            failed_count += 1
+            print(f"Failed: {test_case['output_file']}")
+    
+    # Summary
+    print("\n" + "=" * 70)
+    print("TEST SUMMARY")
+    print("=" * 70)
+    print(f"Total test cases: {len(test_suite)}")
+    print(f"✅ Successful: {success_count}")
+    print(f"❌ Failed: {failed_count}")
+    print("=" * 70)
+    
+    if failed_count > 0:
+        print("\n⚠️  Some tests failed. Please review the errors above.")
+    else:
+        print("\n✅ All tests passed!")
+    
+    print("=" * 70)
+
+

modules/title_styler/test_new_comics.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""
+测试新增的Comic模板
+"""
+
+from templates import get_templates_by_style
+
+def test_new_comic_templates():
+    """验证新增的comic模板"""
+    
+    print("="*60)
+    print("新Comic模板验证")
+    print("="*60)
+    
+    # 获取所有comic模板
+    comic_templates = get_templates_by_style('comic')
+    
+    print(f"\n总共有 {len(comic_templates)} 个Comic模板\n")
+    
+    # 新增的模板名称
+    new_templates = [
+        "comic_bold_announcement",
+        "comic_three_part_fun",
+        "comic_wavy_text",
+        "comic_explosion_box",
+        "comic_dotted_fun",
+        "comic_mega_title",
+        "comic_sticker_style"
+    ]
+    
+    print("新增的Comic模板:")
+    for i, name in enumerate(new_templates, 1):
+        # 查找模板
+        template = None
+        for t in comic_templates:
+            if t.name == name:
+                template = t
+                break
+        
+        if template:
+            print(f"\n{i}. ✅ {name}")
+            print(f"   描述: {template.description}")
+            print(f"   对齐: {template.alignment}")
+            
+            # 统计字体大小
+            if template.lines:
+                fonts = []
+                for line in template.lines:
+                    if hasattr(line, 'font_size'):
+                        fonts.append(f"{line.font_size}px")
+                if fonts:
+                    print(f"   字体大小: {', '.join(fonts)}")
+        else:
+            print(f"\n{i}. ❌ {name} - 未找到！")
+    
+    print("\n" + "="*60)
+    print("所有Comic模板列表:")
+    print("="*60)
+    for i, template in enumerate(comic_templates, 1):
+        is_new = "🆕" if template.name in new_templates else "  "
+        print(f"{is_new} {i:2d}. {template.name}")
+    
+    print("\n" + "="*60)
+    print(f"验证完成！共 {len(comic_templates)} 个Comic模板")
+    print(f"其中新增 {len([t for t in comic_templates if t.name in new_templates])} 个")
+    print("="*60)
+
+
+if __name__ == "__main__":
+    test_new_comic_templates()
+

modules/title_styler/test_new_title.py

@@ -0,0 +1,187 @@
+"""
+Test script for process() function
+Tests with various titles to validate the title processor
+"""
+
+from title_processor import process
+
+# Test cases
+TEST_CASES = [
+    # Comic style test cases
+    {
+        "test_id": "comic_discovery",
+        "input_data": {
+            "title": "Amazing Discovery in Science!",
+            "subtitle": "Breakthrough research findings that will change everything",
+            "primary_color": "#E74C3C",
+            "background_color": "#FFFFFF"
+        },
+        "style": "Comics",
+        "max_width": 800
+    },
+    {
+        "test_id": "comic_fun_facts",
+        "input_data": {
+            "title": "10 Fun Facts About Space Exploration",
+            "subtitle": "Cool things you didn't know about the cosmos",
+            "primary_color": "#3498DB",
+            "background_color": "#F0F0F0"
+        },
+        "style": "Comics",
+        "max_width": 700
+    },
+    
+    # Non-comic style test cases
+    {
+        "test_id": "professional_economy",
+        "input_data": {
+            "title": "Global Economic Growth Forecast for 2025",
+            "subtitle": "Analysis of GDP trends across major economies",
+            "primary_color": "#2E7D32",
+            "background_color": "#FFFFFF"
+        },
+        "style": "professional",
+        "max_width": 900
+    },
+    {
+        "test_id": "europe_cars",
+        "input_data": {
+            "title": "Europe's Best-Selling Car Brands in H1 2025",
+            "subtitle": "This visualization shows the best-selling car brands in Europe",
+            "primary_color": "#1E5BBD",
+            "background_color": "#E8E8E8"
+        },
+        "style": "normal",
+        "max_width": 850
+    },
+    {
+        "test_id": "quality_life",
+        "input_data": {
+            "title": "How Quality of Life Has Changed in 30 Countries",
+            "subtitle": "Citizens' perceptions of changes in their country's quality of life",
+            "primary_color": "#E74C3C",
+            "background_color": "#F5F5F5"
+        },
+        "style": "normal",
+        "max_width": 900
+    },
+    {
+        "test_id": "carbon_emissions",
+        "input_data": {
+            "title": "Global Carbon Emissions by Sector",
+            "subtitle": "Breaking down CO2 emissions from energy, transportation, industry, and agriculture",
+            "primary_color": "#27AE60",
+            "background_color": "#FFFFFF"
+        },
+        "style": "professional",
+        "max_width": 800
+    },
+    {
+        "test_id": "tech_companies",
+        "input_data": {
+            "title": "America's Largest Technology Companies",
+            "subtitle": "Market capitalization comparison of leading tech firms",
+            "primary_color": "#8E44AD",
+            "background_color": "#F5F5F5"
+        },
+        "style": "normal",
+        "max_width": 850
+    },
+    {
+        "test_id": "renewable_energy",
+        "input_data": {
+            "title": "Renewable Energy Share of Total Electricity Generation",
+            "subtitle": "Tracking solar, wind, hydro, and other renewable sources by country",
+            "primary_color": "#16A085",
+            "background_color": "#ECF0F1"
+        },
+        "style": "professional",
+        "max_width": 900
+    },
+]
+
+
+def test_single_case(test_case):
+    """
+    Test process() function for a single case
+    
+    Args:
+        test_case: Dictionary containing test_id, input_data, style, max_width
+    
+    Returns:
+        True if successful, False otherwise
+    """
+    test_id = test_case['test_id']
+    input_data = test_case['input_data']
+    style = test_case['style']
+    max_width = test_case['max_width']
+    output_file = f"output/{test_id}_process_test.svg"
+    
+    print(f"\n{'='*70}")
+    print(f"TEST: {test_id}")
+    print(f"{'='*70}")
+    print(f"Title: {input_data['title']}")
+    print(f"Style: {style}")
+    print(f"Max Width: {max_width}px")
+    print(f"{'='*70}")
+    
+    try:
+        svg_content = process(
+            input_data=input_data,
+            output=output_file,
+            max_width=max_width,
+            text_align="center",
+            show_sub_title=True,
+            style=style
+        )
+        
+        if svg_content:
+            print(f"✅ Success: SVG generated ({len(svg_content)} chars)")
+            return True
+        else:
+            print(f"❌ Failed: process() returned None")
+            return False
+            
+    except Exception as e:
+        print(f"❌ Error: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+
+if __name__ == "__main__":
+    print("=" * 70)
+    print("PROCESS() FUNCTION TEST")
+    print(f"Testing {len(TEST_CASES)} cases")
+    print("=" * 70)
+    
+    success_count = 0
+    failed_count = 0
+    
+    for i, test_case in enumerate(TEST_CASES, 1):
+        print(f"\n[{i}/{len(TEST_CASES)}]")
+        
+        success = test_single_case(test_case)
+        if success:
+            success_count += 1
+        else:
+            failed_count += 1
+    
+    # Summary
+    print("\n" + "=" * 70)
+    print("TEST SUMMARY")
+    print("=" * 70)
+    print(f"Total test cases: {len(TEST_CASES)}")
+    print(f"✅ Successful: {success_count}")
+    print(f"❌ Failed: {failed_count}")
+    print(f"Success rate: {success_count/len(TEST_CASES)*100:.1f}%")
+    print("=" * 70)
+    
+    if success_count == len(TEST_CASES):
+        print("\n🎉 All tests passed!")
+    elif success_count > 0:
+        print(f"\n⚠️  {failed_count} test(s) failed")
+    else:
+        print("\n❌ All tests failed")
+    
+    print("\n" + "=" * 70)

modules/title_styler/title_styler.py

@@ -0,0 +1,502 @@
+"""
+Title Processor - 包装接口
+为title generation提供统一的处理接口
+"""
+
+import json
+import re
+import argparse
+from typing import Dict, Union, Optional, List
+from modules.title_styler.infographic_title_generator import InfographicTitleGenerator
+from modules.title_styler.templates import get_all_templates
+
+
+def _scale_svg_to_fit(svg_content: str, original_width: float, original_height: float, 
+                      max_width: int, template_name: str) -> str:
+    """
+    Scale SVG content to fit within max_width.
+    
+    Args:
+        svg_content: Original SVG string
+        original_width: Original width
+        original_height: Original height
+        max_width: Target max width
+        template_name: Template name for logging
+    
+    Returns:
+        Scaled SVG string
+    """
+    # Calculate scale factor to fit within max_width
+    scale = max_width / original_width
+    
+    # Find the SVG tag
+    svg_pattern = r'<svg[^>]*>'
+    svg_match = re.search(svg_pattern, svg_content)
+    svg_tag = svg_match.group(0)
+    
+    # Calculate new dimensions
+    new_width = original_width * scale
+    new_height = original_height * scale
+    
+    # Update width and height in SVG tag
+    new_svg_tag = re.sub(r'width="[^"]*"', f'width="{new_width:.0f}"', svg_tag)
+    new_svg_tag = re.sub(r'height="[^"]*"', f'height="{new_height:.0f}"', new_svg_tag)
+    
+    # Replace the SVG tag
+    svg_content = svg_content.replace(svg_tag, new_svg_tag)
+    
+    # Add scale transform to all content
+    svg_tag_end = svg_content.find('>', svg_content.find('<svg')) + 1
+    before = svg_content[:svg_tag_end]
+    after = svg_content[svg_tag_end:]
+    
+    # Wrap remaining content in scaled group
+    closing_svg = '</svg>'
+    closing_pos = after.rfind(closing_svg)
+    content = after[:closing_pos]
+    svg_content = f'{before}<g transform="scale({scale:.4f})">{content}</g>{closing_svg}'
+    
+    print(f"✅ 生成完成 (缩放 {scale:.2f}x): {template_name} ({new_width:.0f}x{new_height:.0f}px)")
+    
+    return svg_content
+
+
+def _build_meta_from_result(result: Dict, scaled: bool = False, scale: float = 1.0) -> Dict:
+    """Extract a JSON-serialisable metadata bundle from a generator result.
+    Caller can persist this in info.json so the rendered title is fully
+    reproducible without re-running the LLM/styler."""
+    return {
+        'template_name': result.get('template_name'),
+        'template_description': result.get('template_description'),
+        'alignment': result.get('alignment'),
+        'width': result.get('width'),
+        'height': result.get('height'),
+        'segments': result.get('segments') or [],
+        'split_method': result.get('split_method'),
+        'primary_color': result.get('primary_color'),
+        'secondary_color': result.get('secondary_color'),
+        'background_color': result.get('background_color'),
+        'scaled_to_fit': bool(scaled),
+        'scale_factor': scale,
+    }
+
+
+def _select_best_result(results: List[Dict], max_width: int, min_scale: float = 0.6,
+                        return_meta: bool = False):
+    """
+    Select the best result from a list of results based on max_width constraint.
+
+    Args:
+        results: List of result dicts with 'width', 'height', 'svg', 'template_name'
+        max_width: Maximum width constraint
+        min_scale: Minimum acceptable scale factor (default 0.6). Results requiring
+                   smaller scale will be discarded.
+        return_meta: When True, return ``(svg_str, meta_dict)`` instead of bare SVG
+                     string. Backward-compatible default keeps the old contract.
+
+    Returns:
+        - return_meta=False (default): Best SVG content string, or None
+        - return_meta=True: ``(svg_str_or_None, meta_dict_or_None)``
+    """
+    # Filter results that fit within max_width
+    valid_results = [r for r in results if r['width'] <= max_width]
+
+    if not valid_results:
+        # Use the result with smallest width and scale it to fit max_width
+        best_result = min(results, key=lambda x: x['width'])
+        scale = max_width / best_result['width']
+
+        # Discard if scale is too small
+        if scale < min_scale:
+            print(f"⚠️ 丢弃结果: {best_result['template_name']} 需要缩放 {scale:.2f}x (< {min_scale})")
+            return (None, None) if return_meta else None
+
+        svg = _scale_svg_to_fit(
+            best_result['svg'],
+            best_result['width'],
+            best_result['height'],
+            max_width,
+            best_result['template_name']
+        )
+        if return_meta:
+            return svg, _build_meta_from_result(best_result, scaled=True, scale=scale)
+        return svg
+    else:
+        # Select the result with largest width that fits
+        best_result = max(valid_results, key=lambda x: x['width'])
+        print(f"✅ 生成完成: {best_result['template_name']} ({best_result['width']:.0f}x{best_result['height']:.0f}px)")
+        if return_meta:
+            return best_result['svg'], _build_meta_from_result(best_result)
+        return best_result['svg']
+
+
+def process(
+    input: str = None,
+    output: str = None,
+    input_data: Dict = None,
+    max_width: int = 500,
+    text_align: str = "left",
+    background_color: str = "#FFFFFF",
+    dark: bool = False,
+    show_embellishment: bool = True,
+    show_sub_title: bool = True,
+    font_family: str = None,
+    return_meta: bool = False,
+):
+    """
+    Process function for generating styled title SVG from input data.
+
+    Args:
+        input (str, optional): Path to the input JSON file.
+        output (str, optional): Path to the output SVG file (if provided, will save to file).
+        input_data (Dict, optional): Input data dictionary (alternative to file input).
+        max_width (int, optional): Maximum width constraint for the title. Defaults to 500.
+        text_align (str, optional): Text alignment. Options: "left", "center", "right". Defaults to "left".
+        background_color (str, optional): Background color. Defaults to "#FFFFFF".
+        dark (bool, optional): Whether to use dark mode. Defaults to False.
+        show_embellishment (bool, optional): Whether to show embellishments (currently unused). Defaults to True.
+        show_sub_title (bool, optional): Whether to show the subtitle. Defaults to True.
+        font_family (str, optional): Font family override (currently unused). Defaults to None.
+        style (str, optional): Title style: normal, comic, simple, professional, all. Defaults to "normal".
+
+    Returns:
+        str: Always returns the generated SVG content as a string.
+             If output path is provided, also saves to file.
+    
+    Input JSON Format:
+        {
+            "title": "Main title text",
+            "subtitle": "Subtitle text (optional)",
+            "primary_color": "#2E7D32",
+            "secondary_color": "#4CAF50",
+            "background_color": "#FFFFFF"
+        }
+    """
+    try:
+        # Load the data object
+        if input_data is None:
+            if input is None:
+                print("❌ Error: Either input file path or input_data must be provided")
+                return None
+            with open(input, 'r', encoding='utf-8') as f:
+                data = json.load(f)
+        else:
+            data = input_data
+
+        # Extract data fields
+        title = data.get('titles').get('main_title')
+        if not title:
+            print("❌ Error: 'title' field is required in input data")
+            return None
+        
+        subtitle = data.get('titles').get('sub_title') if show_sub_title else None
+        if not dark:
+            primary_color = data.get('colors').get('other').get('primary')
+            secondary_color = data.get('colors').get('other').get('secondary')
+        else:
+            primary_color = data.get('colors_dark').get('other').get('primary')
+            secondary_color = data.get('colors_dark').get('other').get('secondary')
+        
+        # Handle style parameter: map "Comics" to "comic", otherwise filter out comic templates
+        if font_family == "Comics":
+            filter_mode = "comic_only"
+        else:
+            filter_mode = "non_comic"
+        
+        # Create generator with custom template filtering
+        all_templates = get_all_templates()
+        
+        if filter_mode == "comic_only":
+            # Only use comic templates
+            filtered_templates = [t for t in all_templates if t.style == 'comic']
+        else:
+            # Use all non-comic templates
+            filtered_templates = [t for t in all_templates if t.style != 'comic']
+        
+        if not filtered_templates:
+            print("❌ Error: No templates available after filtering")
+            return None
+        
+        # Create generator instance
+        generator = InfographicTitleGenerator(use_llm=True)
+        # Override templates with filtered ones
+        generator.templates = filtered_templates
+        
+        # Generate title with LLM, top_k=1
+        results = generator.generate(
+            title=title,
+            description=subtitle,
+            primary_color=primary_color,
+            secondary_color=secondary_color,
+            background_color=background_color,
+            max_width=max_width,
+            alignment=text_align,
+            top_k=1,
+            style="comic" if filter_mode == "comic_only" else None
+        )
+        
+        if not results:
+            print("❌ Error: No results generated")
+            return (None, None) if return_meta else None
+
+        # Select best result based on max_width constraint
+        if return_meta:
+            svg_content, meta = _select_best_result(results, max_width, return_meta=True)
+        else:
+            svg_content = _select_best_result(results, max_width)
+            meta = None
+
+        # Output handling: save to file if output path is provided
+        if output and svg_content:
+            with open(output, 'w', encoding='utf-8') as f:
+                f.write(svg_content)
+            print(f"   保存: {output}")
+
+        if return_meta:
+            return svg_content, meta
+        return svg_content
+
+    except FileNotFoundError as e:
+        print(f"❌ Error: Input file not found: {e}")
+        return (None, None) if return_meta else None
+    except json.JSONDecodeError as e:
+        print(f"❌ Error: Invalid JSON format: {e}")
+        return (None, None) if return_meta else None
+    except Exception as e:
+        print(f"❌ Error in title styling: {str(e)}")
+        import traceback
+        traceback.print_exc()
+        return (None, None) if return_meta else None
+
+
+def process_batch(
+    input: str = None,
+    input_data: Dict = None,
+    max_widths: List[int] = None,
+    text_align: str = "left",
+    background_color: str = "#FFFFFF",
+    dark: bool = False,
+    show_embellishment: bool = True,
+    show_sub_title: bool = True,
+    font_family: str = None,
+    return_meta: bool = False,
+):
+    """
+    Batch process function for generating styled title SVGs with multiple widths.
+    This function calls LLM only once and generates SVGs for each width.
+    
+    Args:
+        input (str, optional): Path to the input JSON file.
+        input_data (Dict, optional): Input data dictionary (alternative to file input).
+        max_widths (List[int]): List of maximum width constraints for the titles.
+        text_align (str, optional): Text alignment. Options: "left", "center", "right". Defaults to "left".
+        background_color (str, optional): Background color. Defaults to "#FFFFFF".
+        dark (bool, optional): Whether to use dark mode. Defaults to False.
+        show_embellishment (bool, optional): Whether to show embellishments (currently unused). Defaults to True.
+        show_sub_title (bool, optional): Whether to show the subtitle. Defaults to True.
+        font_family (str, optional): Font family override. Defaults to None.
+    
+    Returns:
+        List[str]: List of SVG content strings, one for each max_width in max_widths.
+                   Order matches the order of max_widths.
+    """
+    if max_widths is None or len(max_widths) == 0:
+        print("❌ Error: max_widths must be provided and non-empty")
+        return []
+    
+    try:
+        # Load the data object
+        if input_data is None:
+            if input is None:
+                print("❌ Error: Either input file path or input_data must be provided")
+                return []
+            with open(input, 'r', encoding='utf-8') as f:
+                data = json.load(f)
+        else:
+            data = input_data
+
+        # Extract data fields
+        title = data.get('titles').get('main_title')
+        if not title:
+            print("❌ Error: 'title' field is required in input data")
+            return []
+        
+        subtitle = data.get('titles').get('sub_title') if show_sub_title else None
+        if not dark:
+            primary_color = data.get('colors').get('other').get('primary')
+            secondary_color = data.get('colors').get('other').get('secondary')
+        else:
+            primary_color = data.get('colors_dark').get('other').get('primary')
+            secondary_color = data.get('colors_dark').get('other').get('secondary')
+        
+        # Handle style parameter: map "Comics" to "comic", otherwise filter out comic templates
+        if font_family == "Comics":
+            filter_mode = "comic_only"
+        else:
+            filter_mode = "non_comic"
+        
+        # Create generator with custom template filtering
+        all_templates = get_all_templates()
+        
+        if filter_mode == "comic_only":
+            filtered_templates = [t for t in all_templates if t.style == 'comic']
+        else:
+            filtered_templates = [t for t in all_templates if t.style != 'comic']
+        
+        if not filtered_templates:
+            print("❌ Error: No templates available after filtering")
+            return []
+        
+        # Create generator instance
+        generator = InfographicTitleGenerator(use_llm=True)
+        generator.templates = filtered_templates
+        
+        # Step 1: Analyze title with LLM (only once)
+        analysis_result = generator.analyze_title(
+            title=title,
+            description=subtitle,
+            primary_color=primary_color,
+            background_color=background_color,
+            alignment=text_align,
+            top_k=1,
+            style="comic" if filter_mode == "comic_only" else None
+        )
+        
+        if not analysis_result:
+            print("❌ Error: Title analysis failed")
+            return []
+        
+        # Step 2: Generate SVGs for each width (no LLM calls)
+        results = generator.generate_with_analysis(
+            analysis_result=analysis_result,
+            max_widths=max_widths,
+            secondary_color=secondary_color
+        )
+        
+        if not results:
+            print("❌ Error: No results generated")
+            return []
+        
+        # Step 3: Post-process results - match each max_width to best result
+        # Results are ordered by max_widths, so we can process each
+        svg_contents = []
+        metas = []
+
+        # Create a mapping from requested max_width to results
+        results_by_max_width = {}
+        for result in results:
+            req_width = result.get('max_width_requested')
+            if req_width not in results_by_max_width:
+                results_by_max_width[req_width] = []
+            results_by_max_width[req_width].append(result)
+
+        for max_width in max_widths:
+            if max_width in results_by_max_width:
+                width_results = results_by_max_width[max_width]
+                if return_meta:
+                    svg_content, meta = _select_best_result(width_results, max_width, return_meta=True)
+                else:
+                    svg_content = _select_best_result(width_results, max_width)
+                    meta = None
+            else:
+                # No result for this width — use closest fit + scale.
+                all_results_list = [r for r in results]
+                if all_results_list:
+                    if return_meta:
+                        svg_content, meta = _select_best_result(all_results_list, max_width, return_meta=True)
+                    else:
+                        svg_content = _select_best_result(all_results_list, max_width)
+                        meta = None
+                else:
+                    svg_content = None
+                    meta = None
+            svg_contents.append(svg_content)
+            metas.append(meta)
+
+        if return_meta:
+            return list(zip(svg_contents, metas))
+        return svg_contents
+
+    except FileNotFoundError as e:
+        print(f"❌ Error: Input file not found: {e}")
+        return []
+    except json.JSONDecodeError as e:
+        print(f"❌ Error: Invalid JSON format: {e}")
+        return []
+    except Exception as e:
+        print(f"❌ Error in title styling: {str(e)}")
+        import traceback
+        traceback.print_exc()
+        return []
+
+
+def main():
+    """命令行接口"""
+    parser = argparse.ArgumentParser(
+        description='Generate styled title SVG for a chart',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Generate with default settings
+  python title_processor.py -i input.json -o output.svg
+  
+  # Generate with specific style and width
+  python title_processor.py -i input.json -o output.svg --style comic --max-width 600
+  
+  # Generate without subtitle
+  python title_processor.py -i input.json -o output.svg --no-subtitle
+  
+  # Generate with center alignment
+  python title_processor.py -i input.json -o output.svg --text-align center
+
+Input JSON format:
+  {
+    "title": "Your Title Here",
+    "subtitle": "Optional subtitle",
+    "primary_color": "#2E7D32",
+    "secondary_color": "#4CAF50",
+    "background_color": "#FFFFFF"
+  }
+        """
+    )
+    
+    parser.add_argument('--input', '-i', type=str, required=True, 
+                        help='Input JSON file path')
+    parser.add_argument('--output', '-o', type=str, 
+                        help='Output SVG file path')
+    parser.add_argument('--max-width', '-w', type=int, default=500, 
+                        help='Maximum width constraint for the title (default: 500)')
+    parser.add_argument('--text-align', '-a', type=str, default='left', 
+                        choices=['left', 'center', 'right'],
+                        help='Text alignment: left, center, or right (default: left)')
+    parser.add_argument('--no-subtitle', action='store_true', 
+                        help='Hide the subtitle')
+    parser.add_argument('--style', '-s', type=str, default='normal',
+                        choices=['normal', 'comic', 'simple', 'professional', 'all'],
+                        help='Title style (default: normal)')
+    
+    args = parser.parse_args()
+    
+    svg_content = process(
+        input=args.input,
+        output=args.output,
+        max_width=args.max_width,
+        text_align=args.text_align,
+        show_sub_title=not args.no_subtitle,
+        style=args.style
+    )
+    
+    if svg_content:
+        if args.output:
+            print("\n✅ Title styling completed successfully.")
+        else:
+            # If no output file, print SVG to stdout
+            print(svg_content)
+    else:
+        print("\n❌ Title styling failed.")
+        exit(1)
+
+
+if __name__ == '__main__':
+    main()
+

modules/title_styler/title_styler_basic.py

@@ -0,0 +1,523 @@
+from typing import Dict, Union
+import json
+from PIL import Image, ImageDraw, ImageFont
+import argparse
+
+def merge_bounding_boxes(bounding_boxes):
+    """合并所有有实际文字内容的boundingbox"""
+    min_x = min(box['x'] for box in bounding_boxes)
+    min_y = min(box['y'] for box in bounding_boxes)
+    max_x = max(box['x'] + box['width'] for box in bounding_boxes)
+    max_y = max(box['y'] + box['height'] for box in bounding_boxes)
+    ascent = max(box['ascent'] for box in bounding_boxes)
+    descent = min(box['descent'] for box in bounding_boxes)
+    return {
+        'x': min_x,
+        'y': min_y,
+        'width': max_x - min_x,
+        'height': max_y - min_y,
+        'ascent': ascent,
+        'descent': descent
+    }
+
+def measure_text_bounds(text, font_family, font_size, font_weight="normal"):
+    """测量文本的边界框尺寸"""
+    # 创建临时图像用于测量文本
+    img = Image.new('RGB', (1, 1), color=(255, 255, 255))
+    draw = ImageDraw.Draw(img)
+    
+    # 获取字体
+    font = get_font(font_family, font_size, font_weight)
+    
+    # 获取文本尺寸
+    left, top, right, bottom = draw.textbbox((0, 0), text, font=font)
+    width = right - left
+    height = bottom - top
+    
+    result = {
+        'width': width,
+        'height': height,
+        'min_x': left,
+        'min_y': top,
+        'max_x': right,
+        'max_y': bottom
+    }
+    
+    return result
+
+def get_font(font_family, font_size, font_weight="normal"):
+    """获取字体对象，处理各种字体格式和降级情况"""
+    # 处理特殊字体名称
+    if font_family and font_family.lower() == 'comics':
+        font_family = 'Comic Sans MS, cursive'
+    
+    # 从字体大小中提取数字部分
+    if isinstance(font_size, str):
+        font_size = int(font_size.replace('px', ''))
+    
+    try:
+        # 首先尝试加载系统字体
+        if font_weight == "bold":
+            font = ImageFont.truetype(font_family, size=font_size, weight="bold")
+        else:
+            font = ImageFont.truetype(font_family, size=font_size)
+    except (OSError, IOError):
+        try:
+            # 如果直接加载失败，尝试一些常见的系统字体
+            system_fonts = {
+                'Arial': '/usr/share/fonts/truetype/msttcorefonts/Arial.ttf',
+                'Times': '/usr/share/fonts/truetype/msttcorefonts/Times_New_Roman.ttf',
+                'Courier': '/usr/share/fonts/truetype/msttcorefonts/Courier_New.ttf',
+                'Verdana': '/usr/share/fonts/truetype/msttcorefonts/Verdana.ttf',
+                'Comic': '/usr/share/fonts/truetype/msttcorefonts/Comic_Sans_MS.ttf',
+                'Default': '/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf'
+            }
+            
+            # 尝试匹配字体名称
+            for name, path in system_fonts.items():
+                if name.lower() in font_family.lower():
+                    font = ImageFont.truetype(path, size=font_size)
+                    return font
+            
+            # 如果没有匹配，使用默认字体
+            font = ImageFont.truetype(system_fonts['Default'], size=font_size)
+        except (OSError, IOError):
+            # 如果所有尝试都失败，使用PIL的默认字体并尝试调整大小
+            default_font = ImageFont.load_default()
+            
+            # PIL的默认字体不支持调整大小，所以我们必须警告用户
+            print(f"警告: 无法加载指定字体和大小 '{font_family}', {font_size}px。使用默认字体。")
+            font = default_font
+    
+    return font
+
+def split_text_into_lines(text, max_width, font_family="Arial", font_size=16, font_weight="normal"):
+    """将文本按照给定的宽度限制拆分成多行"""
+    # 创建临时图像用于测量文本宽度
+    img = Image.new('RGB', (1, 1), color=(255, 255, 255))
+    draw = ImageDraw.Draw(img)
+    
+    # 获取字体
+    font = get_font(font_family, font_size, font_weight)
+    
+    lines = []
+    
+    # 检测是否包含中文字符
+    has_chinese = any('\u4e00' <= char <= '\u9fff' for char in text)
+    
+    if has_chinese:
+        # 中文文本按字符切分
+        current_line = ("", 0)
+        for char in text:
+            test_line = current_line[0] + char
+            # 获取文本宽度
+            text_width = draw.textlength(test_line, font=font)
+            
+            if text_width <= max_width:
+                current_line = (test_line, text_width)
+            else:
+                lines.append(current_line)
+                current_line = (char, draw.textlength(char, font=font))
+        
+        # 添加最后一行
+        if current_line:
+            lines.append(current_line)
+    else:
+        # 英文文本按单词切分
+        words = text.split()
+        current_line = ("", 0)
+        
+        for word in words:
+            # 测试添加这个单词后是否超出宽度
+            test_line = current_line[0] + (" " if current_line[0] else "") + word
+            text_width = draw.textlength(test_line, font=font)
+            if text_width <= max_width:
+                current_line = (test_line, text_width)
+            else:
+                if current_line:
+                    lines.append(current_line)
+                current_line = (word, draw.textlength(word, font=font))
+                
+                # 检查单个单词是否超过最大宽度
+                if draw.textlength(word, font=font) > max_width:
+                    # 如果单个单词就超过宽度，则需要逐字分割
+                    word_line = ""
+                    for char in word:
+                        test_word_line = word_line + char
+                        if draw.textlength(test_word_line, font=font) <= max_width:
+                            word_line = test_word_line
+                        else:
+                            word_line = word_line + "-"
+                            lines.append((word_line, draw.textlength(word_line, font=font)))
+                            word_line = char
+                    
+                    if word_line:
+                        current_line = (word_line, draw.textlength(word_line, font=font))
+                        if current_line not in lines:
+                            lines.append(current_line)
+                            current_line = ("", 0)
+        
+        # 添加最后一行
+        if current_line:
+            lines.append(current_line)
+    
+    # 确保至少有一行
+    if not lines:
+        lines = [(text, draw.textlength(text, font=font))]
+            
+    return lines
+
+class TitleGenerator:
+    def __init__(self, json_data: Dict, max_width = 0, text_align = "left", show_embellishment = True, show_sub_title = True, font_family = None):
+        self.json_data = json_data
+        self.max_width = max_width
+        self.text_align = text_align  # 保留接口，但内部只实现左对齐
+        self.show_embellishment = show_embellishment
+        self.show_sub_title = show_sub_title
+        self.font_family = font_family
+
+    def generate(self):
+        self.main_title_svg, self.main_title_bounding_box = self.generate_main_title()
+        if self.show_sub_title:
+            self.description_svg, self.description_bounding_box = self.generate_description()
+        else:
+            self.description_svg = ""
+            self.description_bounding_box = {
+                'width': 0, 'height': 0,
+                'min_x': 0, 'min_y': 0,
+                'max_x': 0, 'max_y': 0
+            }
+        primary_color = self.json_data['colors']['other']['primary']
+        
+        if self.show_embellishment:
+            self.embellishment_svg, self.embellishment_bounding_box = self.generate_embellishment(primary_color)
+        else:
+            # 创建空的装饰块，不会显示在最终结果中
+            self.embellishment_svg = ""
+            self.embellishment_bounding_box = {
+                'width': 0, 'height': 0,
+                'min_x': 0, 'min_y': 0,
+                'max_x': 0, 'max_y': 0
+            }
+            
+        return self.composite()
+
+    def composite(self):
+        if self.show_sub_title:
+            description_shift_y = self.main_title_bounding_box['max_y'] + 15 - self.main_title_bounding_box['min_y']
+            description_shift_x = self.description_bounding_box['min_x'] - self.main_title_bounding_box['min_x']
+
+            if self.text_align == "right":
+                title_width = self.main_title_bounding_box['max_x'] - self.main_title_bounding_box['min_x']
+                description_width = self.description_bounding_box['max_x'] - self.description_bounding_box['min_x']
+                description_shift_x = title_width - description_width
+            
+            description_transform = f'translate({0}, {description_shift_y})'
+            self.description_svg = self.description_svg.replace('transform="', f'transform="{description_transform} ')
+            self.description_bounding_box['min_x'] += 0
+            self.description_bounding_box['min_y'] += description_shift_y
+            self.description_bounding_box['max_x'] += 0
+            self.description_bounding_box['max_y'] += description_shift_y
+        
+        # 如果显示装饰块，调整其位置和大小
+        if self.show_embellishment:
+            new_height = self.description_bounding_box['max_y'] - self.main_title_bounding_box['min_y']
+            old_height = self.embellishment_bounding_box['height']
+            old_width = self.embellishment_bounding_box['width']
+            scale = new_height / old_height
+            new_width = old_width * scale
+            
+            # 装饰块在左边
+            embellishment_shift_x = self.main_title_bounding_box['min_x'] - self.embellishment_bounding_box['min_x'] - new_width - 15
+            embellishment_shift_y = self.main_title_bounding_box['min_y'] - self.embellishment_bounding_box['min_y']
+            
+            # 通过添加transform属性，调整embellishment_svg的���置
+            embellishment_transform = f'translate({embellishment_shift_x}, {embellishment_shift_y})'
+            self.embellishment_svg = self.embellishment_svg.replace('transform="', f'transform="{embellishment_transform} ')
+            self.embellishment_bounding_box['min_x'] += embellishment_shift_x
+            self.embellishment_bounding_box['min_y'] += embellishment_shift_y
+            self.embellishment_bounding_box['max_x'] += embellishment_shift_x
+            self.embellishment_bounding_box['max_y'] += embellishment_shift_y
+            
+            old_width_text = self.embellishment_svg.split('width="')[1].split('"')[0]
+            old_height_text = self.embellishment_svg.split('height="')[1].split('"')[0]
+            new_width_text = str(int(float(old_width_text) * scale))
+            new_height_text = str(int(float(old_height_text) * scale))
+           
+            # 通过修改width和height，调整embellishment_svg的大小
+            self.embellishment_svg = self.embellishment_svg.replace(old_width_text, new_width_text)
+            self.embellishment_svg = self.embellishment_svg.replace(old_height_text, new_height_text)
+            
+            # Update embellishment bounding box with new dimensions after scaling
+            self.embellishment_bounding_box['width'] = float(new_width_text)
+            self.embellishment_bounding_box['height'] = float(new_height_text)
+            self.embellishment_bounding_box['max_x'] = self.embellishment_bounding_box['min_x'] + float(new_width_text)
+            self.embellishment_bounding_box['max_y'] = self.embellishment_bounding_box['min_y'] + float(new_height_text)
+        
+        # 计算整体边界框
+        min_x = min(
+            self.main_title_bounding_box['min_x'], 
+            self.description_bounding_box['min_x'] if self.show_sub_title else float('inf'),
+            self.embellishment_bounding_box['min_x'] if self.show_embellishment else float('inf')
+        )
+        min_y = min(
+            self.main_title_bounding_box['min_y'], 
+            self.description_bounding_box['min_y'] if self.show_sub_title else float('inf'),
+            self.embellishment_bounding_box['min_y'] if self.show_embellishment else float('inf')
+        )
+        max_x = max(
+            self.main_title_bounding_box['max_x'], 
+            self.description_bounding_box['max_x'] if self.show_sub_title else float('-inf'),
+            self.embellishment_bounding_box['max_x'] if self.show_embellishment else float('-inf')
+        )
+        max_y = max(
+            self.main_title_bounding_box['max_y'], 
+            self.description_bounding_box['max_y'] if self.show_sub_title else float('-inf'),
+            self.embellishment_bounding_box['max_y'] if self.show_embellishment else float('-inf')
+        )
+        
+        group_left = f'<g class="title" transform="translate({-min_x}, {-min_y})">'
+        group_right = '</g>'
+        svg_left = f'<svg xmlns="http://www.w3.org/2000/svg" width="{max_x - min_x}" height="{max_y - min_y}" viewBox="0 0 {max_x - min_x} {max_y - min_y}">'
+        svg_right = '</svg>'
+        svg_content = svg_left + group_left + self.embellishment_svg + self.main_title_svg + self.description_svg + group_right + svg_right 
+            
+        final_bounding_box = {
+            'width': max_x - min_x,
+            'height': max_y - min_y,
+            'min_x': 0,
+            'min_y': 0,
+            'max_x': max_x - min_x,
+            'max_y': max_y - min_y
+        }
+        
+        return svg_content, final_bounding_box
+
+    def generate_text_element(self, text: str, typography: Dict, max_width: int = 0, text_align: str = "left"):
+        """生成文本元素，包括SVG和边界框"""
+        text_svg = self.generate_one_line_text(typography, text, max_width, text_align)
+        
+        # 使用PIL直接测量文本尺寸
+        font_family = typography.get('font_family', 'Arial')
+        if self.font_family:  # 如果全局字体被设置，优先使用全局字体
+            font_family = self.font_family
+        # 如果字体是comics，自动转换为Comic Sans MS, cursive
+        if font_family and font_family.lower() == 'comics':
+            font_family = 'Comic Sans MS, cursive'
+        font_size = typography.get('font_size', '16px')
+        font_weight = typography.get('font_weight', 'normal')
+        
+        bounding_box = measure_text_bounds(text, font_family, font_size, font_weight)
+        
+        # 检查是否超出最大宽度，并且生成多行文本
+        if max_width > 0 and bounding_box['width'] > max_width:
+            text_svg, bounding_box = self.generate_multi_line_text(typography, text, max_width, text_align)
+        
+        return text_svg, bounding_box
+
+    def generate_main_title(self):
+        """生成主标题"""
+        main_title_text = self.json_data['titles']['main_title']
+        typography = self.json_data['typography']['title']
+        return self.generate_text_element(main_title_text, typography, self.max_width, self.text_align)
+
+    def generate_description(self):
+        """生成描述文本"""
+        description_text = self.json_data['titles']['sub_title']
+        typography = self.json_data['typography']['description']
+        return self.generate_text_element(description_text, typography, self.max_width, self.text_align)
+
+    def generate_embellishment(self, color = '#000000'):
+        rect = f'<rect x="0" y="0" width="15" height="150" fill="{color}" transform="translate(0, 0)"></rect>'
+        bounding_box = {
+            'width': 15,
+            'height': 150,
+            'min_x': 0,
+            'min_y': 0,
+            'max_x': 15,
+            'max_y': 150
+        }
+        return rect, bounding_box
+
+    def generate_one_line_text(self, typography: Dict, text: str, max_width: int = 0, text_align: str = "left"):
+        font_family = typography.get('font_family', 'Arial')
+        if self.font_family:  # 如果全局字体被设置，优先使用全局字体
+            font_family = self.font_family
+        # 如果字体是comics，自动转换为Comic Sans MS, cursive
+        if font_family and font_family.lower() == 'comics':
+            font_family = 'Comic Sans MS, cursive'
+        font_size = typography.get('font_size', '16px')
+        font_weight = typography.get('font_weight', 'normal')
+        
+        text_anchor = "start"
+        x = 0
+        if text_align == "center":
+            text_anchor = "middle"
+            x = max_width / 2
+        elif text_align == "right":
+            text_anchor = "end"
+            x = max_width
+        text_left = f'<text dominant-baseline="hanging" text-anchor="{text_anchor}" style="font-family: {font_family}; font-size: {font_size}; font-weight: {font_weight};" \
+            transform="translate({x}, 0)">'
+        text_right = '</text>'
+        return text_left + text + text_right
+
+    def generate_multi_line_text(self, typography: Dict, text: str, max_width: int, text_align: str = "left"):
+        """生成多行文本，确保每行不超过最大宽度"""
+        font_family = typography.get('font_family', 'Arial')
+        if self.font_family:  # 如果全局字体被设置，优先使用全局字体
+            font_family = self.font_family
+        # 如果字体是comics，自动转换为Comic Sans MS, cursive
+        if font_family and font_family.lower() == 'comics':
+            font_family = 'Comic Sans MS, cursive'
+        font_size = typography.get('font_size', '16px')
+        font_weight = typography.get('font_weight', 'normal')
+        
+        # 使用拆分文本函数获取多行
+        lines = split_text_into_lines(text, max_width, font_family, font_size, font_weight)
+        
+        # 生成多行SVG
+        if isinstance(font_size, str):
+            font_size_px = int(font_size.replace('px', ''))
+        else:
+            font_size_px = font_size
+            
+        line_height = font_size_px * 1.2  # 行高约为字体大小的1.2倍
+        g_left = '<g>'
+        text_content = ""
+
+        text_anchor = "start"
+        if text_align == "center":
+            text_anchor = "middle"
+        elif text_align == "right":
+            text_anchor = "end"
+        
+        for i, (line, line_width) in enumerate(lines):
+            y = i * line_height
+            x = 0
+            if text_align == "right":
+                x = max_width
+            elif text_align == "center":
+                x = max_width / 2
+            text_style = f'style="font-family: {font_family}; font-size: {font_size}; font-weight: {font_weight};"'
+            text_content += f'<text dominant-baseline="hanging" text-anchor="{text_anchor}" {text_style} transform="translate({x}, {y})">{line}</text>'
+        
+        g_right = '</g>'
+        text_svg = g_left + text_content + g_right
+        
+        # 计算整体边界框
+        if len(lines) == 1:
+            bounding_box = measure_text_bounds(lines[0][0], font_family, font_size, font_weight)
+        else:
+            # 对于多行文本，计算整体边界框
+            max_line_width = 0
+            for (line, line_width) in lines:
+                max_line_width = max(max_line_width, line_width)
+                
+            total_height = line_height * (len(lines) - 1) + font_size_px
+            
+            bounding_box = {
+                'width': max_line_width,
+                'height': total_height,
+                'min_x': 0,
+                'min_y': 0,
+                'max_x': max_line_width,
+                'max_y': total_height
+            }
+        
+        return text_svg, bounding_box
+    
+    
+def process(
+    input: str = None,
+    output: str = None,
+    input_data: Dict = None,
+    max_width: int = 500,
+    text_align: str = "left",
+    show_embellishment: bool = True,
+    show_sub_title: bool = True,
+    font_family: str = None
+) -> Union[bool, str]:
+    """
+    Process function for generating styled title SVG from input data.
+
+    Args:
+        input (str, optional): Path to the input JSON file.
+        output (str, optional): Path to the output SVG file.
+        input_data (Dict, optional): Input data dictionary (alternative to file input).
+        max_width (int, optional): Maximum width constraint for the title. Defaults to 500.
+        text_align (str, optional): Text alignment. Options: "left", "center", "right". Defaults to "left".
+        show_embellishment (bool, optional): Whether to show the decoration element. Defaults to True.
+        show_sub_title (bool, optional): Whether to show the subtitle. Defaults to True.
+        font_family (str, optional): Font family to use for all text. Defaults to None (use from typography).
+
+    Returns:
+        Union[bool, str]:
+          - If output is provided, returns True/False indicating success/failure.
+          - Otherwise, returns the generated SVG content as a string.
+    """
+    try:
+        # Load the data object
+        if input_data is None:
+            if input is None:
+                return False
+            with open(input, 'r', encoding='utf-8') as f:
+                data = json.load(f)
+        else:
+            data = input_data
+
+        # Generate the title SVG
+        title_generator = TitleGenerator(data, max_width=max_width, 
+                                         text_align=text_align, 
+                                         show_embellishment=show_embellishment,
+                                         show_sub_title=show_sub_title,
+                                         font_family=font_family)
+        svg_content, bounding_box = title_generator.generate()
+
+        if output:
+            with open(output, 'w', encoding='utf-8') as f:
+                f.write(svg_content)
+            return True
+
+        return svg_content
+
+    except Exception as e:
+        print(f"Error in title styling: {str(e)}")
+        return False
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Generate styled title SVG for a chart')
+    parser.add_argument('--input', '-i', type=str, required=True, help='Input JSON file path')
+    parser.add_argument('--output', '-o', type=str, help='Output SVG file path')
+    parser.add_argument('--max-width', '-w', type=int, default=500, help='Maximum width constraint for the title')
+    parser.add_argument('--text-align', '-a', type=str, default='left', choices=['left', 'center', 'right'],
+                        help='Text alignment: left, center, or right')
+    parser.add_argument('--no-embellishment', action='store_true', help='Hide the decoration element')
+    parser.add_argument('--no-subtitle', action='store_true', help='Hide the subtitle')
+    parser.add_argument('--font', type=str, help='Font family to use for all text (e.g. Arial, Comic, Times)')
+    
+    args = parser.parse_args()
+    
+    # 处理font参数中的comics
+    if args.font and args.font.lower() == 'comics':
+        args.font = 'Comic Sans MS, cursive'
+        
+    success = process(
+        input=args.input,
+        output=args.output,
+        max_width=args.max_width,
+        text_align=args.text_align,
+        show_embellishment=not args.no_embellishment,
+        show_sub_title=not args.no_subtitle,
+        font_family=args.font
+    )
+    
+    if success:
+        print("Title styling completed successfully.")
+    else:
+        print("Title styling failed.")
+
+
+if __name__ == '__main__':
+    main()

modules/title_styler/utils/svg_to_mask.py

@@ -0,0 +1,251 @@
+import sys
+import os
+import io
+import argparse
+import math
+from PIL import Image as PILImage, ImageDraw
+import cairosvg
+import numpy as np
+from lxml import etree
+import base64
+
+def parse_svg_dimensions(svg_content):
+    """解析SVG中的尺寸信息"""
+    # print('svg_content: ', svg_content)
+    # for debug: 把svg_content写入文件
+    svg_content = svg_content.replace('&', '')
+    temp_dir = os.environ.get('TEMP_DIR', '.')
+    with open(os.path.join(temp_dir, "svg_content.svg"), "w") as f:
+        f.write(svg_content)
+    # 将&符号替换为&以避免XML解析错误
+    root = etree.fromstring(svg_content)
+    
+
+    
+    # 默认值
+    dimensions = {
+        'viewBox': [0, 0, 300, 150],
+        'width': 300,
+        'height': 150
+    }
+    
+    # 解析viewBox
+    viewbox = root.get('viewBox')
+    if viewbox:
+        dimensions['viewBox'] = [float(x) for x in viewbox.replace(',', ' ').split()]
+    
+    # 解析width和height
+    width = root.get('width')
+    height = root.get('height')
+    
+    if width and height:
+        # 去掉单位
+        dimensions['width'] = float(''.join(c for c in width if c.isdigit() or c == '.'))
+        dimensions['height'] = float(''.join(c for c in height if c.isdigit() or c == '.'))
+    elif width:
+        dimensions['width'] = float(''.join(c for c in width if c.isdigit() or c == '.'))
+        # 保持比例
+        dimensions['height'] = dimensions['width'] * (dimensions['viewBox'][3] / dimensions['viewBox'][2])
+    elif height:
+        dimensions['height'] = float(''.join(c for c in height if c.isdigit() or c == '.'))
+        # 保持比例
+        dimensions['width'] = dimensions['height'] * (dimensions['viewBox'][2] / dimensions['viewBox'][3])
+    else:
+        # 使用viewBox
+        dimensions['width'] = dimensions['viewBox'][2]
+        dimensions['height'] = dimensions['viewBox'][3]
+    
+    return dimensions
+
+
+def svg_to_mask(svg_content, grid_size=10, content_threshold=0.05, sample_density=36, scale=2):
+    """
+    将SVG转换为基于网格的mask
+    
+    参数:
+    svg_content - SVG内容字符串
+    grid_size - 网格大小
+    content_threshold - 内容阈值，当内容占比超过此值时标记为有内容
+    sample_density - 采样密度，每个网格单元的采样点数量
+    scale - 比例因子，用于提高渲染精度
+    
+    返回:
+    tuple (原始图像, mask图像, mask网格, 网格信息)
+    """
+    svg_content = svg_content.replace('&', '')
+    # 解析SVG尺寸
+    dimensions = parse_svg_dimensions(svg_content)
+    vbx, vby, vbw, vbh = dimensions['viewBox']
+    
+    # 计算网格尺寸
+    cols = math.ceil(vbw / grid_size)
+    rows = math.ceil(vbh / grid_size)
+    
+    # 渲染SVG到PNG
+    canvas_width = int(cols * grid_size * scale)
+    canvas_height = int(rows * grid_size * scale)
+    
+    png_data = cairosvg.svg2png(
+        bytestring=svg_content.encode('utf-8'),
+        output_width=canvas_width,
+        output_height=canvas_height
+    )
+    
+    # 加载图像
+    image = PILImage.open(io.BytesIO(png_data))
+    image_data = np.array(image)
+    
+    # 创建mask矩阵和图像
+    mask_grid = np.zeros((rows, cols), dtype=bool)
+    mask_image = PILImage.new('RGBA', (canvas_width, canvas_height), (0, 0, 0, 0))
+    draw = ImageDraw.Draw(mask_image)
+    
+    # 用于调试的画布
+    debug_image = image.copy()
+    debug_draw = ImageDraw.Draw(debug_image)
+    
+    # 计算采样步长
+    samples_per_row = int(math.sqrt(sample_density))
+    step_size = (grid_size * scale) / samples_per_row
+    
+    grid_info = {
+        'total_cells': rows * cols,
+        'filled_cells': 0,
+        'dimensions': dimensions,
+        'grid_size': grid_size,
+        'rows': rows,
+        'cols': cols
+    }
+    
+    # 生成采样网格坐标
+    x_offsets = np.arange(samples_per_row) * step_size
+    y_offsets = np.arange(samples_per_row) * step_size
+    X, Y = np.meshgrid(x_offsets, y_offsets)
+    sample_offsets = np.stack([X.flatten(), Y.flatten()], axis=1)
+    
+    # 遍历每个网格单元
+    for y in range(rows):
+        for x in range(cols):
+            # 网格在图像上的位置
+            grid_x = int(x * grid_size * scale)
+            grid_y = int(y * grid_size * scale)
+            
+            # 绘制网格线（调试用）
+            debug_draw.rectangle(
+                [(grid_x, grid_y), (grid_x + grid_size * scale, grid_y + grid_size * scale)], 
+                outline=(200, 200, 200, 128), 
+                width=1, 
+                fill=None
+            )
+            
+            # 计算所有采样点坐标
+            sample_points = sample_offsets + [grid_x, grid_y]
+            sample_points = sample_points.astype(int)
+            
+            # 过滤掉超出范围的点
+            valid_points = (sample_points[:, 0] >= 0) & (sample_points[:, 0] < canvas_width) & \
+                         (sample_points[:, 1] >= 0) & (sample_points[:, 1] < canvas_height)
+            valid_samples = sample_points[valid_points]
+            
+            # 获取所有有效采样点的颜色和alpha值
+            pixels = image_data[valid_samples[:, 1], valid_samples[:, 0]]
+            rgb_values = pixels[:, :3]
+            alpha_values = pixels[:, 3]
+            
+            # 判断有效点：alpha不为0且RGB不都超过250
+            is_white = np.all(rgb_values > 250, axis=1)
+            is_visible = (alpha_values > 0) & (~is_white)
+            content_points = np.sum(is_visible)
+            
+            # 计算内容比例
+            content_ratio = content_points / sample_density
+            
+            # 在调试图像上显示比例
+            text_x = grid_x + (grid_size * scale) // 2
+            text_y = grid_y + (grid_size * scale) // 2
+            text_color = (255, 0, 0, 255) if content_ratio >= content_threshold else (0, 0, 0, 255)
+            debug_draw.text((text_x, text_y), f"{int(content_ratio*100)}%", fill=text_color)
+            
+            # 如果内容比例超过阈值，则标记为有内容
+            if content_ratio >= content_threshold:
+                mask_grid[y, x] = True
+                grid_info['filled_cells'] += 1
+                
+                # 在mask图像上绘制矩形
+                draw.rectangle(
+                    [(grid_x, grid_y), (grid_x + grid_size * scale, grid_y + grid_size * scale)],
+                    fill=(0, 0, 255, 128)
+                )
+                
+                # 在调试图像上高亮有内容的网格
+                debug_draw.rectangle(
+                    [(grid_x, grid_y), (grid_x + grid_size * scale, grid_y + grid_size * scale)],
+                    outline=(255, 0, 0, 255),
+                    width=2,
+                    fill=None
+                )
+    
+    return debug_image, mask_image, mask_grid, grid_info
+
+def main():
+    parser = argparse.ArgumentParser(description='SVG到网格Mask转换工具')
+    parser.add_argument('svg_file', help='输入SVG文件路径')
+    parser.add_argument('--output', '-o', help='输出目录', default='.')
+    parser.add_argument('--grid-size', '-g', type=int, default=10, help='网格大小 (默认: 10)')
+    parser.add_argument('--threshold', '-t', type=float, default=0.05, help='内容阈值 (0-1, 默认: 0.05)')
+    parser.add_argument('--sample', '-s', type=int, default=36, help='采样密度 (默认: 36 = 6x6)')
+    parser.add_argument('--scale', type=float, default=2, help='渲染比例因子 (默认: 2)')
+    
+    args = parser.parse_args()
+    
+    # 读取SVG文件
+    try:
+        with open(args.svg_file, 'r', encoding='utf-8') as f:
+            svg_content = f.read()
+    except Exception as e:
+        print(f"无法读取SVG文件: {e}")
+        return
+    
+    # 创建输出目录
+    if not os.path.exists(args.output):
+        os.makedirs(args.output)
+    
+    # 生成文件名
+    base_name = os.path.splitext(os.path.basename(args.svg_file))[0]
+    debug_file = os.path.join(args.output, f"{base_name}_debug.png")
+    mask_file = os.path.join(args.output, f"{base_name}_mask.png")
+    info_file = os.path.join(args.output, f"{base_name}_info.txt")
+    
+    # 生成mask
+    print(f"处理SVG文件: {args.svg_file}")
+    print(f"网格大小: {args.grid_size}, 内容阈值: {args.threshold*100}%, 采样密度: {args.sample}")
+    
+    debug_image, mask_image, mask_grid, grid_info = svg_to_mask(
+        svg_content, 
+        grid_size=args.grid_size,
+        content_threshold=args.threshold,
+        sample_density=args.sample,
+        scale=args.scale
+    )
+    
+    # 保存结果
+    debug_image.save(debug_file)
+    mask_image.save(mask_file)
+    print(mask_grid)
+    
+    # 生成信息文件
+    dimensions = grid_info['dimensions']
+    with open(info_file, 'w', encoding='utf-8') as f:
+        f.write(f"SVG尺寸: {dimensions['width']}x{dimensions['height']}\n")
+        f.write(f"ViewBox: {dimensions['viewBox']}\n")
+        f.write(f"网格: {grid_info['cols']}×{grid_info['rows']}, 共{grid_info['filled_cells']}/{grid_info['total_cells']}个单元格被标记 ")
+        f.write(f"({grid_info['filled_cells']/grid_info['total_cells']*100:.1f}%)\n")
+        f.write(f"阈值: {args.threshold*100}%\n")
+        f.write(f"白色阈值: 250\n")
+    
+    print(f"处理完成。调试图像已保存到: {debug_file}")
+    print(f"Mask图像已保存到: {mask_file}")
+    print(f"信息已保存到: {info_file}")
+
+if __name__ == "__main__":
+    main()