Imported from davidmacar/Conversor-DnD (scripts/AGENTS.md). Install upstream with npx skills add davidmacar/Conversor-DnD --skill scripts. Copyright stays with the author.

SCRIPTS MODULE: PDF Generation & HTML Parsing

Core business logic for D&D character conversion. Heavy processing modules — largest files in project.

STRUCTURE

scripts/
├── parse_character.py   # HTML→JSON parser (1757 lines)
├── generate_pdf.py      # JSON→PDF generator (~1940 lines)
├── aplanar.py          # PDF flattener (421 lines)
├── project_paths.py    # Path resolution dataclass
└── __init__.py         # Package marker

WHERE TO LOOK

KEY CONCEPTS

• Continuous blocks: Multi-line text fields using ContinuousBlockSpec
• Field classification: Fields categorized by importance → font sizing (10pt/8pt/7pt/6pt)
• SIZE_6PT: Immutable 6pt for all background/appearance fields (personality traits, ideals, bonds, flaws, appearance, allies, enemies, backstory, notes)
• CENTERED: Set of fields with centered text alignment (stats, abilities, skills, speed fields)
• Widget manipulation: Direct xref access for AcroForm fields
• Flattened PDFs: Text rendered statically via pikepdf, only checkboxes remain interactive
• BeautifulSoup4: HTML parsing for Nivel20 extraction

ANTI-PATTERNS

• 1800+ line files with single-responsibility violations
• Complex _continuous_text_sections() branching logic
• Hardcoded field name strings scattered throughout
• No unit tests for parser logic

EXTERNAL DEPS

• beautifulsoup4: HTML parsing (parse_character.py)
• pymupdf (fitz): PDF manipulation (generate_pdf.py)
• pikepdf: PDF structure manipulation (aplanar.py)
• fonttools: Font metrics handling