chore: preserve presentation sources and exporter

2026-08-31 15:35:35 +02:00
parent 11f78c4467
commit 919d408c81
9 changed files with 1211 additions and 0 deletions
@@ -0,0 +1,72 @@
+---
+name: html-to-pptx
+description: Convert the ThothII HTML slide decks in presentations/ into a pixel-faithful PowerPoint (.pptx) and re-export after edits. Use whenever the user mentions pptx, PowerPoint, Keynote import, "esporta in PowerPoint", "converti le slide", or wants the deck in Office format while keeping the exact look and feel of the HTML version.
+---
+
+# HTML deck → PPTX (pixel-faithful)
+
+The decks in `presentations/*.html` are the editable source of truth. The PPTX is a
+rendered artifact: one full-bleed, high-resolution PNG per slide inside a 13.33×7.5in
+(16:9) deck, plus native speaker notes and document metadata.
+
+**Why images instead of native PowerPoint shapes:** the decks depend on web fonts
+(Fraunces, Manrope) and hairline CSS details that PowerPoint silently substitutes on
+any machine without those fonts installed. Rendering bakes the fonts into pixels, so
+the file projects identically everywhere. The tradeoff: slide text is not editable in
+PowerPoint. To change a slide, edit the HTML, then re-export here. Speaker notes stay
+native and editable.
+
+## Pipeline
+
+Run from the repo root. The scripts resolve `playwright`/`pptxgenjs` from this
+skill's own `node_modules`, falling back to `npm -g`:
+
+1. **Render** every slide to PNG (2× ≈ 240dpi) and auto-extract per-slide titles:
+
+   ```bash
+   node .agents/skills/html-to-pptx/scripts/render.mjs \
+     presentations/<deck>.html <tmpdir> --hide ".hud button,.hint"
+   ```
+
+   `--hide` takes a comma-separated selector list for browser-only chrome (nav
+   buttons, keyboard hints) that must not be baked into a static file. The renderer
+   assumes the deck exposes `.slide` sections navigable via `#N` hash routes (the
+   ThothII deck does).
+
+2. **Build** the deck:
+
+   ```bash
+   node .agents/skills/html-to-pptx/scripts/build.mjs \
+     <tmpdir> presentations/<deck>.pptx \
+     --notes presentations/<deck>.notes.json \
+     --title "..." --author "..." --subject "..."
+   ```
+
+   `render.mjs` writes a raw `<tmpdir>/notes.json` (slide titles); keep the refined,
+   speaker-ready notes in `presentations/<deck>.notes.json` (same shape:
+   `{"1": "...", "2": "..."}`) and pass it with `--notes`. Notes are in Italian,
+   2-4 speakable sentences per slide, and are the only editable text in the PPTX.
+
+## QA before handing over
+
+- python-pptx walk: reopen the file, assert slide count equals the PNG count, slide
+  size equals 12192000×6858000 EMU (13.333×7.5in), and every slide carries exactly
+  one picture plus (optionally) a notes slide. Report file size.
+- Spot-check one PNG at full size: crisp text, no clipping, serif headlines
+  (Fraunces) and sans body (Manrope) clearly rendered, no browser buttons visible.
+
+## Requirements (first run only)
+
+```bash
+npm install --prefix .agents/skills/html-to-pptx
+npx --prefix .agents/skills/html-to-pptx playwright install chromium  # only if launch fails
+```
+
+QA needs `python-pptx` (any venv: `python3 -m venv /tmp/pptxqa && /tmp/pptxqa/bin/pip install python-pptx`).
+
+## When NOT to use this skill
+
+If the user needs natively editable PowerPoint objects (they will rewrite slide text
+inside PowerPoint), build the deck with the `document-skills:pptx` skill instead and
+accept the font-substitution risk. Do not silently mix the two outputs: pick one,
+state the tradeoff, and deliver one file.