docx-to-builder 1.0.0

package/docx-to-builder.py

@@ -0,0 +1,1268 @@
+"""
+docx-to-builder.py
+
+Parses any .docx template and generates a complete, ready-to-run JavaScript
+builder using the `docx` npm package (https://docx.js.org).
+
+The generated builder:
+  - Reproduces the exact layout, colors, fonts, spacing, borders, and tables
+  - Replaces bracketed template placeholders like [Client Name] with data.fieldName
+  - Supports multi-section documents (cover page + body with separate margins)
+  - Preserves hyperlinks as ExternalHyperlink in the output
+  - Outputs a properly branded .docx when run with Node.js
+
+Usage:
+  python3 docx-to-builder.py <template.docx> [--output <builder.js>]
+  python3 docx-to-builder.py <template.docx> --list
+
+Options:
+  --output <path>   Write the generated builder to this path instead of next to the template
+  --list            Print a summary of what was found in the template and exit (no file written)
+
+Examples:
+  python3 docx-to-builder.py sample-template.docx
+  python3 docx-to-builder.py my-proposal.docx --output proposal-builder.js
+  python3 docx-to-builder.py my-proposal.docx --list
+
+Requirements:
+  - Python 3.8+  (standard library only — no pip installs needed)
+  - Node.js + docx npm package in the output project: npm install docx
+
+The generated file will be placed next to the input .docx unless --output is specified.
+"""
+
+import sys
+import os
+import zipfile
+import xml.etree.ElementTree as ET
+import re
+import colorsys
+from dataclasses import dataclass, field
+from typing import Optional
+
+# ─── XML namespaces ───────────────────────────────────────────────────────────
+NS = {
+    'w':   'http://schemas.openxmlformats.org/wordprocessingml/2006/main',
+    'wp':  'http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing',
+    'a':   'http://schemas.openxmlformats.org/drawingml/2006/main',
+    'pic': 'http://schemas.openxmlformats.org/drawingml/2006/picture',
+    'r':   'http://schemas.openxmlformats.org/officeDocument/2006/relationships',
+}
+
+def qn(tag):
+    """Resolve a prefixed tag like w:p to its full Clark notation."""
+    prefix, local = tag.split(':')
+    return f'{{{NS[prefix]}}}{local}'
+
+def _bool_prop(rPr, tag):
+    """
+    Return True if a toggle property like <w:b/> is present AND not explicitly
+    turned off with w:val="0" or w:val="false".  Word uses this pattern for
+    properties inherited from a style that need to be reset on a specific run.
+    """
+    el = rPr.find(qn(tag))
+    if el is None:
+        return False
+    val = el.get(qn('w:val'))
+    # Explicit off: val="0" or val="false"
+    if val in ('0', 'false'):
+        return False
+    return True
+
+# ─── Data structures ─────────────────────────────────────────────────────────
+@dataclass
+class RunFormat:
+    text: str = ''
+    bold: bool = False
+    italic: bool = False
+    allCaps: bool = False
+    font: str = 'Calibri'
+    size: Optional[int] = None   # stored as half-points (Word XML unit)
+    color: Optional[str] = None
+    is_page_number: bool = False  # PAGE or NUMPAGES field
+    is_tab: bool = False
+    is_cached_field: bool = False  # stale cached value between fldChar begin/end — skip
+    hyperlink_url: Optional[str] = None  # set if this run is inside a w:hyperlink
+
+@dataclass
+class ParaFormat:
+    runs: list = field(default_factory=list)
+    alignment: Optional[str] = None
+    spacing_before: int = 0
+    spacing_after: int = 0
+    border_top: Optional[dict] = None
+    border_bottom: Optional[dict] = None
+    style: Optional[str] = None
+    is_bullet: bool = False
+    is_page_break: bool = False
+    tab_stop_right: Optional[int] = None
+
+@dataclass
+class CellFormat:
+    paragraphs: list = field(default_factory=list)
+    width_dxa: Optional[int] = None
+    shading: Optional[str] = None
+    border_color: Optional[str] = None
+    margin_top: int = 0
+    margin_bottom: int = 0
+    margin_left: int = 0
+    margin_right: int = 0
+    valign: Optional[str] = None
+
+@dataclass
+class TableFormat:
+    rows: list = field(default_factory=list)
+    width_dxa: Optional[int] = None
+    width_type: Optional[str] = None
+    alignment: Optional[str] = None
+
+@dataclass
+class ImageRef:
+    rel_id: str
+    width_emu: int
+    height_emu: int
+    para_align: Optional[str] = None
+    spacing_before: int = 0
+    spacing_after: int = 0
+
+@dataclass
+class SectionBreak:
+    margin_top: int = 1440
+    margin_bottom: int = 1440
+    margin_left: int = 1440
+    margin_right: int = 1440
+
+# ─── Color naming ─────────────────────────────────────────────────────────────
+# Well-known brand colors get readable names. Everything else is auto-named by
+# hue + lightness so you get e.g. "navyDark" instead of "color2C4A6E".
+_KNOWN_COLORS = {
+    '973A38': 'accent',
+    '59575A': 'body',
+    '8C8C8C': 'subtle',
+    'DDDDDD': 'rule',
+    'CCCCCC': 'border',
+    'F0E8E8': 'tintLight',
+    'F2F2F2': 'offWhite',
+    'D9D9D9': 'lightGray',
+    'E8E8E8': 'veryLightGray',
+    'D0A0A0': 'tintMid',
+    'F9F0F0': 'tintFaint',
+    '1A1A1A': 'nearBlack',
+    'FFFFFF': 'white',
+    '000000': 'black',
+}
+
+def _auto_color_name(hex6: str) -> str:
+    """Derive a readable JS identifier from an unknown hex color using hue + lightness."""
+    try:
+        r = int(hex6[0:2], 16) / 255
+        g = int(hex6[2:4], 16) / 255
+        b = int(hex6[4:6], 16) / 255
+    except ValueError:
+        return f'color{hex6}'
+
+    h, l, s = colorsys.rgb_to_hls(r, g, b)
+
+    # Lightness buckets
+    if l >= 0.92:   tone = 'Faint'
+    elif l >= 0.80: tone = 'Light'
+    elif l >= 0.60: tone = 'Mid'
+    elif l >= 0.40: tone = 'Base'
+    elif l >= 0.20: tone = 'Dark'
+    else:           tone = 'Deep'
+
+    # If very desaturated treat as gray
+    if s < 0.08:
+        return f'gray{tone}'
+
+    hue_deg = h * 360
+    if hue_deg < 20:    hue = 'red'
+    elif hue_deg < 45:  hue = 'orange'
+    elif hue_deg < 70:  hue = 'yellow'
+    elif hue_deg < 150: hue = 'green'
+    elif hue_deg < 195: hue = 'teal'
+    elif hue_deg < 255: hue = 'blue'
+    elif hue_deg < 285: hue = 'indigo'
+    elif hue_deg < 330: hue = 'purple'
+    else:               hue = 'red'
+
+    # Special-case common hues people actually name
+    if hue == 'blue' and hue_deg >= 210 and hue_deg <= 245 and l < 0.45:
+        hue = 'navy'
+
+    return f'{hue}{tone}'
+
+def _name_color(hex6: str, existing_names: set) -> str:
+    """Return a JS-safe unique name for a hex color, avoiding collisions."""
+    key = hex6.upper()
+    if key in _KNOWN_COLORS:
+        return _KNOWN_COLORS[key]
+    base = _auto_color_name(key)
+    name = base
+    n = 2
+    while name in existing_names:
+        name = f'{base}{n}'
+        n += 1
+    return name
+
+def build_color_map(colors: list) -> dict:
+    """Map a list of hex color strings to unique, readable JS constant names."""
+    color_map = {}
+    used_names = set()
+    for hex_color in colors:
+        name = _name_color(hex_color, used_names)
+        color_map[hex_color] = name
+        used_names.add(name)
+    return color_map
+
+# ─── Bracket placeholder → data field name ───────────────────────────────────
+BRACKET_FIELD_MAP = {
+    'client name':        'data.clientName',
+    'client':             'data.clientName',
+    'proposal title':     'data.title',
+    'document title':     'data.title',
+    'title':              'data.title',
+    'month day, year':    'data.date',
+    'date':               'data.date',
+    'draft / final':      'data.status',
+    'status':             'data.status',
+    'prepared by':        'data.preparedBy',
+    'contact name':       'data.contactName',
+    'company name':       'data.companyName',
+    'brief description of services': 'data.serviceDescription',
+    'brief description':  'data.description',
+}
+
+def bracket_to_field(text):
+    """
+    If text looks like a single template placeholder e.g. '[Client Name]',
+    return the JS data field reference. Otherwise return None (keep as literal).
+
+    Rules:
+    - Must be a single [bracket] — multi-bracket text handled by split_bracket_runs
+    - Instructional text (> 5 words or > 50 chars inside brackets) is treated as a
+      static literal, not a data field — those are human-readable instructions the
+      template author wrote, not machine placeholders
+    """
+    stripped = text.strip()
+    if not (stripped.startswith('[') and stripped.endswith(']')):
+        return None
+    if stripped.count('[') != 1:
+        return None
+    inner = stripped[1:-1].strip()
+    # Long instructional text — keep as literal
+    if len(inner) > 50 or len(inner.split()) > 5:
+        return None
+    inner_lower = inner.lower()
+    if inner_lower in BRACKET_FIELD_MAP:
+        return BRACKET_FIELD_MAP[inner_lower]
+    for key, val in BRACKET_FIELD_MAP.items():
+        if key in inner_lower:
+            return val
+    # Auto-generate camelCase field name
+    words = re.sub(r'[^a-zA-Z0-9 ]', '', inner).split()
+    if not words:
+        return None
+    camel = words[0].lower() + ''.join(w.title() for w in words[1:])
+    return f'data.{camel}'
+
+def split_bracket_runs(text):
+    """
+    Split a text run that contains multiple [bracket] placeholders into a list
+    of (text_segment, is_placeholder) tuples so each can be emitted separately.
+
+    e.g. '[Foo] — [Bar]' → [('[Foo]', True), (' — ', False), ('[Bar]', True)]
+    """
+    parts = []
+    for seg in re.split(r'(\[[^\[\]]+\])', text):
+        if not seg:
+            continue
+        is_ph = bool(re.match(r'^\[[^\[\]]+\]$', seg))
+        parts.append((seg, is_ph))
+    return parts
+
+# ─── Parser ───────────────────────────────────────────────────────────────────
+class DocxParser:
+    def __init__(self, docx_path):
+        self.path = docx_path
+        self.body_elements = []
+        self.header_elements = []
+        self.footer_elements = []
+        self.media_files = []       # zip paths, e.g. ['word/media/image1.png']
+        self.media_bytes = {}       # filename -> bytes, written to assets/ by main()
+        self.relationships = {}     # rId -> target path
+        self.hyperlink_rels = {}    # rId -> URL (from document.xml.rels where Type=hyperlink)
+        self.colors = []
+        self._parse()
+
+    def _parse(self):
+        with zipfile.ZipFile(self.path, 'r') as z:
+            names = z.namelist()
+            self.media_files = [f for f in names if 'word/media/' in f and os.path.basename(f)]
+
+            # Extract image bytes while the zip is open
+            for mf in self.media_files:
+                fname = os.path.basename(mf)
+                if fname:
+                    self.media_bytes[fname] = z.read(mf)
+
+            # Relationships (images + hyperlinks)
+            if 'word/_rels/document.xml.rels' in names:
+                with z.open('word/_rels/document.xml.rels') as f:
+                    rels_tree = ET.parse(f)
+                for rel in rels_tree.getroot():
+                    rid    = rel.get('Id', '')
+                    target = rel.get('Target', '')
+                    rtype  = rel.get('Type', '')
+                    self.relationships[rid] = target
+                    if 'hyperlink' in rtype:
+                        self.hyperlink_rels[rid] = target
+
+            # Document body
+            with z.open('word/document.xml') as f:
+                doc_tree = ET.parse(f)
+            body = doc_tree.getroot().find(qn('w:body'))
+            self.body_elements = self._parse_body(body)
+
+            # Header (use first one found)
+            for fname in sorted(f for f in names if re.match(r'word/header\d+\.xml', f)):
+                with z.open(fname) as f:
+                    h_tree = ET.parse(f)
+                self.header_elements = self._parse_paragraphs_from(h_tree.getroot())
+                break
+
+            # Footer (use first one found)
+            for fname in sorted(f for f in names if re.match(r'word/footer\d+\.xml', f)):
+                with z.open(fname) as f:
+                    ft_tree = ET.parse(f)
+                self.footer_elements = self._parse_paragraphs_from(ft_tree.getroot())
+                break
+
+        self._extract_colors()
+
+    def _parse_body(self, body):
+        elements = []
+        for child in body:
+            tag = child.tag
+            if tag == qn('w:p'):
+                parsed = self._parse_para(child)
+                if parsed is not None:
+                    elements.append(parsed)
+            elif tag == qn('w:tbl'):
+                elements.append(self._parse_table(child))
+            elif tag == qn('w:sectPr'):
+                elements.append(self._parse_section(child))
+        return elements
+
+    def _parse_paragraphs_from(self, root):
+        elements = []
+        for child in root:
+            if child.tag == qn('w:p'):
+                parsed = self._parse_para(child)
+                if parsed is not None:
+                    elements.append(parsed)
+        return elements
+
+    def _parse_para(self, p_el):
+        pPr = p_el.find(qn('w:pPr'))
+        para = ParaFormat()
+
+        # Inline section break
+        if pPr is not None:
+            sect = pPr.find(qn('w:sectPr'))
+            if sect is not None:
+                return self._parse_section(sect)
+
+        if pPr is not None:
+            jc = pPr.find(qn('w:jc'))
+            if jc is not None:
+                v = jc.get(qn('w:val'), '')
+                para.alignment = {'center': 'CENTER', 'right': 'RIGHT', 'both': 'BOTH'}.get(v, 'LEFT')
+
+            sp = pPr.find(qn('w:spacing'))
+            if sp is not None:
+                b = sp.get(qn('w:before'), '0')
+                a = sp.get(qn('w:after'),  '0')
+                para.spacing_before = int(b) if str(b).isdigit() else 0
+                para.spacing_after  = int(a) if str(a).isdigit() else 0
+
+            pBdr = pPr.find(qn('w:pBdr'))
+            if pBdr is not None:
+                for side in ['top', 'bottom']:
+                    bdr = pBdr.find(qn(f'w:{side}'))
+                    if bdr is not None:
+                        binfo = {
+                            'style': bdr.get(qn('w:val'), 'single'),
+                            'size':  int(bdr.get(qn('w:sz'), '4')),
+                            'color': bdr.get(qn('w:color'), '000000'),
+                            'space': int(bdr.get(qn('w:space'), '0')),
+                        }
+                        if side == 'top': para.border_top = binfo
+                        else:             para.border_bottom = binfo
+
+            pStyle = pPr.find(qn('w:pStyle'))
+            if pStyle is not None:
+                para.style = pStyle.get(qn('w:val'))
+
+            if pPr.find(qn('w:numPr')) is not None:
+                para.is_bullet = True
+
+            tabs = pPr.find(qn('w:tabs'))
+            if tabs is not None:
+                for tab in tabs.findall(qn('w:tab')):
+                    if tab.get(qn('w:val')) == 'right':
+                        pos = tab.get(qn('w:pos'))
+                        if pos:
+                            para.tab_stop_right = int(pos)
+
+        # Walk children: runs, hyperlinks, drawings
+        inside_cached_field = False
+        for child in p_el:
+            tag = child.tag
+
+            if tag == qn('w:r'):
+                fld = child.find(qn('w:fldChar'))
+                if fld is not None:
+                    ftype = fld.get(qn('w:fldCharType'), '')
+                    if ftype == 'begin': inside_cached_field = True
+                    elif ftype == 'end': inside_cached_field = False
+                    continue
+
+                drawing = child.find(qn('w:drawing'))
+                if drawing is not None:
+                    img = self._parse_drawing(drawing)
+                    if img:
+                        img.para_align     = para.alignment
+                        img.spacing_before = para.spacing_before
+                        img.spacing_after  = para.spacing_after
+                        return img
+                    continue
+
+                run = self._parse_run(child, is_cached=inside_cached_field)
+                if run:
+                    para.runs.append(run)
+
+            elif tag == qn('w:hyperlink'):
+                # Resolve URL from relationship ID or inline anchor
+                rid = child.get(qn('r:id'), '')
+                url = self.hyperlink_rels.get(rid, child.get(qn('w:anchor'), ''))
+                for r_el in child.findall(qn('w:r')):
+                    run = self._parse_run(r_el, is_cached=inside_cached_field)
+                    if run:
+                        run.hyperlink_url = url
+                        para.runs.append(run)
+
+            elif tag == qn('w:drawing'):
+                img = self._parse_drawing(child)
+                if img:
+                    img.para_align     = para.alignment
+                    img.spacing_before = para.spacing_before
+                    img.spacing_after  = para.spacing_after
+                    return img
+
+        for br in p_el.findall(f'.//{qn("w:br")}'):
+            if br.get(qn('w:type')) == 'page':
+                para.is_page_break = True
+
+        return para
+
+    def _parse_run(self, r_el, is_cached=False):
+        if r_el.find(qn('w:drawing')) is not None:
+            return None
+
+        run = RunFormat()
+        run.is_cached_field = is_cached
+
+        rPr = r_el.find(qn('w:rPr'))
+        if rPr is not None:
+            run.bold    = _bool_prop(rPr, 'w:b')
+            run.italic  = _bool_prop(rPr, 'w:i')
+            run.allCaps = _bool_prop(rPr, 'w:caps')
+
+            fonts_el = rPr.find(qn('w:rFonts'))
+            if fonts_el is not None:
+                run.font = fonts_el.get(qn('w:ascii'), 'Calibri')
+
+            sz = rPr.find(qn('w:sz'))
+            if sz is not None:
+                hp = sz.get(qn('w:val'))
+                if hp:
+                    run.size = int(hp)
+
+            color_el = rPr.find(qn('w:color'))
+            if color_el is not None:
+                c = color_el.get(qn('w:val'))
+                if c and c != 'auto':
+                    run.color = c
+
+        # Field instruction (PAGE / NUMPAGES)
+        instr = r_el.find(qn('w:instrText'))
+        if instr is not None:
+            text = (instr.text or '').strip()
+            if text in ('PAGE', 'NUMPAGES'):
+                run.is_page_number = True
+                run.is_cached_field = False
+                run.text = text
+                return run
+            return None
+
+        if r_el.find(qn('w:tab')) is not None:
+            run.is_tab = True
+            run.text = '\t'
+            return run
+
+        t = r_el.find(qn('w:t'))
+        if t is not None and t.text:
+            run.text = t.text
+            return run
+
+        return None
+
+    def _parse_drawing(self, drawing_el):
+        extent = drawing_el.find(f'.//{qn("wp:extent")}')
+        if extent is None:
+            return None
+        cx = int(extent.get('cx', 0))
+        cy = int(extent.get('cy', 0))
+
+        blip = drawing_el.find(f'.//{qn("a:blip")}')
+        if blip is None:
+            return None
+        rel_id = blip.get(qn('r:embed'))
+        if not rel_id:
+            return None
+
+        return ImageRef(rel_id=rel_id, width_emu=cx, height_emu=cy)
+
+    def _parse_table(self, tbl_el):
+        table = TableFormat()
+        tblPr = tbl_el.find(qn('w:tblPr'))
+
+        if tblPr is not None:
+            tblW = tblPr.find(qn('w:tblW'))
+            if tblW is not None:
+                table.width_dxa  = int(tblW.get(qn('w:w'), 0))
+                table.width_type = tblW.get(qn('w:type'), 'dxa')
+            jc = tblPr.find(qn('w:jc'))
+            if jc is not None:
+                table.alignment = jc.get(qn('w:val'), 'left').upper()
+
+        for tr in tbl_el.findall(qn('w:tr')):
+            row = [self._parse_cell(tc) for tc in tr.findall(qn('w:tc'))]
+            if row:
+                table.rows.append(row)
+
+        return table
+
+    def _parse_cell(self, tc_el):
+        cell = CellFormat()
+        tcPr = tc_el.find(qn('w:tcPr'))
+
+        if tcPr is not None:
+            tcW = tcPr.find(qn('w:tcW'))
+            if tcW is not None:
+                cell.width_dxa = int(tcW.get(qn('w:w'), 0))
+
+            shd = tcPr.find(qn('w:shd'))
+            if shd is not None:
+                fill = shd.get(qn('w:fill'))
+                if fill and fill.upper() not in ('AUTO', 'FFFFFF'):
+                    cell.shading = fill.upper()
+
+            tcMar = tcPr.find(qn('w:tcMar'))
+            if tcMar is not None:
+                for side, attr_name in [('top','margin_top'),('bottom','margin_bottom'),
+                                        ('left','margin_left'),('right','margin_right')]:
+                    m = tcMar.find(qn(f'w:{side}'))
+                    if m is not None:
+                        setattr(cell, attr_name, int(m.get(qn('w:w'), '0')))
+
+            tcBdr = tcPr.find(qn('w:tcBorders'))
+            if tcBdr is not None:
+                top_bdr = tcBdr.find(qn('w:top'))
+                if top_bdr is not None:
+                    cell.border_color = top_bdr.get(qn('w:color'))
+
+            vAlign = tcPr.find(qn('w:vAlign'))
+            if vAlign is not None:
+                cell.valign = vAlign.get(qn('w:val'))
+
+        for p in tc_el.findall(qn('w:p')):
+            parsed = self._parse_para(p)
+            if parsed is not None:
+                cell.paragraphs.append(parsed)
+
+        return cell
+
+    def _parse_section(self, sect_el):
+        s = SectionBreak()
+        pgMar = sect_el.find(qn('w:pgMar'))
+        if pgMar is not None:
+            s.margin_top    = int(pgMar.get(qn('w:top'),    1440))
+            s.margin_bottom = int(pgMar.get(qn('w:bottom'), 1440))
+            s.margin_left   = int(pgMar.get(qn('w:left'),   1440))
+            s.margin_right  = int(pgMar.get(qn('w:right'),  1440))
+        return s
+
+    def _extract_colors(self):
+        colors = set()
+        def scan(elements):
+            for el in elements:
+                if isinstance(el, ParaFormat):
+                    for r in el.runs:
+                        if r.color: colors.add(r.color.upper())
+                    if el.border_bottom: colors.add(el.border_bottom['color'].upper())
+                    if el.border_top:    colors.add(el.border_top['color'].upper())
+                elif isinstance(el, TableFormat):
+                    for row in el.rows:
+                        for cell in row:
+                            if cell.shading:      colors.add(cell.shading.upper())
+                            if cell.border_color: colors.add(cell.border_color.upper())
+                            scan(cell.paragraphs)
+        scan(self.body_elements)
+        scan(self.header_elements)
+        scan(self.footer_elements)
+        self.colors = sorted(colors)
+
+    def list_summary(self):
+        """Return a human-readable summary of what was found in the template."""
+        sections = [el for el in self.body_elements if isinstance(el, SectionBreak)]
+        images   = [el for el in self.body_elements if isinstance(el, ImageRef)]
+        tables   = [el for el in self.body_elements if isinstance(el, TableFormat)]
+        paras    = [el for el in self.body_elements if isinstance(el, ParaFormat)]
+        hyperlinks = set()
+        def find_links(elements):
+            for el in elements:
+                if isinstance(el, ParaFormat):
+                    for r in el.runs:
+                        if r.hyperlink_url:
+                            hyperlinks.add(r.hyperlink_url)
+                elif isinstance(el, TableFormat):
+                    for row in el.rows:
+                        for cell in row:
+                            find_links(cell.paragraphs)
+        find_links(self.body_elements)
+
+        placeholders = {}
+        def find_placeholders(elements):
+            for el in elements:
+                if isinstance(el, ParaFormat):
+                    for r in el.runs:
+                        if r.text:
+                            for seg, is_ph in split_bracket_runs(r.text):
+                                if is_ph:
+                                    f = bracket_to_field(seg)
+                                    if f:
+                                        placeholders[f.replace('data.','')] = seg
+                elif isinstance(el, TableFormat):
+                    for row in el.rows:
+                        for cell in row:
+                            find_placeholders(cell.paragraphs)
+        find_placeholders(self.body_elements)
+
+        lines = [
+            f"Template: {os.path.basename(self.path)}",
+            f"  Sections   : {len(sections) + 1}  (section breaks found: {len(sections)})",
+            f"  Body paras : {len(paras)}",
+            f"  Tables     : {len(tables)}",
+            f"  Images     : {len(images)}  {[os.path.basename(self.relationships.get(i.rel_id,'?')) for i in images]}",
+            f"  Colors     : {self.colors}",
+            f"  Header     : {len(self.header_elements)} paragraph(s)",
+            f"  Footer     : {len(self.footer_elements)} paragraph(s)",
+        ]
+        if placeholders:
+            lines.append(f"  Placeholders detected:")
+            for name, raw in placeholders.items():
+                lines.append(f"    data.{name}  <-  {raw}")
+        if hyperlinks:
+            lines.append(f"  Hyperlinks:")
+            for url in sorted(hyperlinks):
+                lines.append(f"    {url}")
+        return '\n'.join(lines)
+
+# ─── Code Generator ──────────────────────────────────────────────────────────
+class JSGenerator:
+    def __init__(self, parser: DocxParser, template_name: str):
+        self.p    = parser
+        self.name = template_name
+        self.color_map = build_color_map(parser.colors)
+        self.inferred_data_fields = {}  # field_name -> example value
+
+    def _color_ref(self, hex_color):
+        if not hex_color:
+            return "'000000'"
+        key = hex_color.upper()
+        return f"COLOR.{self.color_map[key]}" if key in self.color_map else f"'{hex_color}'"
+
+    def _emu_to_inch(self, emu):
+        return round(emu / 914400, 3)
+
+    def _run_to_js_parts(self, r: RunFormat, indent: str) -> list:
+        """
+        Convert a RunFormat to one or more JS TextRun/ExternalHyperlink strings.
+        Returns a list (usually one item) because a run with multiple [brackets]
+        gets split into multiple TextRuns.
+        """
+        if r.is_cached_field:
+            return []
+
+        if r.is_tab:
+            return [f"{indent}new TextRun({{ text: '\\t', font: FONT, size: {r.size or 22}, color: {self._color_ref(r.color)} }}),"]
+
+        if r.is_page_number:
+            field = 'PageNumber.CURRENT' if r.text == 'PAGE' else 'PageNumber.TOTAL_PAGES'
+            return [f"{indent}new TextRun({{ children: [{field}], font: FONT, size: {r.size or 22}, color: {self._color_ref(r.color)} }}),"]
+
+        if not r.text:
+            return []
+
+        # Split into bracket segments so '[Foo] — [Bar]' emits two TextRuns
+        segments = split_bracket_runs(r.text)
+        results = []
+        for seg_text, is_placeholder in segments:
+            field_ref = bracket_to_field(seg_text) if is_placeholder else None
+            if field_ref:
+                field_name = field_ref.replace('data.', '')
+                if field_name not in self.inferred_data_fields:
+                    self.inferred_data_fields[field_name] = seg_text.strip('[]')
+                text_expr = field_ref
+            else:
+                escaped = seg_text.replace('\\', '\\\\').replace("'", "\\'")
+                text_expr = f"'{escaped}'"
+
+            opts = [f"text: {text_expr}", "font: FONT"]
+            if r.size:    opts.append(f"size: {r.size}")
+            if r.bold:    opts.append("bold: true")
+            if r.italic:  opts.append("italics: true")
+            if r.allCaps: opts.append("allCaps: true")
+            if r.color:   opts.append(f"color: {self._color_ref(r.color)}")
+
+            run_js = f"new TextRun({{ {', '.join(opts)} }})"
+
+            if r.hyperlink_url:
+                escaped_url = r.hyperlink_url.replace("'", "\\'")
+                results.append(f"{indent}new ExternalHyperlink({{ link: '{escaped_url}', children: [{run_js}] }}),")
+            else:
+                results.append(f"{indent}{run_js},")
+
+        return results
+
+    def _para_to_js(self, para: ParaFormat, indent: str) -> Optional[str]:
+        if not isinstance(para, ParaFormat):
+            return None
+        if para.is_page_break:
+            return f"{indent}new Paragraph({{ pageBreakBefore: true }}),"
+
+        lines = [f"{indent}new Paragraph({{"]
+
+        run_lines = []
+        for r in para.runs:
+            run_lines.extend(self._run_to_js_parts(r, indent + '    '))
+
+        if run_lines:
+            lines.append(f"{indent}  children: [")
+            lines.extend(run_lines)
+            lines.append(f"{indent}  ],")
+        else:
+            lines.append(f"{indent}  children: [],")
+
+        if para.alignment and para.alignment != 'LEFT':
+            lines.append(f"{indent}  alignment: AlignmentType.{para.alignment},")
+
+        if para.spacing_before or para.spacing_after:
+            lines.append(f"{indent}  spacing: {{ before: {para.spacing_before}, after: {para.spacing_after} }},")
+
+        borders = {}
+        if para.border_top:
+            b = para.border_top
+            borders['top'] = f"{{ style: BorderStyle.SINGLE, size: {b['size']}, color: {self._color_ref(b['color'])}, space: {b['space']} }}"
+        if para.border_bottom:
+            b = para.border_bottom
+            borders['bottom'] = f"{{ style: BorderStyle.SINGLE, size: {b['size']}, color: {self._color_ref(b['color'])}, space: {b['space']} }}"
+        if borders:
+            bstr = ', '.join(f"{k}: {v}" for k, v in borders.items())
+            lines.append(f"{indent}  border: {{ {bstr} }},")
+
+        if para.tab_stop_right:
+            lines.append(f"{indent}  tabStops: [{{ type: TabStopType.RIGHT, position: TabStopPosition.MAX }}],")
+
+        if para.is_bullet:
+            lines.append(f"{indent}  bullet: {{ level: 0 }},")
+
+        lines.append(f"{indent}}})," )
+        return '\n'.join(lines)
+
+    def _image_to_js(self, img: ImageRef, indent: str) -> str:
+        target   = self.p.relationships.get(img.rel_id, '')
+        fname    = os.path.basename(target) or 'image.png'
+        var_name = re.sub(r'[^a-zA-Z0-9]', '_', os.path.splitext(fname)[0]).upper() + '_PATH'
+        ext      = os.path.splitext(fname)[1].lstrip('.').lower() or 'png'
+        w_pt     = round(self._emu_to_inch(img.width_emu)  * 72)
+        h_pt     = round(self._emu_to_inch(img.height_emu) * 72)
+
+        lines = [
+            f"{indent}new Paragraph({{",
+            f"{indent}  children: [",
+            f"{indent}    new ImageRun({{",
+            f"{indent}      data: readFileSync({var_name}),",
+            f"{indent}      transformation: {{ width: {w_pt}, height: {h_pt} }},",
+            f"{indent}      type: '{ext}',",
+            f"{indent}    }}),",
+            f"{indent}  ],",
+        ]
+        if img.para_align and img.para_align != 'LEFT':
+            lines.append(f"{indent}  alignment: AlignmentType.{img.para_align},")
+        if img.spacing_before or img.spacing_after:
+            lines.append(f"{indent}  spacing: {{ before: {img.spacing_before}, after: {img.spacing_after} }},")
+        lines.append(f"{indent}}})," )
+        return '\n'.join(lines)
+
+    def _table_to_js(self, table: TableFormat, indent: str) -> str:
+        lines = [f"{indent}new Table({{"]
+
+        if table.width_type == 'pct' or (table.width_dxa and table.width_dxa > 8000):
+            lines.append(f"{indent}  width: {{ size: 100, type: WidthType.PERCENTAGE }},")
+        elif table.width_dxa:
+            lines.append(f"{indent}  width: {{ size: {table.width_dxa}, type: WidthType.DXA }},")
+
+        if table.alignment:
+            lines.append(f"{indent}  alignment: AlignmentType.{table.alignment},")
+
+        lines.append(f"{indent}  rows: [")
+        for row in table.rows:
+            lines.append(f"{indent}    new TableRow({{")
+            lines.append(f"{indent}      children: [")
+            total_w = sum(c.width_dxa or 0 for c in row)
+            for cell in row:
+                lines += self._cell_to_js(cell, total_w, indent + '        ')
+            lines.append(f"{indent}      ],")
+            lines.append(f"{indent}    }}),")
+        lines.append(f"{indent}  ],")
+        lines.append(f"{indent}}})," )
+        return '\n'.join(lines)
+
+    def _cell_to_js(self, cell: CellFormat, total_width: int, indent: str) -> list:
+        lines = [f"{indent}new TableCell({{"]
+
+        if cell.width_dxa and total_width:
+            pct = round(cell.width_dxa / total_width * 100)
+            lines.append(f"{indent}  width: {{ size: {pct}, type: WidthType.PERCENTAGE }},")
+
+        if cell.shading:
+            lines.append(f"{indent}  shading: {{ fill: {self._color_ref(cell.shading)} }},")
+
+        bc = self._color_ref(cell.border_color) if cell.border_color else "'DDDDDD'"
+        lines += [
+            f"{indent}  borders: {{",
+            f"{indent}    top:    {{ style: BorderStyle.SINGLE, size: 4, color: {bc} }},",
+            f"{indent}    bottom: {{ style: BorderStyle.SINGLE, size: 4, color: {bc} }},",
+            f"{indent}    left:   {{ style: BorderStyle.SINGLE, size: 4, color: {bc} }},",
+            f"{indent}    right:  {{ style: BorderStyle.SINGLE, size: 4, color: {bc} }},",
+            f"{indent}  }},",
+        ]
+
+        if any([cell.margin_top, cell.margin_bottom, cell.margin_left, cell.margin_right]):
+            lines.append(f"{indent}  margins: {{")
+            for side, val in [('top',cell.margin_top),('bottom',cell.margin_bottom),
+                               ('left',cell.margin_left),('right',cell.margin_right)]:
+                if val: lines.append(f"{indent}    {side}: {val},")
+            lines.append(f"{indent}  }},")
+
+        lines.append(f"{indent}  children: [")
+        for para in cell.paragraphs:
+            pjs = self._para_to_js(para, indent + '    ')
+            if pjs:
+                lines.append(pjs)
+        lines.append(f"{indent}  ],")
+
+        if cell.valign:
+            lines.append(f"{indent}  verticalAlign: '{cell.valign}',")
+
+        lines.append(f"{indent}}})," )
+        return lines
+
+    # ── Section generators ───────────────────────────────────────────────────
+
+    def _gen_file_header(self):
+        # Check whether any hyperlinks exist so we know whether to import ExternalHyperlink
+        has_hyperlinks = any(
+            r.hyperlink_url
+            for el in self.p.body_elements + self.p.header_elements + self.p.footer_elements
+            if isinstance(el, ParaFormat)
+            for r in el.runs
+        )
+        self._has_hyperlinks = has_hyperlinks
+
+        basename = os.path.basename(self.p.path)
+        hyperlink_import = ', ExternalHyperlink' if has_hyperlinks else ''
+        return [
+            f'/**',
+            f' * {self.name.title()} Document Builder',
+            f' * Auto-generated by docx-to-builder  https://github.com/jermorrison22/docx-to-builder',
+            f' * Source template: {basename}',
+            f' * Generated: {__import__("datetime").date.today().isoformat()}',
+            f' *',
+            f' * HOW TO USE:',
+            f' *   1. Fill in the data object below (or pass your own)',
+            f' *   2. Run:  node {self.name}-builder.js',
+            f' *   3. Find the output at: output/{self.name}-output.docx',
+            f' *',
+            f' * To regenerate this file from a new template:',
+            f' *   python3 docx-to-builder.py your-template.docx',
+            f' */',
+            '',
+            "import {",
+            f"  Document, Packer, Paragraph, TextRun, ImageRun{hyperlink_import},",
+            "  Table, TableRow, TableCell, WidthType, AlignmentType,",
+            "  BorderStyle, Header, Footer, PageNumber,",
+            "  TabStopType, TabStopPosition, convertInchesToTwip,",
+            "} from 'docx';",
+            "import { readFileSync, writeFileSync, mkdirSync } from 'fs';",
+            "import { fileURLToPath } from 'url';",
+            "import { dirname, join } from 'path';",
+            "",
+            "const __dirname = dirname(fileURLToPath(import.meta.url));",
+            "",
+        ]
+
+    def _gen_constants(self):
+        lines = [
+            "// ─── Brand colors extracted from template ────────────────────────────────────",
+            "const COLOR = {",
+        ]
+        for hex_color, name in sorted(self.color_map.items(), key=lambda x: x[1]):
+            lines.append(f"  {name}: '{hex_color}',")
+        lines += ["};", ""]
+
+        fonts = {}
+        def scan(els):
+            for el in els:
+                if isinstance(el, ParaFormat):
+                    for r in el.runs:
+                        fonts[r.font] = fonts.get(r.font, 0) + 1
+                elif isinstance(el, TableFormat):
+                    for row in el.rows:
+                        for cell in row:
+                            scan(cell.paragraphs)
+        scan(self.p.body_elements)
+        main_font = max(fonts, key=fonts.get) if fonts else 'Calibri'
+        lines += [f"const FONT = '{main_font}';", ""]
+
+        if self.p.media_files:
+            lines.append("// ─── Asset paths — update these if you move the image files ─────────────────")
+            for media in self.p.media_files:
+                fname = os.path.basename(media)
+                if not fname:
+                    continue
+                var = re.sub(r'[^a-zA-Z0-9]', '_', os.path.splitext(fname)[0]).upper() + '_PATH'
+                lines.append(f"const {var} = join(__dirname, 'assets/{fname}');")
+            lines.append("")
+
+        return lines
+
+    def _gen_header_fn(self):
+        lines = [
+            "// ─── Header ───────────────────────────────────────────────────────────────────",
+            "function buildHeader(data) {",
+            "  return new Header({",
+            "    children: [",
+        ]
+        for el in self.p.header_elements:
+            if isinstance(el, ParaFormat):
+                pjs = self._para_to_js(el, '      ')
+                if pjs:
+                    lines.append(pjs)
+        lines += ["    ],", "  });", "}", ""]
+        return lines
+
+    def _gen_footer_fn(self):
+        lines = [
+            "// ─── Footer ───────────────────────────────────────────────────────────────────",
+            "function buildFooter() {",
+            "  return new Footer({",
+            "    children: [",
+        ]
+        for el in self.p.footer_elements:
+            if isinstance(el, ParaFormat):
+                pjs = self._para_to_js(el, '      ')
+                if pjs:
+                    lines.append(pjs)
+        lines += ["    ],", "  });", "}", ""]
+        return lines
+
+    def _elements_to_js(self, elements, indent='  ', is_first_section=True) -> list:
+        """Convert a list of body elements to JS lines (used per-section)."""
+        # Strip trailing page-break paragraphs — the section boundary itself
+        # already forces a new page, so a pageBreakBefore at the end of a section
+        # produces a blank page.
+        trimmed = list(elements)
+        while trimmed and isinstance(trimmed[-1], ParaFormat) and trimmed[-1].is_page_break:
+            trimmed.pop()
+
+        # Also strip leading page-break paragraphs from non-first sections —
+        # the section start already puts us on a new page.
+        if not is_first_section:
+            while trimmed and isinstance(trimmed[0], ParaFormat) and trimmed[0].is_page_break:
+                trimmed.pop(0)
+
+        elements = trimmed
+
+        lines = []
+        for el in elements:
+            if isinstance(el, SectionBreak):
+                continue  # handled at the section boundary level
+
+            if isinstance(el, ImageRef):
+                target = self.p.relationships.get(el.rel_id, '')
+                fname  = os.path.basename(target) or 'image.png'
+                w_in   = self._emu_to_inch(el.width_emu)
+                h_in   = self._emu_to_inch(el.height_emu)
+                lines.append(f"{indent}// Image: {fname}  ({w_in}\" x {h_in}\")")
+                lines.append(f"{indent}elements.push(")
+                lines.append(self._image_to_js(el, indent + '  '))
+                lines.append(f"{indent});")
+                lines.append("")
+
+            elif isinstance(el, ParaFormat):
+                if el.is_page_break:
+                    lines.append(f"{indent}elements.push(new Paragraph({{ pageBreakBefore: true }}));")
+                    lines.append("")
+                    continue
+                pjs = self._para_to_js(el, indent + '  ')
+                if pjs:
+                    preview = ' '.join(
+                        r.text for r in el.runs
+                        if r.text and not r.is_tab and not r.is_page_number and not r.is_cached_field
+                    )[:60]
+                    if preview:
+                        lines.append(f"{indent}// {repr(preview)}")
+                    lines.append(f"{indent}elements.push(")
+                    lines.append(pjs)
+                    lines.append(f"{indent});")
+                    lines.append("")
+
+            elif isinstance(el, TableFormat):
+                n_rows = len(el.rows)
+                n_cols = max((len(r) for r in el.rows), default=0)
+                lines.append(f"{indent}// Table ({n_rows} rows x {n_cols} cols)")
+                lines.append(f"{indent}elements.push(")
+                lines.append(self._table_to_js(el, indent + '  '))
+                lines.append(f"{indent});")
+                lines.append("")
+
+        return lines
+
+    def _gen_content_fn(self):
+        """
+        Split body elements at SectionBreak boundaries and generate one
+        buildSection_N() function per section, plus a buildContent() that
+        returns the full array.
+        """
+        # Partition body_elements into sections
+        sections_data = []  # list of (section_break, [elements before next break])
+        current = []
+        current_break = None
+        for el in self.p.body_elements:
+            if isinstance(el, SectionBreak):
+                sections_data.append((current_break, current))
+                current = []
+                current_break = el
+            else:
+                current.append(el)
+        # Don't forget trailing elements after last break
+        sections_data.append((current_break, current))
+
+        lines = [
+            "// ─── Document content ────────────────────────────────────────────────────────",
+            "// Bracketed placeholders (e.g. [Client Name]) have been mapped to data.fieldName.",
+            "// Static template text is kept as-is. Replace any literal string with a data",
+            "// field if you need it to be dynamic.",
+            "",
+        ]
+
+        fn_names = []
+        for i, (sec_break, elements) in enumerate(sections_data):
+            fn = f'buildSection{i + 1}'
+            fn_names.append((fn, sec_break))
+            comment = ''
+            if sec_break:
+                comment = f' // margins: T={sec_break.margin_top} B={sec_break.margin_bottom} L={sec_break.margin_left} R={sec_break.margin_right} (twips)'
+            lines.append(f"function {fn}(data) {{{comment}")
+            lines.append("  const elements = [];")
+            lines.append("")
+            lines.extend(self._elements_to_js(elements, '  ', is_first_section=(i == 0)))
+            lines.append("  return elements;")
+            lines.append("}")
+            lines.append("")
+
+        return lines, fn_names
+
+    def _gen_builder_fn(self, fn_names):
+        """Generate the main buildDocument() that wires sections together."""
+        lines = [
+            "// ─── Main builder ────────────────────────────────────────────────────────────",
+            "export async function buildDocument(data, outputPath) {",
+            "  const doc = new Document({",
+            "    sections: [",
+        ]
+
+        for fn, sec_break in fn_names:
+            sb = sec_break if sec_break else SectionBreak()
+            lines += [
+                "      {",
+                "        properties: {",
+                "          page: {",
+                "            margin: {",
+                f"              top:    convertInchesToTwip({sb.margin_top    / 1440:.3f}),",
+                f"              bottom: convertInchesToTwip({sb.margin_bottom / 1440:.3f}),",
+                f"              left:   convertInchesToTwip({sb.margin_left   / 1440:.3f}),",
+                f"              right:  convertInchesToTwip({sb.margin_right  / 1440:.3f}),",
+                "            },",
+                "          },",
+                "        },",
+                "        headers: { default: buildHeader(data) },",
+                "        footers: { default: buildFooter() },",
+                f"        children: {fn}(data),",
+                "      },",
+            ]
+
+        lines += [
+            "    ],",
+            "  });",
+            "",
+            "  const buffer = await Packer.toBuffer(doc);",
+            "  writeFileSync(outputPath, buffer);",
+            "  console.log('Document saved to: ' + outputPath);",
+            "}",
+            "",
+        ]
+        return lines
+
+    def _gen_example_data(self):
+        lines = [
+            "// ─── Data object ─────────────────────────────────────────────────────────────",
+            "// Fields below were inferred from bracketed placeholders in your template.",
+            "// Add, remove, or rename fields to match your use case.",
+            "const data = {",
+        ]
+        if self.inferred_data_fields:
+            for field_name, example in self.inferred_data_fields.items():
+                escaped = example.replace("'", "\\'")
+                lines.append(f"  {field_name}: '{escaped}',")
+        else:
+            lines.append("  title: 'Document Title',")
+            lines.append("  clientName: 'Client Name',")
+            lines.append("  date: new Date().toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' }),")
+        lines += ["};", ""]
+        return lines
+
+    def _gen_cli(self):
+        return [
+            "// ─── Run from command line ────────────────────────────────────────────────────",
+            "if (process.argv[1] === fileURLToPath(import.meta.url)) {",
+            "  const outputArg = process.argv.indexOf('--output');",
+            "  const outputPath = outputArg !== -1",
+            "    ? process.argv[outputArg + 1]",
+            f"    : join(__dirname, 'output/{self.name}-output.docx');",
+            "",
+            "  mkdirSync(join(__dirname, 'output'), { recursive: true });",
+            "  buildDocument(data, outputPath).catch(console.error);",
+            "}",
+        ]
+
+    def generate(self):
+        # Generate header first so _has_hyperlinks gets set
+        file_header = self._gen_file_header()
+        constants   = self._gen_constants()
+        header_fn   = self._gen_header_fn()
+        footer_fn   = self._gen_footer_fn()
+
+        # Content generation populates inferred_data_fields as a side-effect
+        content_lines, fn_names = self._gen_content_fn()
+        builder_fn  = self._gen_builder_fn(fn_names)
+        example     = self._gen_example_data()
+        cli         = self._gen_cli()
+
+        lines = []
+        lines += file_header
+        lines += constants
+        lines += header_fn
+        lines += footer_fn
+        lines += content_lines
+        lines += builder_fn
+        lines += example
+        lines += cli
+        return '\n'.join(lines)
+
+
+# ─── Main ─────────────────────────────────────────────────────────────────────
+def main():
+    if len(sys.argv) < 2:
+        print(__doc__)
+        sys.exit(1)
+
+    docx_path = sys.argv[1]
+    if not os.path.exists(docx_path):
+        print(f"Error: file not found: {docx_path}")
+        sys.exit(1)
+
+    list_mode = '--list' in sys.argv
+
+    # Determine output path
+    output_path = None
+    if '--output' in sys.argv:
+        idx = sys.argv.index('--output')
+        output_path = sys.argv[idx + 1]
+
+    # Derive a clean document name from the filename
+    basename = os.path.basename(docx_path)
+    name = re.sub(r'(?i)template\s*[-\u2013]\s*', '', basename)
+    name = os.path.splitext(name)[0].strip().lower()
+    name = re.sub(r'\s+', '-', name)
+    name = re.sub(r'[^a-z0-9-]', '', name)
+
+    if not output_path:
+        output_path = os.path.join(os.path.dirname(os.path.abspath(docx_path)), f'{name}-builder.js')
+
+    print(f"Parsing: {docx_path}")
+    parser = DocxParser(docx_path)
+
+    if list_mode:
+        print()
+        print(parser.list_summary())
+        return
+
+    sections = [el for el in parser.body_elements if isinstance(el, SectionBreak)]
+    print(f"  {len(parser.body_elements)} body elements  |  "
+          f"{len(parser.header_elements)} header  |  "
+          f"{len(parser.footer_elements)} footer  |  "
+          f"{len(parser.media_files)} image(s)  |  "
+          f"{len(sections) + 1} section(s)")
+    print(f"  Colors: {parser.colors}")
+
+    print("Generating JS builder...")
+    gen     = JSGenerator(parser, name)
+    js_code = gen.generate()
+
+    os.makedirs(os.path.dirname(os.path.abspath(output_path)), exist_ok=True)
+    with open(output_path, 'w', encoding='utf-8') as f:
+        f.write(js_code)
+
+    print(f"[OK] {output_path}")
+
+    # Extract embedded images into assets/ next to the builder
+    if parser.media_bytes:
+        assets_dir = os.path.join(os.path.dirname(os.path.abspath(output_path)), 'assets')
+        os.makedirs(assets_dir, exist_ok=True)
+        for fname, data in parser.media_bytes.items():
+            dest = os.path.join(assets_dir, fname)
+            with open(dest, 'wb') as f:
+                f.write(data)
+            print(f"  [image] assets/{fname}")
+
+    if gen.inferred_data_fields:
+        print(f"  Inferred data fields: {list(gen.inferred_data_fields.keys())}")
+    print(f"\nNext: run  node {os.path.basename(output_path)}")
+
+if __name__ == '__main__':
+    main()