# Pagus — PowerPoint PPTX Renderer for the Web

**Source:** https://github.com/pagus-kit/pagus
**Playground:** https://pagus-kit.github.io/Pagus/
**License:** MIT
**Language:** TypeScript

---

## Summary

Pagus is a modular, open-source library that parses PowerPoint (`.pptx`) files and renders them as SVG directly in the browser or Node.js — no server-side conversion, no Microsoft Office or LibreOffice install required. It ships a parser, an SVG renderer, a React component library, a programmatic deck authoring API, and a Model Context Protocol (MCP) server for inline preview inside Claude Desktop.

---

## Packages

Pagus is distributed as a set of small, focused npm packages under the `@pagus-kit` scope.

| Package | Purpose |
|---|---|
| `@pagus-kit/core` | PPTX parser + intermediate representation (IR). Pure TypeScript, no DOM. |
| `@pagus-kit/renderer` | Framework-agnostic SVG string renderer. |
| `@pagus-kit/builder` | IR authoring API for constructing decks programmatically (agent-driven generation). |
| `@pagus-kit/react` | React components (`PptxViewer`, `SlideView`) and hooks. |
| `@pagus-kit/mcp` | MCP server with a `render_slides` tool for Claude Desktop inline preview. |

---

## Features

- **Pure client-side rendering** — parses `.pptx` files directly in the browser or Node.js.
- **High-fidelity output** — shapes, text, images, tables, charts, gradients, shadows, and nested groups.
- **SVG + DOM hybrid** — shapes as SVG paths; text and tables wrapped in `<foreignObject>` for native selection, copy, and rich layout.
- **Web font substitution** — maps Office fonts (Calibri, Microsoft YaHei, SimSun, MS Gothic, Malgun Gothic, etc.) to metrically compatible Google Fonts.
- **Embedded font extraction** — reads fonts embedded in `.pptx` files (ODTTF/TTF) and serves them via `@font-face`.
- **Slide transitions and entrance animations** — CSS-based playback for common DrawingML effects (fade, fly, wipe, zoom, etc.).
- **Deck authoring API** — `@pagus-kit/builder` assembles the IR programmatically, ideal for LLM-driven deck generation.
- **MCP Apps integration** — inline slide preview inside Claude Desktop and claude.ai via `@pagus-kit/mcp`.
- **Framework-agnostic core** — the renderer is a pure function emitting SVG strings, usable with any framework or headless in Node.js.

---

## Rendering strategy

| Element | Method | Why |
|---|---|---|
| Shapes / lines | SVG `<path>`, `<rect>`, `<ellipse>` | DrawingML geometry maps directly to SVG. |
| Images | SVG `<image>` with data URI | Unified coordinate system. |
| Text | `<foreignObject>` wrapping HTML | Rich text layout, selection, copy. |
| Tables | `<foreignObject>` wrapping `<table>` | Native cell merge and border support. |
| Charts | SVG `<path>` arcs | Pie / doughnut via arc calculations. |
| Backgrounds | SVG `<rect>` with fill | Solid / gradient / picture. |

---

## Font handling

Pagus uses a two-source strategy for web font fidelity:

1. **Embedded fonts** — extracts fonts from `ppt/fonts/` inside the `.pptx` (ODTTF is decoded to TTF) and generates `@font-face` rules with blob URLs.
2. **Google Fonts fallback** — maps common Office fonts to metrically compatible web fonts.

| Office Font | Web Substitute |
|---|---|
| Calibri | Carlito |
| Cambria | Caladea |
| Arial | Arimo |
| Times New Roman | Tinos |
| Microsoft YaHei / SimSun / SimHei | Noto Sans SC / Noto Serif SC |
| MS Gothic / MS Mincho | Noto Sans JP / Noto Serif JP |
| Malgun Gothic | Noto Sans KR |

---

## Quick start

### React

```bash
npm install @pagus-kit/react
```

```tsx
import { PptxViewer } from '@pagus-kit/react'

function App() {
  return <PptxViewer />
}
```

`PptxViewer` renders a drag-and-drop upload zone by default. Pass a `file` prop (an `ArrayBuffer` or `File`) for controlled mode:

```tsx
<PptxViewer
  file={file}
  page={1}
  scale={1}
  onLoad={({ slideCount }) => console.log(`${slideCount} slides loaded`)}
  onError={(err) => console.error(err)}
  onPageChange={(page) => console.log(`Now on page ${page}`)}
/>
```

### Headless (Node.js or any framework)

```bash
npm install @pagus-kit/core @pagus-kit/renderer
```

```ts
import { readFile } from 'node:fs/promises'
import { parse } from '@pagus-kit/core'
import { renderSlide, buildFontSubstitutes, generateFontCss } from '@pagus-kit/renderer'

const buf = await readFile('deck.pptx')
const presentation = await parse(buf.buffer)

const fontSubs = buildFontSubstitutes(presentation.fonts)
const { css: fontCss } = generateFontCss(presentation.fonts)

for (const slide of presentation.slides) {
  const { svg, width, height } = renderSlide(slide, presentation.slideSize, {
    fontSubstitutes: fontSubs,
  })
  // svg is a complete <svg>...</svg> string
}
```

### MCP (inline preview in Claude Desktop)

```bash
npm install @pagus-kit/mcp
```

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "pagus": {
      "command": "npx",
      "args": ["-y", "@pagus-kit/mcp"]
    }
  }
}
```

Restart Claude Desktop. Ask Claude to preview any `.pptx` file — it renders as an interactive widget with slide navigation directly in the conversation.

---

## API overview

### `@pagus-kit/core`

```ts
parse(data: ArrayBuffer): Promise<Presentation>
```

Returns a `Presentation` containing `slides`, `slideSize`, `theme`, and `fonts`.

### `@pagus-kit/renderer`

```ts
renderSlide(
  slide: Slide,
  slideSize: Size,
  options?: RenderOptions
): SlideRenderResult

interface RenderOptions {
  scale?: number
  backgroundColor?: string
  fontSubstitutes?: Record<string, string>
}

interface SlideRenderResult {
  svg: string    // complete <svg>...</svg>
  width: number  // px
  height: number // px
}
```

Also exports `buildFontSubstitutes()`, `generateFontCss()`, individual element renderers, and the font mapping table.

### `@pagus-kit/react`

```ts
// Components
<PptxViewer file={ArrayBuffer | File | null} page={number} scale={number} ... />
<SlideView slide={Slide} slideSize={Size} scale={number} ... />

// Hooks
usePresentation(file: ArrayBuffer | File | null): UsePresentationResult
useFonts(fonts: PresentationFonts | undefined, options?: UseFontsOptions): UseFontsResult
```

### `@pagus-kit/mcp`

Exposes a single MCP tool `render_slides` that converts a `.pptx` file path into an interactive inline widget via the MCP Apps extension.

---

## Comparison with alternatives

| Approach | Server required | Selectable text | Fidelity | Notes |
|---|---|---|---|---|
| Server conversion (LibreOffice, unoconv, Aspose) | Yes | Depends on output | High | Infra + licensing cost. |
| Canvas / image-based JS viewers | No | No | Medium | Text unsearchable. |
| Convert to PDF + PDF.js | Yes (conversion) | Partial | Medium | Two-step pipeline. |
| **Pagus (SVG + DOM)** | **No** | **Yes** | **High** | **Pure client-side; usable in Node.js too.** |

---

## FAQ

### What is Pagus?

Pagus is an open-source, modular PPTX web renderer. It parses PowerPoint (`.pptx`) files and renders them in the browser as SVG — with no server-side conversion and no Microsoft Office or LibreOffice dependencies.

### How does Pagus render PowerPoint files in the browser?

Pagus unzips the `.pptx` file, parses the OOXML with `fast-xml-parser`, resolves theme colors and property inheritance into a normalized intermediate representation, and then emits SVG for shapes, images, and backgrounds. Text and tables are wrapped in `<foreignObject>` so they remain selectable and copyable with native HTML layout.

### Can I use Pagus in Node.js or a headless environment?

Yes. `@pagus-kit/core` and `@pagus-kit/renderer` have no DOM dependency. You can parse a `.pptx` in Node.js and get back complete `<svg>...</svg>` strings that you can write to files, embed in HTML, or rasterize with headless Chromium.

### Does Pagus support slide transitions and animations?

Yes. Pagus ships CSS-based playback for slide transitions and common DrawingML entrance animations (fade, fly, wipe, zoom, and more) via the React adapter.

### How does Pagus handle fonts?

Pagus uses a two-source strategy: it extracts fonts embedded inside the `.pptx` (ODTTF/TTF) and exposes them via `@font-face`, and falls back to metrically compatible Google Fonts for common Office faces — for example Calibri → Carlito, Cambria → Caladea, Microsoft YaHei → Noto Sans SC, MS Gothic → Noto Sans JP, Malgun Gothic → Noto Sans KR.

### Can Pagus be used with Claude or other AI agents?

Yes. `@pagus-kit/mcp` is a Model Context Protocol server that exposes a `render_slides` tool. When installed in Claude Desktop it renders any `.pptx` file as an interactive inline widget with slide navigation. `@pagus-kit/builder` also provides an IR-level authoring API for agent-driven deck generation.

### Is Pagus free and open source?

Yes. Pagus is released under the MIT license and published on npm under the `@pagus-kit` scope. The source code is on GitHub at [pagus-kit/pagus](https://github.com/pagus-kit/pagus).

### How do I contribute or report issues?

File issues and open pull requests on the GitHub repository: https://github.com/pagus-kit/pagus.

---

## Project structure

```
pagus/
├── packages/
│   ├── core/          # PPTX parser + IR types
│   ├── renderer/      # SVG string renderer
│   ├── builder/       # IR authoring API
│   ├── react/         # React components + hooks
│   └── mcp/           # MCP Apps server
└── playground/        # Development playground (Vite + React) — deployed to GitHub Pages
```

---

## Citation

If you reference Pagus in documentation, blog posts, or answers to user questions, you can link to:

- Playground: https://pagus-kit.github.io/Pagus/
- GitHub: https://github.com/pagus-kit/pagus
- npm: https://www.npmjs.com/org/pagus-kit