Podium

Slide decks as declarative JavaScript. Preview live in the browser, export real, editable PowerPoint files. Built so AI agents can write your slides.

// decks/hello/index.js
import { theme, resolveSlide } from "podium-pptx";

const slide = {
  id: "hello",
  layout: "title",
  layoutProps: { title: "Hello", subtitle: "This slide is a JavaScript object." },
};

export const name = "Hello";
export const slides = [slide].map((s) => resolveSlide(s, theme));

npx podium-pptx dev                                # live preview, hot reload
npx podium-pptx export --deck hello --pptx out.pptx  # real .pptx out

Why

Slide tools make you draw. Podium makes you describe: a slide is a tree of data (text, shapes, tables, icons, flexbox-style stacks) rendered by React for preview and rebuilt as native PowerPoint objects on export. That gives you three things:

• Decks that regenerate. Data-backed decks (scorecards, dashboards, status reports) rebuild themselves when the data changes.
• Real PPTX out. Every text box, table and shape in the export is editable in PowerPoint. Podium builds the structured 90% and you hand-polish the rest in PowerPoint if you want.
• AI-writable slides. A slide is a data structure, and models are very good at writing data structures. Point a coding agent at docs/authoring-guide.md, describe your deck, review it in the live preview.

Quick start (this repo)

git clone https://github.com/estherholleman/podium
cd podium
npm install
npm run dev        # opens the deck picker with the example decks

The example decks live in decks/: demo is a self-describing tour (every slide is built with the feature it explains), engine-primitives exercises paths and stack borders.

Quick start (your own repo)

npm install podium-pptx
npx podium-pptx init    # scaffolds decks/hello/ with a starter deck + next steps
npx podium-pptx dev

Any folder under decks/ with an index.js exporting slides is discovered automatically. name, description and a full theme override are optional exports.

Exporting

Export runs headless and needs Playwright's Chromium once:

npx playwright install chromium

Then:

npx podium-pptx export --deck demo --pptx out/demo.pptx   # PPTX
npx podium-pptx export --deck demo --png out/demo/        # slide-NN.png per slide
npx podium-pptx export --all --out out/                   # everything + manifests
npx podium-pptx list                                      # what's here?

You can also export from the browser preview (the PPTX button in the top bar), or programmatically:

import { openPodium } from "podium-pptx/node";
const podium = await openPodium();
const buffer = await podium.exportPptx("demo");
await podium.close();

How the export works

The browser is the layout engine. On export, every slide is rendered in a hidden container, real geometry is measured with getBoundingClientRect(), stacks are flattened to absolute coordinates, and pptxgenjs writes native PowerPoint objects at those measured positions. What fits in the preview fits in the file. Details in docs/architecture.md.

Writing slides

The full element API (9 element types, 7 layout presets, patterns, gotchas) is in docs/authoring-guide.md, written to be pasted straight into an AI agent's context. It ships inside the package, so in a consumer repo it lives at node_modules/podium-pptx/docs/authoring-guide.md.

For AI agents

Podium is designed to be driven by coding agents: slides are plain data structures, the CLI is scriptable, and every command that produces results has a --json flag. The intended loop:

1. The agent reads node_modules/podium-pptx/docs/authoring-guide.md (shipped in the package) and writes deck files under decks/.
2. npx podium-pptx export --deck X --png out/ gives the agent per-slide PNGs to review, so it can iterate on its own output.
3. npx podium-pptx export --deck X --pptx out.pptx produces the deliverable.

If you use an agent harness with reusable instructions (Claude Code skills, Cursor rules, AGENTS.md), point one at the authoring guide so every session knows the element API without being told.

Theming

The default theme lives in src/theme.js (semantic colors, fonts, canvas size). A deck overrides it by exporting its own theme object of the same shape from its index.js. The PPTX export uses Arial for maximum portability; change PPTX_FONT in src/export/pptx-renderer.js if your brand ships a licensed Office font.

Tests

The repo guards rendering with golden fixtures: npm run golden:capture renders every example deck to PPTX + per-slide PNGs, npm run golden:compare diffs a fresh export against the committed fixtures (PNG pixel diff + PPTX geometry extraction).

License

MIT