tools: preserve HTML deck exporter

2026-08-31 15:59:51 +02:00
parent e82fe8d322
commit 218e50f124
5 changed files with 501 additions and 0 deletions
@@ -0,0 +1,86 @@
+# HTML deck to PPTX
+
+This tool renders a ThothII HTML deck as one full-bleed PNG per slide and assembles
+those images into a 16:9 PowerPoint file with native speaker notes and document
+metadata. The HTML and notes JSON under `presentations/` are the editable sources;
+the PPTX is a rendered release artifact.
+
+Using images preserves the web typography and fine CSS details across machines. The
+tradeoff is that slide text is not editable in PowerPoint. Speaker notes remain native
+and editable.
+
+## Requirements
+
+- Node.js 18 or newer and npm.
+- Playwright's Chromium build.
+- Network access while rendering the current deck, because its Fraunces and Manrope
+  fonts are loaded from Google Fonts. The render is therefore not fully hermetic.
+
+Install the locked JavaScript dependencies and Chromium from the repository root:
+
+```bash
+npm ci --prefix tools/html-to-pptx
+npx --prefix tools/html-to-pptx playwright install chromium
+```
+
+Dependencies are local to this tool. The scripts intentionally do not use globally
+installed npm packages.
+
+## Render slides
+
+Use a dedicated render directory. The renderer removes stale files matching
+`NN.png`, writes fresh slide images, and creates a raw `notes.json` containing the
+title extracted from each slide.
+
+```bash
+npm --prefix tools/html-to-pptx run render -- \
+  presentations/<deck>.html <render-dir> \
+  --hide ".hud button,.hint"
+```
+
+The HTML deck must expose `.slide` elements activated by `#N` hash routes. Optional
+rendering flags are `--scale`, `--width`, and `--height`; their defaults are `2`,
+`1600`, and `900`.
+
+## Build the PowerPoint file
+
+Keep refined speaker notes in `presentations/<deck>.notes.json`, using the shape
+`{"1": "...", "2": "..."}`. Pass that file instead of the raw titles generated
+during rendering:
+
+```bash
+npm --prefix tools/html-to-pptx run build -- \
+  <render-dir> presentations/<deck>.pptx \
+  --notes presentations/<deck>.notes.json \
+  --title "..." --author "..." --subject "..."
+```
+
+The output uses the wide PowerPoint layout (13.333 x 7.5 inches), with one image per
+slide. Edit the HTML and rebuild whenever slide content changes.
+
+## Validation
+
+Run the syntax checks with:
+
+```bash
+npm --prefix tools/html-to-pptx test
+```
+
+Before publishing a regenerated deck, inspect at least one PNG at full resolution and
+use `python-pptx` to verify the slide count, the 12192000 x 6858000 EMU page size, and
+one picture per slide. `python-pptx` is an optional, currently unpinned QA dependency;
+it is not needed to render or build the deck.
+
+The locked direct dependencies are Playwright 1.58.0 (Apache-2.0) and PptxGenJS
+3.12.0 (MIT). Their transitive versions and integrity hashes are recorded in
+`package-lock.json`.
+
+### Temporary dependency exception
+
+PptxGenJS 3.12.0 declares `image-size` 1.2.1, which npm flags for the availability-only
+[GHSA-w3rx-r6r6-pgpr](https://github.com/advisories/GHSA-w3rx-r6r6-pgpr) and
+[GHSA-5p2g-fcmc-qvqq](https://github.com/advisories/GHSA-5p2g-fcmc-qvqq) advisories. No patched
+`image-size` release exists as of 2026-08-31, and current PptxGenJS releases retain the dependency.
+The affected parser is not imported by PptxGenJS's published builder path used here; this tool also
+accepts only locally generated PNG slides with explicit dimensions. Do not use it with untrusted
+image inputs. Reassess this exception by 2026-11-29, or sooner when a patched dependency is released.