codeannex 0.1.1__tar.gz → 0.2.0__tar.gz

codeannex-0.2.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: codeannex
+Version: 0.2.0
+Summary: Generates a professional PDF source code annex with Smart Index, Images and Emoji support.
+License: MIT
+Project-URL: Repository, https://github.com/tanhleno/codeannex
+Keywords: pdf,source-code,documentation,annex,reportlab,emoji
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: reportlab>=4.0
+Requires-Dist: Pillow>=10.0
+Requires-Dist: Pygments>=2.16
+Requires-Dist: pdfminer.six>=20231228
+Provides-Extra: svg
+Requires-Dist: cairosvg>=2.7; extra == "svg"
+Requires-Dist: svglib>=1.5; extra == "svg"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# 📂 codeannex
+
+Generates a professional PDF annex from a project's source code — with syntax highlighting, a hierarchical table of contents, image rendering, and intelligent font discovery.
+
+## 🚀 Key Features
+
+- **Interactive Wizard** — Run without arguments to configure your PDF step-by-step. It intelligently skips irrelevant questions (like starting page if numbering is disabled).
+- **Intelligent Font Discovery** — Automatically finds and registers fonts from your system (Windows, Linux, macOS) by name (e.g., `--title-font "Play"`).
+- **Fully Customizable UI** — Change every label, color, and size via CLI. Default labels are in English for international consistency.
+- **Hierarchical Summary** — Real tree-structured Table of Contents with terminal-like connection lines.
+- **Customizable Primary Color** — Set the theme color for headers, folder icons, and accents with `--primary-color`.
+- **Smart Contrast** — Automatically switches header text between black and white based on the brightness of your primary color for maximum legibility.
+- **Flexible Page Styling** — Support for custom page background and code block colors.
+- **Git-Aware** — Perfectly interprets `.gitignore` using Git's native engine.
+
+## 🛠 Installation
+
+```bash
+pip install codeannex
+```
+
+## 📖 Usage
+
+### Interactive Mode (Wizard)
+Simply run without arguments to start the step-by-step configuration:
+```bash
+codeannex .
+```
+
+### Automation / CI
+Use the `--no-input` flag to disable the wizard in automated environments:
+```bash
+codeannex . --no-input
+```
+
+### Professional Customization Example
+```bash
+python3 -m codeannex . \
+  --cover-title "Anexo I" \
+  --no-page-numbers \
+  --primary-color "#0f4761" \
+  --title-font "Play" --title-size 20 \
+  --normal-font "Times New Roman" --normal-size 12 \
+  --margin-top 2.5 --margin-bottom 2.5 --margin-left 3 --margin-right 3 \
+  --code-bg "#f5f5f5" --code-size 9
+```
+
+## ⚙️ Configuration Options
+
+### Document & Labels
+- `--cover-title TITLE` — Title for the cover (default: "ANEXO TÉCNICO").
+- `--cover-subtitle SUB` — Subtitle for the cover.
+- `--summary-title TITLE` — Title for the summary page.
+- `--repo-label LABEL` — Prefix for repository link (default: "Repository: ").
+- `--project-label LABEL` — Prefix for project name in footer.
+- `--file-part-format FMT` — Format for file parts (default: "({current}/{total})").
+- `--no-input` — Disable the interactive wizard.
+
+
+### Colors & Themes
+- `--primary-color HEX` — Main color for headers and accents.
+- `--page-bg-color HEX` — Background color for all pages.
+- `--code-bg HEX` — Background color for code blocks.
+- `--normal-color HEX` / `--title-color HEX` — Text colors.
+
+### Fonts & Sizes
+- `--title-font` / `--subtitle-font` / `--normal-font` — System font names.
+- `--mono-font` — Font for code (e.g., "Consolas", "Ubuntu Mono").
+- `--emoji-font` — Font for emojis (e.g., "Noto Emoji").
+- `--code-size N` — Font size for code blocks.
+
+### Layout
+- `--margin CM` — General margin for all sides.
+- `--margin-top`, `--margin-bottom`, `--margin-left`, `--margin-right` — Specific margins in cm.
+- `--no-page-numbers` — Disable page numbering.
+
+## 🧪 Testing
+
+```bash
+PYTHONPATH=. pytest
+```
+
+## 📄 License
+
+MIT

codeannex-0.2.0/README.md

@@ -0,0 +1,85 @@
+# 📂 codeannex
+
+Generates a professional PDF annex from a project's source code — with syntax highlighting, a hierarchical table of contents, image rendering, and intelligent font discovery.
+
+## 🚀 Key Features
+
+- **Interactive Wizard** — Run without arguments to configure your PDF step-by-step. It intelligently skips irrelevant questions (like starting page if numbering is disabled).
+- **Intelligent Font Discovery** — Automatically finds and registers fonts from your system (Windows, Linux, macOS) by name (e.g., `--title-font "Play"`).
+- **Fully Customizable UI** — Change every label, color, and size via CLI. Default labels are in English for international consistency.
+- **Hierarchical Summary** — Real tree-structured Table of Contents with terminal-like connection lines.
+- **Customizable Primary Color** — Set the theme color for headers, folder icons, and accents with `--primary-color`.
+- **Smart Contrast** — Automatically switches header text between black and white based on the brightness of your primary color for maximum legibility.
+- **Flexible Page Styling** — Support for custom page background and code block colors.
+- **Git-Aware** — Perfectly interprets `.gitignore` using Git's native engine.
+
+## 🛠 Installation
+
+```bash
+pip install codeannex
+```
+
+## 📖 Usage
+
+### Interactive Mode (Wizard)
+Simply run without arguments to start the step-by-step configuration:
+```bash
+codeannex .
+```
+
+### Automation / CI
+Use the `--no-input` flag to disable the wizard in automated environments:
+```bash
+codeannex . --no-input
+```
+
+### Professional Customization Example
+```bash
+python3 -m codeannex . \
+  --cover-title "Anexo I" \
+  --no-page-numbers \
+  --primary-color "#0f4761" \
+  --title-font "Play" --title-size 20 \
+  --normal-font "Times New Roman" --normal-size 12 \
+  --margin-top 2.5 --margin-bottom 2.5 --margin-left 3 --margin-right 3 \
+  --code-bg "#f5f5f5" --code-size 9
+```
+
+## ⚙️ Configuration Options
+
+### Document & Labels
+- `--cover-title TITLE` — Title for the cover (default: "ANEXO TÉCNICO").
+- `--cover-subtitle SUB` — Subtitle for the cover.
+- `--summary-title TITLE` — Title for the summary page.
+- `--repo-label LABEL` — Prefix for repository link (default: "Repository: ").
+- `--project-label LABEL` — Prefix for project name in footer.
+- `--file-part-format FMT` — Format for file parts (default: "({current}/{total})").
+- `--no-input` — Disable the interactive wizard.
+
+
+### Colors & Themes
+- `--primary-color HEX` — Main color for headers and accents.
+- `--page-bg-color HEX` — Background color for all pages.
+- `--code-bg HEX` — Background color for code blocks.
+- `--normal-color HEX` / `--title-color HEX` — Text colors.
+
+### Fonts & Sizes
+- `--title-font` / `--subtitle-font` / `--normal-font` — System font names.
+- `--mono-font` — Font for code (e.g., "Consolas", "Ubuntu Mono").
+- `--emoji-font` — Font for emojis (e.g., "Noto Emoji").
+- `--code-size N` — Font size for code blocks.
+
+### Layout
+- `--margin CM` — General margin for all sides.
+- `--margin-top`, `--margin-bottom`, `--margin-left`, `--margin-right` — Specific margins in cm.
+- `--no-page-numbers` — Disable page numbering.
+
+## 🧪 Testing
+
+```bash
+PYTHONPATH=. pytest
+```
+
+## 📄 License
+
+MIT

{codeannex-0.1.1 → codeannex-0.2.0}/codeannex/__main__.py

@@ -5,7 +5,7 @@ from pathlib import Path
 
 from .config import IMAGE_EXTENSIONS, BINARY_EXTENSIONS, PDFConfig
 from .file_utils import get_project_files, classify_file, sort_files
-from .fonts import init_sprites, register_best_font, register_emoji_font
+from .fonts import init_sprites, register_best_font, register_emoji_font, auto_register_font
 from .pdf_builder import ModernAnnexPDF
 from reportlab.lib.units import cm
 
@@ -16,8 +16,6 @@ def check_emoji_font_style():
 
     emoji_font = register_emoji_font()
     if emoji_font:
-        # Tentar obter informações sobre a fonte
-        # Nota: Esta é uma simplificação - em produção teríamos o caminho armazenado
         print(f"✅ Emoji font registered: {emoji_font}")
         print("ℹ️  To check if using Google-like style, look for 'Noto' in the font path above")
         print("💡 Tip: Install Google Noto fonts for authentic Google emoji style")
@@ -26,11 +24,50 @@ def check_emoji_font_style():
     return emoji_font
 
 
+def run_interactive_wizard(args):
+    """Interactive wizard to configure the PDF when no arguments are provided."""
+    print("\n✨ Welcome to codeannex Interactive Wizard! ✨")
+    print("Press Enter to keep the [default] value.\n")
+    
+    questions = [
+        ("name", "Project Name", args.name or "Current Directory"),
+        ("cover_title", "Cover Title", args.cover_title),
+        ("cover_subtitle", "Cover Subtitle", args.cover_subtitle),
+        ("primary_color", "Primary Color (HEX)", args.primary_color),
+        ("title_font", "Title Font Name", args.title_font or "Play"),
+        ("normal_font", "Normal Text Font Name", args.normal_font or "Tinos"),
+        ("mono_font", "Monospace Font Name", args.mono_font or "NotoSansMono"),
+        ("margin_top", "Top Margin (cm)", args.margin_top or 2.0),
+        ("margin_bottom", "Bottom Margin (cm)", args.margin_bottom or 2.0),
+        ("margin_left", "Left Margin (cm)", args.margin_left or 1.5),
+        ("margin_right", "Right Margin (cm)", args.margin_right or 1.5),
+        ("no_page_numbers", "Disable Page Numbers? (y/n)", "n"),
+        ("start_page", "Starting Page Number", args.start_page or 1),
+    ]
+    
+    for i, (attr, label, default) in enumerate(questions, 1):
+        # Skip start_page question if page numbers were disabled in previous step
+        if attr == "start_page" and args.no_page_numbers:
+            continue
+            
+        choice = input(f"[{i}/{len(questions)}] {label} [{default}]: ").strip()
+        if choice:
+            if attr == "no_page_numbers":
+                args.no_page_numbers = choice.lower() == 'y'
+            elif "margin" in attr or attr == "start_page":
+                setattr(args, attr, float(choice) if "." in choice else int(choice))
+            else:
+                setattr(args, attr, choice)
+    print("\n🚀 Configuration complete! Generating PDF...\n")
+
+
 def main():
     parser = argparse.ArgumentParser(description="Generates a PDF code annex with Smart Index and Images.")
     parser.add_argument("dir", nargs="?", default=".", help="Project directory")
     parser.add_argument("-o", "--output", default=None, help="Output PDF filename")
     parser.add_argument("-n", "--name", default=None, help="Project name (default: directory name)")
+    parser.add_argument("--no-input", action="store_true", help="Disable interactive mode")
+    parser.add_argument("--cover-title", default="TECHNICAL ANNEX", help="Title for the cover page")
     parser.add_argument("--margin", type=float, default=None, help="General margin in cm for all sides")
     parser.add_argument("--margin-left", type=float, default=None, help="Left margin in cm (default: 1.5cm)")
     parser.add_argument("--margin-right", type=float, default=None, help="Right margin in cm (default: 1.5cm)")
@@ -39,9 +76,29 @@ def main():
     parser.add_argument("--start-page", type=int, default=1, help="Starting page number (default: 1)")
     parser.add_argument("--show-project", action="store_true", help="Show project name in footer")
     parser.add_argument("--repo-url", default=None, help="Repository URL to show on cover")
+    parser.add_argument("--repo-label", default="Repository: ", help="Label for repo URL (default: 'Repository: ')")
+    parser.add_argument("--project-label", default="Project: ", help="Label for project name in footer (default: 'Project: ')")
+    parser.add_argument("--file-part-format", default="({current}/{total})", help="Format for file parts continuation (e.g. '({current}/{total})')")
+    parser.add_argument("--summary-title", default="Summary / File Index", help="Title for the summary page")
+    parser.add_argument("--cover-subtitle", default="Source Code Documentation", help="Subtitle for the cover page")
+
     parser.add_argument("--page-number-size", type=int, default=8, help="Font size for page numbers (default: 8)")
+    parser.add_argument("--page-number-format", default="{n}", help="Format for page numbers (e.g. 'Anexo I - {n}')")
+    parser.add_argument("--no-page-numbers", action="store_true", help="Disable page numbers")
+    parser.add_argument("--page-bg-color", default="#ffffff", help="Background color for pages (default: #ffffff)")
     parser.add_argument("--normal-font", default=None, help="Normal text font (default: Helvetica)")
+    parser.add_argument("--normal-size", type=int, default=10, help="Normal text font size (default: 10)")
+    parser.add_argument("--normal-color", default="#4c4f69", help="Normal text color (default: #4c4f69)")
     parser.add_argument("--bold-font", default=None, help="Bold text font (default: Helvetica-Bold)")
+    parser.add_argument("--title-font", default=None, help="Title font (default: bold-font)")
+    parser.add_argument("--title-size", type=int, default=28, help="Title font size (default: 28)")
+    parser.add_argument("--title-color", default="#1e1e2e", help="Title color (default: #1e1e2e)")
+    parser.add_argument("--subtitle-font", default=None, help="Subtitle font (default: normal-font)")
+    parser.add_argument("--subtitle-size", type=int, default=18, help="Subtitle font size (default: 18)")
+    parser.add_argument("--subtitle-color", default=None, help="Subtitle color (default: title-color)")
+    parser.add_argument("--primary-color", default="#1e66f5", help="Primary color for accents and headers (default: #1e66f5)")
+    parser.add_argument("--code-size", type=int, default=10, help="Font size for code (default: 10)")
+    parser.add_argument("--code-bg", default="#1e1e2e", help="Background color for code blocks (default: #1e1e2e)")
     parser.add_argument("--mono-font", default=None, help="Monospace font for code (default: auto-detect)")
     parser.add_argument("--emoji-font", default=None, help="Font for emojis (default: auto-detect)")
     parser.add_argument("--emoji-description", action="store_true", help="Print [description] instead of emoji glyphs")
@@ -49,6 +106,22 @@ def main():
 
     args, unknown = parser.parse_known_args()
 
+    # Check if we should run interactive mode: 
+    # No optional arguments provided AND --no-input is False
+    import sys
+    is_interactive = len(sys.argv) <= 2 and not args.no_input
+    # If the second arg is actually a directory but no other flags were passed, we can still go interactive
+    if is_interactive:
+        run_interactive_wizard(args)
+
+    # Pre-register fonts specified in arguments dynamically from system
+    if args.normal_font:   args.normal_font   = auto_register_font(args.normal_font, required=True)
+    if args.bold_font:     args.bold_font     = auto_register_font(args.bold_font, required=True)
+    if args.title_font:    args.title_font    = auto_register_font(args.title_font, required=True)
+    if args.subtitle_font: args.subtitle_font = auto_register_font(args.subtitle_font, required=True)
+    if args.mono_font:     args.mono_font     = auto_register_font(args.mono_font, required=True)
+    if args.emoji_font:    args.emoji_font    = auto_register_font(args.emoji_font, required=True)
+
     # Handle unknown arguments
     if unknown:
         for u in unknown:
@@ -95,6 +168,27 @@ def main():
         emoji_description=args.emoji_description,
         repo_url=args.repo_url,
         page_number_size=args.page_number_size,
+        title_font=args.title_font,
+        title_size=args.title_size,
+        title_color=args.title_color,
+        subtitle_font=args.subtitle_font,
+        subtitle_size=args.subtitle_size,
+        subtitle_color=args.subtitle_color,
+        normal_text_size=args.normal_size,
+        normal_text_color=args.normal_color,
+        page_number_format=args.page_number_format,
+        show_page_numbers=not args.no_page_numbers,
+        cover_title=args.cover_title,
+        primary_color=args.primary_color,
+        # New dynamic fields
+        cover_subtitle=args.cover_subtitle,
+        summary_title=args.summary_title,
+        repo_label=args.repo_label,
+        project_label=args.project_label,
+        file_part_format=args.file_part_format,
+        code_font_size=args.code_size,
+        code_bg_color=args.code_bg,
+        page_bg_color=args.page_bg_color,
     )
 
     print(f"🔍 Analyzing directory: {root}")
@@ -113,7 +207,6 @@ def main():
 
         ext = fp.suffix.lower()
 
-        # Check known extensions first (without reading file)
         if ext == ".svg":
             included += [(fp, "image"), (fp, "text")]
             continue
@@ -124,7 +217,6 @@ def main():
             ignored_binaries.append(fp)
             continue
 
-        # Classify file with a single read
         file_type = classify_file(fp)
         if file_type == "text":
             included.append((fp, "text"))

{codeannex-0.1.1 → codeannex-0.2.0}/codeannex/config.py

@@ -56,6 +56,33 @@ class PDFConfig:
     repo_url: str | None = None  # URL of the repository for the cover page
     page_number_size: int = 8  # Font size for page numbers
 
+    # Customization fields
+    title_font: str | None = None
+    title_size: int = 28
+    title_color: str = "#1e1e2e"
+    subtitle_font: str | None = None
+    subtitle_size: int = 18
+    subtitle_color: str | None = None # Defaults to title_color
+    normal_text_size: int = 10
+    normal_text_color: str = "#4c4f69" # Default COLOR_TEXT_MAIN
+    page_number_format: str = "{n}" # e.g. "Anexo I - {n}" or just "{n}"
+    show_page_numbers: bool = True
+    cover_title: str = "TECHNICAL ANNEX"
+    cover_subtitle: str = "Source Code Documentation"
+    primary_color: str = "#1e66f5" # Professional dark blue
+    
+    # Code style
+    code_font_size: int = CODE_FONT_SIZE
+    code_bg_color: str = "#1e1e2e" # Default COLOR_CODE_BG
+    page_bg_color: str = "#ffffff" # Default COLOR_PAGE_BG
+    
+    # Labels (Internationalization)
+    summary_title: str = "Summary / File Index"
+    repo_label: str = "Repository: "
+    project_label: str = "Project: "
+    file_part_format: str = "({current}/{total})" # e.g. "(1/2)"
+    cover_subtitle: str = "Source Code Documentation"
+
     def get_code_x(self) -> float:
         """Calculates the initial X position of the code."""
         return self.margin_left + GUTTER_W

codeannex-0.2.0/codeannex/fonts.py

@@ -0,0 +1,275 @@
+import os
+import io
+import logging
+from pathlib import Path
+from PIL import Image as PilImage, ImageDraw as PilImageDraw, ImageFont as PilImageFont
+from reportlab.lib.utils import ImageReader
+from reportlab.pdfbase import pdfmetrics
+from reportlab.pdfbase.ttfonts import TTFont
+
+from .config import CODE_FONT_SIZE, COLOR_GUTTER_FG
+
+logging.getLogger("svglib").setLevel(logging.ERROR)
+
+# ── Discovery ────────────────────────────────────
+
+def get_system_font_paths():
+    """Returns a list of standard system font directories."""
+    home = os.path.expanduser("~")
+    paths = [
+        os.path.join(home, ".local/share/fonts"),
+        os.path.join(home, ".fonts"),
+        "/usr/share/fonts",
+        "/usr/local/share/fonts",
+        "/System/Library/Fonts",
+        "/Library/Fonts",
+        "C:\\Windows\\Fonts",
+    ]
+    return [p for p in paths if os.path.exists(p)]
+
+def find_font_file(font_name: str) -> str | None:
+    """Dynamically searches for a font file by name in system directories."""
+    search_dirs = get_system_font_paths()
+    
+    # Normalize name for searching: "NotoEmoji" -> "notoemoji"
+    clean_name = font_name.lower().replace(" ", "").replace("-", "")
+    
+    extensions = [".ttf", ".otf", ".ttc"]
+
+    for base_dir in search_dirs:
+        for root, _, files in os.walk(base_dir):
+            for f in files:
+                f_lower = f.lower()
+                # Check if it's a font file
+                if any(f_lower.endswith(ext) for ext in extensions):
+                    # Check if our clean_name is in the filename
+                    # e.g. "notoemoji" in "notocoloremoji.ttf"
+                    f_clean = f_lower.replace(" ", "").replace("-", "").replace("_", "")
+                    if clean_name in f_clean:
+                        return os.path.join(root, f)
+    return None
+
+def auto_register_font(font_name: str, required: bool = False) -> str:
+    """Attempts to register a font. Errors (🛑) stop execution, Warnings (⚠️) just alert."""
+    if not font_name:
+        return font_name
+        
+    # Standard ReportLab fonts
+    if font_name in ["Helvetica", "Helvetica-Bold", "Times-Roman", "Times-Bold", "Courier"]:
+        return font_name
+
+    # Check if already registered
+    try:
+        pdfmetrics.getFont(font_name)
+        return font_name
+    except:
+        pass
+
+    # Try to find and register
+    path = find_font_file(font_name)
+    if path:
+        try:
+            print(f"✅ Found font '{font_name}' at: {path}")
+            pdfmetrics.registerFont(TTFont(font_name, path))
+            return font_name
+        except Exception as e:
+            if not required:
+                print(f"⚠️ Warning: Could not register font '{font_name}': {e}")
+                return font_name
+            # If required, it will fall through to the Error block below
+    
+    # If font is not found or registration failed
+    if required:
+        msg = (
+            f"\n🛑 ERROR: Font '{font_name}' not found or invalid.\n"
+            f"   Search paths: {', '.join(get_system_font_paths())}\n\n"
+            f"   Fixes:\n"
+            f"   - Install the font on your OS (Windows/Linux/macOS).\n"
+            f"   - Check for typos in your command.\n"
+            f"   - Use a built-in font: Helvetica, Times-Roman, Courier.\n"
+        )
+        import sys
+        print(msg, file=sys.stderr)
+        sys.exit(1)
+    else:
+        print(f"⚠️ WARNING: Font '{font_name}' not found. Emojis or text might not render correctly.")
+    
+    return font_name
+
+# ── Original Support Functions ───────────────────
+
+TTF_SEARCH_PATHS = [
+    "/usr/share/fonts/truetype/noto/NotoSansMono-Regular.ttf",
+    "/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf",
+    "C:\\Windows\\Fonts\\consola.ttf",
+]
+
+EMOJI_SEARCH_PATHS = [
+    "/usr/share/fonts/truetype/noto/NotoEmoji-Regular.ttf",
+    "/usr/share/fonts/truetype/ancient-scripts/Symbola_hint.ttf",
+]
+
+def _register_font(name: str, paths: list, fallback):
+    for p in paths:
+        if os.path.exists(p):
+            try:
+                pdfmetrics.registerFont(TTFont(name, p))
+                return name, p
+            except Exception:
+                continue
+    return fallback, None
+
+def register_best_font():
+    name, path = _register_font("CustomMono", TTF_SEARCH_PATHS, "Courier")
+    return name, name != "Courier", path
+
+def register_emoji_font(error_on_missing=False):
+    name, path = _register_font("CustomEmoji", EMOJI_SEARCH_PATHS, None)
+    if name is None:
+        # Tenta busca dinâmica como última opção
+        dynamic_path = find_font_file("NotoEmoji") or find_font_file("Symbola")
+        if dynamic_path:
+            name, _ = _register_font("CustomEmoji", [dynamic_path], None)
+    
+    if name is None and error_on_missing:
+        msg = (
+            "❌ Error: No emoji font found on your system.\n"
+            "   Emojis cannot be rendered correctly without a dedicated font.\n\n"
+            "   Solutions:\n"
+            "   1. Install a font like 'Google Noto Emoji' or 'DejaVu Sans'.\n"
+            "      - Ubuntu/Debian: sudo apt install fonts-noto-color-emoji\n"
+            "      - Fedora: sudo dnf install google-noto-emoji-color-fonts\n"
+            "      - Arch: sudo pacman -S noto-fonts-emoji\n"
+            "   2. Use the --emoji-description flag to print [emoji descriptions] instead.\n"
+            "   3. Manually specify a font path using --emoji-font \"/path/to/font.ttf\""
+        )
+        import sys
+        print(msg, file=sys.stderr)
+        sys.exit(1)
+    return name
+
+def get_emoji_font_style(font_path: str | None) -> str | None:
+    """Detects the emoji style based on the font path."""
+    if not font_path:
+        return None
+    font_path_lower = font_path.lower()
+    if "noto" in font_path_lower:
+        if "color" in font_path_lower: return "Google Noto Color"
+        elif "emoji" in font_path_lower: return "Google Noto Emoji"
+        else: return "Google Noto"
+    if "apple" in font_path_lower: return "Apple"
+    if "segui" in font_path_lower or "windows" in font_path_lower: return "Microsoft/Windows"
+    if "symbola" in font_path_lower: return "Symbola (Unicode)"
+    if "dejavu" in font_path_lower: return "DejaVu"
+    if "ubuntu" in font_path_lower: return "Ubuntu"
+    return "Unknown"
+
+def is_google_like_emoji_font(font_path: str | None) -> bool:
+    """Checks if the emoji font is Google-like (Noto-based)."""
+    if not font_path: return False
+    return "noto" in font_path.lower()
+
+def get_current_emoji_font_info() -> dict:
+    """Returns information about the currently registered emoji font."""
+    if "CustomEmoji" in pdfmetrics._fonts:
+        return {
+            "name": "CustomEmoji",
+            "is_registered": True,
+            "is_google_like": False, 
+            "style": "Unknown"
+        }
+    return {
+        "name": None,
+        "is_registered": False,
+        "is_google_like": False,
+        "style": None
+    }
+
+# ── Character & Sprite Support ───────────────────
+
+_FONT_CACHE: dict = {}
+
+def is_char_supported(char: str, font_name: str) -> bool:
+    """Checks if the font has a glyph for the character. True for standard ASCII in built-in fonts."""
+    if font_name not in _FONT_CACHE:
+        try:
+            _FONT_CACHE[font_name] = pdfmetrics.getFont(font_name)
+        except:
+            return False
+
+    try:
+        f = _FONT_CACHE[font_name]
+        
+        # ReportLab standard fonts (Type1) only support latin-1
+        if font_name in ["Helvetica", "Helvetica-Bold", "Times-Roman", "Times-Bold", "Courier"]:
+            return ord(char) < 256
+
+        # For TTFonts, check the actual glyph map
+        if hasattr(f, "face") and hasattr(f.face, "charToGlyph"):
+            return ord(char) in f.face.charToGlyph
+            
+        return ord(char) < 256
+    except:
+        return False
+
+def is_emoji(char: str) -> bool:
+    """
+    Returns True if the character is likely an emoji/symbol.
+    Excludes box-drawing characters (U+2500 to U+257F).
+    """
+    if not char: return False
+    cp = ord(char[0])
+    # Box Drawing range: 2500–257F
+    if 0x2500 <= cp <= 0x257F:
+        return False
+        
+    import unicodedata
+    category = unicodedata.category(char[0])
+    return category in ['So', 'Sk', 'Cn']
+
+DIGIT_SPRITES: dict | None = None
+
+def get_digit_sprites() -> dict:
+    if DIGIT_SPRITES is None: raise RuntimeError("init_sprites() not called.")
+    return DIGIT_SPRITES
+
+def init_sprites(is_ttf: bool, ttf_path: str | None):
+    global DIGIT_SPRITES
+    if DIGIT_SPRITES is not None: return
+    DIGIT_SPRITES = {}
+    color_hex = "#bac2de"
+    try:
+        import cairosvg
+        cairo_available = True
+    except ImportError:
+        cairo_available = False
+
+    for d in "0123456789":
+        if cairo_available:
+            svg_str = f'<svg xmlns="http://www.w3.org/2000/svg" width="50" height="50"><text x="25" y="40" font-family="monospace" font-size="40" fill="{color_hex}" text-anchor="middle">{d}</text></svg>'
+            png_data = cairosvg.svg2png(bytestring=svg_str.encode(), scale=4.0)
+            img = PilImage.open(io.BytesIO(png_data))
+        else:
+            box_size = 200
+            font = None
+            if is_ttf and ttf_path:
+                try: font = PilImageFont.truetype(ttf_path, box_size)
+                except: pass
+            font = font or PilImageFont.load_default()
+            img_large = PilImage.new("RGBA", (box_size, box_size), (0, 0, 0, 0))
+            draw = PilImageDraw.Draw(img_large)
+            draw.text((box_size // 2, int(box_size * 0.8)), d, font=font, fill=(186, 194, 222, 255), anchor="ms")
+            img = img_large.resize((50, 50), PilImage.Resampling.LANCZOS)
+        buf = io.BytesIO()
+        img.save(buf, format="PNG")
+        buf.seek(0)
+        DIGIT_SPRITES[d] = ImageReader(buf)
+
+def register_font_file(name: str, path: str):
+    """Fallback for manual registration if needed."""
+    if os.path.exists(path):
+        try:
+            pdfmetrics.registerFont(TTFont(name, path))
+            return name
+        except: pass
+    return None