# 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.