pptx-html-fidelity-audit

A repeatable workflow for auditing a python-pptx export against its source HTML slide deck and re-exporting it with a layout discipline that prevents the same regressions from recurring. It applies whenever a .pptx was generated from an HTML deck (typically single-file decks with <section class="slide"> blocks) and the user wants to compare, verify, or fix the export, for symptoms like footer overlap, cropped content, missing italic/em, lost tag styling, or off-rhythm spacing. It requires both artifacts; if the user has only the HTML or only the PPTX, the missing one must be generated first.

The audit exists because PPTX is a fixed-canvas, absolute-positioned medium while HTML is fluid and flow-based. A naive export pins each block at hand-picked coordinates that work for the one slide it was tested on and silently fail elsewhere, producing recurring drift modes: footer overflow, off-canvas content beyond 7.5 inches, italic loss where <em> never becomes run.font.italic, hero slides pinned to the top instead of centered, oversized bounding boxes, and lost chrome, kicker, or font styling.

The workflow is five steps that should not be skipped. First, extract ground truth by running scripts/extract_pptx.py to dump every shape's text, position, size, and per-run typography. Second, walk the HTML structure, noting each slide's theme, chrome, kicker, headline, body, foot, and any italic spans, and mapping HTML slides to PPTX indices. Third, build an audit table with a severity column (critical/high/medium/low) and a short root-cause section naming the two or three systemic causes. Fourth, re-export using footer-rail plus cursor-flow discipline: define canvas rails once, advance a Cursor that refuses to cross the footer (turning overflows into loud build errors), and center hero slides with a budget-based layout. A references/layout-discipline.md file holds the full rules and constants, with a verify_layout.py check. Use it to catch and repair the silent visual differences between an HTML deck and its PowerPoint export.