# Presentations Guide — Agent Instructions
Instructions for building HTML slide decks in the Fractal system and exporting them to PowerPoint.
Decks are a **fixed 1920×1080 HTML canvas** — not responsive app surfaces. They are authored as static HTML, previewed in the browser, then exported to `.pptx` by the user's `gen_pptx` tool.
---
## Core rules
Two rules govern every deck. Violate either and the export breaks.
### 1. HTML first, always
**Always build and preview the deck as HTML before exporting.** Never generate PPTX directly. The export tool captures what the browser renders — if the deck is broken in the browser, the `.pptx` will be broken too.
Workflow:
1. Author the deck as a single HTML file starting from `starter.html`.
2. `show_to_user` the file so the user can see it rendered.
3. Iterate on content + layout in HTML.
4. Only when the deck looks correct in the browser, call `gen_pptx`.
### 2. Self-contained, always
**A deck is a single HTML file with every style and script inlined.** No ``. No `
```
`gen_pptx` reads this automatically and attaches each string to its matching slide. Keep notes plain text — no HTML, no markdown. One paragraph per slide is plenty.
---
## `` reference
`` is a vanilla custom element that wraps the deck, scales the 1920×1080 canvas to fit the viewport, handles navigation, and cooperates with the export tool. Slides must be **direct children** of `` — it toggles `data-deck-active` on them.
### Attributes
| Attribute | Default | Effect |
| ----------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `width` | `1920` | Canvas width in px. |
| `height` | `1080` | Canvas height in px. |
| `active` | `0` | 0-indexed active slide; reflects through `goTo`. |
| `loop` | (off) | `next`/`prev` wrap at deck ends. |
| `presenter` | (off) | Opt in to single-slide presenter mode (scaled to viewport, centered, chrome visible, keyboard nav). Without it, the default is scrollable stacked. |
| `nochrome` | (off) | Force-hide chrome (tap zones, progress, counter). Only meaningful in presenter mode; in the default mode chrome is already hidden. Required for screenshot-mode export. |
| `noscale` | (off) | Single-slide natural-size mode for export. Overrides both `presenter` and the scrollable default. `gen_pptx` editable export sets this automatically via `resetTransformSelector: "deck-stage"`. |
### Methods
| Method | Description |
| ------------------- | ----------------------------------------------------------------------------- |
| `goTo(n)` | Navigate to slide `n` (0-indexed). Clamps to valid range (wraps with `loop`). |
| `next()` / `prev()` | Convenience around `goTo`. |
| `count` (getter) | Number of direct-child slides. |
### Events (bubble + composed)
| Event | Detail | Fired |
| --------------------- | ---------------------------- | ------------------------------------------------------ |
| `deck-ready` | — | After `document.fonts.ready` resolves (or at timeout). |
| `deck-change` | `{ index, total, previous }` | On every `goTo` call. |
| `deck-noscale-change` | `{ on }` | When the `noscale` attribute toggles. |
### Keyboard
| Keys | Action |
| ----------------------------- | ------------------------- |
| `→`, `Space`, `PageDown`, `n` | Next |
| `←`, `PageUp`, `p` | Previous |
| `Home` / `End` | First / last |
| `1`–`9` | Jump to slide (1-indexed) |
| `f` | Toggle fullscreen |
The host element is focusable (`tabindex="0"` set automatically). Click the deck once to give it focus before keyboard nav works.
### Rendering modes
The default is a **scrollable stacked view**: all slides visible, each scaled by CSS `zoom` to fit the host width. This is the right choice for preview viewers, chat sidebars, embedded iframes, and any context narrower than a full window. It's also what the no-JS fallback renders — so the deck looks the same whether `` successfully upgrades as a custom element or not. That matters because many file previewers (macOS Quick Look, IDE hover previews, some chat sidebars) don't execute JavaScript at all.
For a full-screen talk or a dedicated deck viewer, add `presenter`:
```html
……
…
```
Presenter mode shows one slide at a time at fit-to-viewport scale, centered, with chrome (counter, progress bar, tap zones) and keyboard navigation (`→` / `←` / `Space` / `1`–`9` / `f` for fullscreen).
Either mode authors the same way — same `.slide` templates, tokens, typography. The attribute only changes layout.
#### Export always wins
`noscale` (set by `gen_pptx` editable export via `resetTransformSelector: "deck-stage"`) overrides both modes and forces single-slide natural-size rendering. Decks are still exportable from either authoring mode with the same arg shape shown below.
#### Browser support
Both default scrollable mode and the no-JS fallback use CSS `zoom` (all current browsers since Firefox 126 / May 2024) + container query units `100cqw` (all current browsers since 2022). If your target includes browsers older than mid-2024, add `presenter` to force single-slide mode, which only relies on `transform: scale` (supported everywhere).
### Verifying the deck
Before reporting a deck complete:
1. Open the HTML in a **full browser** (Chrome / Safari / Firefox) and confirm the scrollable view renders — all slides visible, each scaled to the window width, scroll to navigate. This confirms the `.slide` CSS loaded and the custom element upgraded.
2. If the deck will be viewed in a JS-restricted file previewer (macOS Quick Look, IDE previews, some chat sidebars), the `:not(:defined)` fallback should render the same scrollable view. A truly blank page in such a viewer means the `.slide` CSS didn't load — usually because the deck was hand-written without the bundled styles. Rebuild from `starter.html`.
3. To verify presenter mode, add `presenter` to `` temporarily (or via DevTools: `$0.setAttribute('presenter','')`) and confirm keyboard nav + centered single-slide rendering. Remove before shipping unless presenter is the deck's intended default.
---
## PPTX export workflow
Two modes. Two ways to invoke them:
- **Agent harness `gen_pptx` tool** — if your agent environment provides it, use that. The definitive reference is the user's own two guides (`Export as PPTX (editable).md` and `Export as PPTX (screenshots).md`).
- **Local fallback CLI** — this repo ships a reference implementation at [`scripts/gen-pptx.js`](../../scripts/gen-pptx.js) that produces matching output using Playwright + pptxgenjs. See "Local fallback" below.
Both paths accept the same arg shape. The shapes below apply to either.
### Editable mode (default — editable text + shapes)
```jsonc
{
"width": 1920,
"height": 1080,
"resetTransformSelector": "deck-stage",
"slides": [
{
"showJs": "document.querySelector('deck-stage').goTo(0)",
"selector": "deck-stage > [data-deck-active]",
},
{
"showJs": "document.querySelector('deck-stage').goTo(1)",
"selector": "deck-stage > [data-deck-active]",
},
// …one entry per slide in DOM order
],
"filename": "my-deck",
}
```
Notes:
- `resetTransformSelector: "deck-stage"` sets the `noscale` attribute on the host; `` drops its scale transform in response. Don't fight it.
- Shadow-DOM chrome (tap zones, progress, counter) is not captured in editable mode.
- Omit `googleFontImports` and `fontSwaps` — see "Fonts" below.
### Screenshot mode (pixel-perfect, non-editable)
```jsonc
{
"mode": "screenshots",
"width": 1920,
"height": 1080,
"slides": [
{
"showJs": "document.querySelector('deck-stage').setAttribute('noscale',''); document.querySelector('deck-stage').setAttribute('nochrome',''); document.querySelector('deck-stage').goTo(0)",
"selector": "body",
},
{
"showJs": "document.querySelector('deck-stage').goTo(1)",
"selector": "body",
},
// …
],
"filename": "my-deck",
}
```
**Critical:** the first slide's `showJs` must set both `noscale` and `nochrome` on ``. Without `noscale`, the default scrollable rendering would capture the _top of the stacked view_ instead of slide N. Without `nochrome`, the tap zones, progress bar, and counter appear in the exported PNGs.
### Fonts
The default in this design system is **brand fonts as-is** (Avenir Next + Geist Mono). Omit `googleFontImports` and `fontSwaps`. `starter.html` already inlines `@font-face` declarations pointing at the hosted font files on `design.mirrorphysics.com`, with `system-ui` fallback in `--font-sans` so the deck renders legibly even if the font host is unreachable.
If the deck's audience won't have the brand fonts available and you need fallbacks in the exported `.pptx`, pass the standard strategies described in the user's `Export as PPTX (editable).md` font-strategy section.
### Local fallback
If your agent environment doesn't provide `gen_pptx`, use the bundled CLI. It's a Node reference implementation (Playwright + pptxgenjs) that matches the arg shape above.
**With repo access** (you cloned or downloaded the repo):
```bash
npm install # if you haven't already
npx playwright install chromium
npm run gen-pptx -- path/to/deck.html --mode editable --output deck.pptx
# or
npm run gen-pptx -- path/to/deck.html --mode screenshots --output deck.pptx
```
**Standalone** (no repo access — grab the single file and run it anywhere):
```bash
curl -O https://design.mirrorphysics.com/scripts/gen-pptx.js
npm init -y
npm install pptxgenjs playwright
npx playwright install chromium
node gen-pptx.js path/to/deck.html --mode editable
```
CLI flags (see the top of `scripts/gen-pptx.js` for full docs):
| Flag | Default | Use |
| ------------------ | --------------------- | ------------------------------- |
| `--mode` | `editable` | `editable` or `screenshots` |
| `--output` | `.pptx` | Output file path |
| `--width` | `1920` | Canvas width in px |
| `--height` | `1080` | Canvas height in px |
| `--slide-selector` | `deck-stage > .slide` | CSS selector for slide elements |
| `--verbose` | off | Log per-slide progress |
Behavior parity with harness `gen_pptx`:
- Sets `noscale` on `` before editable export so the canvas renders at natural 1920×1080.
- Calls `goTo(N)` between slides; waits for `document.fonts.ready` before each capture.
- Reads speaker notes from `