Auditoria de Fidelidade PPTX ↔ HTML

Um fluxo de trabalho repetível para capturar as maneiras pelas quais uma exportação python-pptx se desvia silenciosamente de sua origem HTML — e corrigi-las com uma disciplina de layout que evita as mesmas regressões na próxima passagem.

Quando esta habilidade se aplica

O usuário tem:

• Um deck de slides HTML de origem (tipicamente um deck de arquivo único com blocos <section class="slide">):

  <section class="slide light">
    <div class="chrome">2026 · Q2 review</div>
    <span class="kicker">Pillar 03</span>
    <h2 class="h-xl">Shipping <em>velocity</em> doubled</h2>
    <p class="lead">…</p>
    <div class="foot">page 5 / 14</div>
  </section>
  

• Um arquivo PPTX gerado a partir desse deck via python-pptx (ou similar).

• Uma suspeita (ou evidência visível) de que o PPTX não corresponde ao HTML — texto invadindo o rodapé, palavras em itálico voltando ao normal, slides principais não centralizados, seções cortadas, estilo de tag perdido.

Se o usuário tiver apenas um desses dois artefatos, esta habilidade ainda não se aplica — primeiro gere o ausente, ou peça ao usuário para fornecê-lo.

Por que isso é difícil (e por que uma habilidade ajuda)

PPTX é um meio de tela fixa e posicionamento absoluto. HTML é um meio fluido e baseado em fluxo. Uma exportação python-pptx ingênua fixa cada bloco em coordenadas (top, left) escolhidas a dedo, o que funciona para o primeiro slide em que foi testado e falha silenciosamente para todos os outros slides cujo conteúdo tem altura intrínseca diferente. O resultado são os modos de desvio mais comuns:

1. Transbordamento do rodapé — a top + height do conteúdo invade a linha do rodapé.
2. Conteúdo fora da tela — a parte inferior do último bloco excede 7.5" (tela 16:9).
3. Perda de itálico — <em> em HTML nunca se torna run.font.italic = True.
4. Slides principais não centralizados — slides de pilha vertical usam MARGIN_TOP em vez de calcular o centro.
5. Limites da caixa invadindo — o texto cabe, mas a caixa delimitadora da forma é superdimensionada e visualmente invade a linha.
6. Perda de tag/estilo — linhas de cromo coloridas, espaçamento de letras maiúsculas de kicker, atribuições mono-vs-serif silenciosamente voltam aos padrões.

Cada um desses é um problema de disciplina de layout, não um problema de conteúdo. Uma vez que você adota a disciplina, eles param de acontecer.

Fluxo de Trabalho

A auditoria tem cinco etapas. Não pule nenhuma delas — a disciplina só funciona se a auditoria produzir uma lista real de problemas para direcionar a reexportação. Uma passagem de correção sem auditoria tende a deixar metade dos problemas ativos.

Etapa 1 — Extrair a verdade fundamental do PPTX

Execute scripts/extract_pptx.py <path-to.pptx> > pptx_dump.json. O script percorre cada forma em cada slide e despeja texto, posição (top / left), tamanho (width / height) e tipografia por execução (nome da fonte, tamanho em pt, negrito, itálico, cor). Este é o estado real da exportação — não confie na intenção do script de exportação, confie no despejo.

Para decks de 14 slides, o despejo tem ~30–60 KB e é legível por humanos.

Etapa 2 — Percorrer a estrutura HTML

Leia o HTML de origem e enumere os blocos <section class="slide">. Para cada um, anote:

• O tema do slide (light / dark / hero light / hero dark).
• O texto da linha chrome (metadados superiores).
• O kicker (pequena sobrancelha em maiúsculas acima do título).
• O título (h-hero / h-xl / etc.) e qualquer subtítulo.
• O corpo do texto e quaisquer blocos estruturados (etapas do pipeline, cartões, pilares, cartões de observação).
• A linha foot (metadados inferiores).
• Quaisquer spans em <em> ou com estilo itálico — itálico é a regressão silenciosa.

Mapeie cada slide HTML para um índice de slide PPTX. Para decks que seguem a convenção "slide 1 = capa, slide N = encerramento", o mapeamento é posicional.

Etapa 3 — Construir a tabela de auditoria

Para cada slide, percorra as formas do despejo e verifique contra as regras de layout esperadas. Use este formato de tabela exato — a coluna de severidade é o que direciona a prioridade de correção:

| Slide | Issue | Severity |
|---|---|---|
| 1 cover | meta-row 底端 6.95" 蓋過 footer (6.7") | 🔴 |
| 5 checklist | row B 步驟描述底端 7.2" 切到 footer | 🔴 |
| 8 3E | 收束段落直接坐在 footer 起點 | 🔴 |
| 9 on-day | step 描述底端剛好碰 footer，無安全距 | 🟠 |
| 多處 | em (Playfair italic) 未保留 | 🟡 |

Rubrica de severidade:

• 🔴 crítico — conteúdo cortado, texto invisível, sobreposição de rodapé, fora da tela. Deve corrigir.
• 🟠 alto — conteúdo visível, mas hierarquia visual quebrada, sem espaço para respirar, herói não centralizado. Deve corrigir.
• 🟡 médio — itálico/em ausente, fallback de fonte incorreto, desvio de cor. Corrigir nesta passagem.
• 🟢 baixo — espaçamento/alinhamento menor, deslocamentos de subpixel. Anotar, mas não bloquear.

…